pikuri-core 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b9d64fe3a6b311841de49b193f6caa92cdb2ba0e627ef0195c73824d803fcafa
+  data.tar.gz: fa1112813faf7c4d6d162d467b4977c7b800bc647d35c0fe6fec79a1f30e6112
+SHA512:
+  metadata.gz: f9b5618853d0501a417fbcfd021e1dd65fe45fef42331d9f8b4f1c8ab273a91437f433b7065512b46340d98670e53127cb49a5149eb7078750bd99a0e6ad22fa
+  data.tar.gz: a9ce6040b23bcd4a2eb4f11bc10c50cd64ad8fdba685e2eba51f9181a3f3503617adb230b0601257e3f0ec3122c14d1a12b5091ab03b7612f906d72c54938189

data/README.md

@@ -0,0 +1,67 @@
+# pikuri-core
+
+The lean, audit-friendly foundation of the [pikuri](https://codeberg.org/mvysny/pikuri)
+AI-assistant toolkit:
+
+- `Pikuri::Agent` — a thin wrapper around ruby_llm's chat loop with
+  the Configurator + Extension protocol for hosts to wire extra
+  capabilities into an agent.
+- `Pikuri::Tool` framework with strict argument validation
+  (`Pikuri::Tool::Parameters`) and LLM-actionable error messages.
+- Listener stream (`Pikuri::Agent::Listener::*`) for rendering,
+  token accounting, and structured capture.
+- Controls (`StepLimit`, `Cancellable`, `Interloper`) for budget
+  enforcement + cancellation.
+- Four stateless bundled tools: `CALCULATOR`, `WEB_SEARCH`,
+  `WEB_SCRAPE`, `FETCH`.
+- A demo binary, `bin/pikuri-chat`.
+
+Extensions (skills, MCP, workspace, coding stack, named-agent
+personas) live in sibling gems and opt in à la carte — see
+[`pikuri-skills`](../pikuri-skills/README.md),
+[`pikuri-mcp`](../pikuri-mcp/README.md),
+[`pikuri-workspace`](../pikuri-workspace/README.md),
+[`pikuri-code`](../pikuri-code/README.md),
+[`pikuri-assistant`](../pikuri-assistant/README.md). For the
+convenience bundle that pulls in everything, see the
+[`pikuri`](../pikuri/README.md) metagem.
+
+## Install
+
+```ruby
+# Gemfile
+gem 'pikuri-core'
+```
+
+```sh
+gem install pikuri-core
+```
+
+## Minimal usage
+
+```ruby
+require 'pikuri-core'
+
+RubyLLM.configure do |c|
+  c.openai_api_base = 'http://localhost:8080/v1'
+  c.openai_api_key  = 'not-needed'
+end
+
+agent = Pikuri::Agent.new(
+  transport: Pikuri::Agent::ChatTransport.new(
+    model: 'unsloth/Qwen3.6-35B-A3B-GGUF',
+    provider: :openai,
+    assume_model_exists: true
+  ),
+  system_prompt: Pikuri.prompt(:'pikuri-chat'),
+  step_limit: Pikuri::Agent::Control::StepLimit.new(max: 20)
+) do |c|
+  c.add_tool Pikuri::Tool::CALCULATOR
+  c.add_tool Pikuri::Tool::WEB_SEARCH
+  c.add_listener Pikuri::Agent::Listener::Terminal.new
+end
+agent.run_loop(user_message: 'What is 17 * 23?')
+```
+
+See `bin/pikuri-chat` for a worked example with REPL, signal
+handling, and cancellation.

data/lib/pikuri/agent/chat_transport.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Agent
+    # The trio of arguments that has to travel together to +RubyLLM.chat+
+    # for model resolution to come out the same on every construction:
+    # the model id, the provider hint, and the registry-bypass flag.
+    #
+    # Bundling them is structural protection against a recurring bug
+    # class — every forwarding site (the synthesizer rescue in
+    # {Agent#run_loop}, {Tool::SubAgent} spawning a sub-agent) used to
+    # pass the three individually, and dropping one routed the spawned
+    # 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.
+    #
+    # 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
+    # @!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.
+    # @!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+.
+    class ChatTransport < Data.define(:model, :provider, :assume_model_exists)
+      # @param model [String, nil]
+      # @param provider [Symbol, nil]
+      # @param assume_model_exists [Boolean]
+      def initialize(model:, provider: nil, assume_model_exists: false)
+        super
+      end
+    end
+  end
+end

data/lib/pikuri/agent/configurator.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+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, and extension instances; {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:
+    #
+    #   Pikuri::Agent.new(transport: ..., system_prompt: ...) do |c|
+    #     c.add_listener Pikuri::Agent::Listener::Terminal.new
+    #     c.add_tool     Pikuri::Tool::CALCULATOR
+    #     c.add_extension Pikuri::Skill::Extension.new(catalog: catalog)
+    #   end
+    #
+    # 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
+    #
+    # 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.
+    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).
+      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.
+      attr_reader :system_prompt_base
+
+      # @return [String] this agent's identifier; empty for the main
+      #   agent, hierarchical (+"sub_agent 0_1"+) for sub-agents.
+      attr_reader :name
+
+      # @return [Boolean] +true+ when the agent opted into chunk-level
+      #   streaming.
+      attr_reader :streaming
+
+      # @return [Control::StepLimit, nil] step-budget control passed
+      #   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.
+      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}.
+      attr_reader :tools
+
+      # @return [Array<Listener::Base>] listeners added via
+      #   {#add_listener}, in declaration order. Drained by
+      #   {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 and calls +bind(self)+ on each after
+      #   wiring is complete.
+      attr_reader :extensions
+
+      # @return [SubAgentRequest, nil] set when the block called
+      #   {#allow_sub_agent}; +nil+ otherwise. The Agent ctor uses
+      #   this to decide whether to create a {Tool::SubAgent}
+      #   instance after the chat is wired (so the SubAgent tool's
+      #   parent.tools snapshot doesn't include itself —
+      #   recursion guard).
+      attr_reader :sub_agent_request
+
+      # Record holding the +max_steps+ value the host passed to
+      # {#allow_sub_agent}. The Agent ctor consumes one of these
+      # records to build a {Tool::SubAgent} keyed to that step
+      # budget.
+      SubAgentRequest = Data.define(:max_steps)
+
+      # @param transport [Agent::ChatTransport]
+      # @param system_prompt_base [String]
+      # @param name [String]
+      # @param streaming [Boolean]
+      # @param step_limit [Control::StepLimit, nil]
+      # @param cancellable [Control::Cancellable, nil]
+      # @param interloper [Control::Interloper, nil]
+      def initialize(transport:, system_prompt_base:, name:, streaming:,
+                     step_limit:, cancellable:, interloper:)
+        @transport = transport
+        @system_prompt_base = system_prompt_base
+        @name = name
+        @streaming = streaming
+        @step_limit = step_limit
+        @cancellable = cancellable
+        @interloper = interloper
+
+        @tools = []
+        @listeners = []
+        @system_prompt_additions = []
+        @on_close_handlers = []
+        @extensions = []
+      end
+
+      # Append a tool to the agent's static tool list.
+      #
+      # @param tool [Tool]
+      # @return [void]
+      def add_tool(tool)
+        @tools << tool
+        nil
+      end
+
+      # Append several tools at once. Equivalent to calling {#add_tool}
+      # for each element of +tools+; declaration order is preserved.
+      # Sole intended caller today is {Tool::SubAgent}, which seeds a
+      # sub-agent's Configurator from the parent's tool snapshot.
+      #
+      # @param tools [Enumerable<Tool>]
+      # @return [void]
+      def add_tools(tools)
+        tools.each { |t| @tools << t }
+        nil
+      end
+
+      # Append a listener to the agent's listener list.
+      #
+      # @param listener [Listener::Base]
+      # @return [void]
+      def add_listener(listener)
+        @listeners << listener
+        nil
+      end
+
+      # Append several listeners at once. Accepts any enumerable
+      # (Array, {ListenerList}, …); declaration order is preserved.
+      # Sole intended caller today is {Tool::SubAgent}, which seeds a
+      # sub-agent's Configurator from the parent's listener list (run
+      # through {ListenerList#for_sub_agent}).
+      #
+      # @param listeners [Enumerable<Listener::Base>]
+      # @return [void]
+      def add_listeners(listeners)
+        listeners.each { |l| @listeners << l }
+        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(agent)+ 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.
+      #
+      # @param extension [Extension, #configure, #bind] extension instance
+      # @return [void]
+      def add_extension(extension)
+        @extensions << extension
+        extension.configure(self)
+        nil
+      end
+
+      # Retain a list of already-configured extensions for the
+      # bind sweep without re-running +configure+. Sole intended
+      # caller is {Tool::SubAgent}, which seeds a sub-agent's
+      # Configurator from the parent's extension list — the parent
+      # already drove +configure+ and its system-prompt snippets /
+      # static tools are inherited by the sub-agent verbatim
+      # through {#add_tools} + {#add_listeners} + the augmented
+      # +system_prompt+; re-running +configure+ on the sub-agent
+      # would double up those contributions. The +bind(sub_agent)+
+      # sweep in {Agent#initialize} still fires on each inherited
+      # extension so per-agent state (MCP's per-agent connect tool,
+      # for example) gets installed fresh on the sub-agent.
+      #
+      # @param extensions [Enumerable<Extension>]
+      # @return [void]
+      def inherit_extensions(extensions)
+        extensions.each { |ext| @extensions << ext }
+        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.
+      #
+      # @yield called with no arguments at close time
+      # @return [void]
+      def on_close(&blk)
+        raise ArgumentError, 'on_close requires a block' unless block_given?
+
+        @on_close_handlers << blk
+        nil
+      end
+
+      # Enable the +sub_agent+ tool on this agent. Records the
+      # +max_steps+ budget for sub-agent runs; the Agent ctor reads
+      # {#sub_agent_request} after the block returns and constructs
+      # the actual {Tool::SubAgent} so its snapshot of the parent's
+      # tool list doesn't include itself (recursion guard).
+      #
+      # Sub-agents inherit the parent's tool list (minus +sub_agent+
+      # itself), augmented system prompt, listeners (via
+      # +for_sub_agent+ per listener), controls (per the per-control
+      # rule), and the parent's extension list. Each inherited
+      # extension's +bind(sub_agent)+ fires during the sub-agent's
+      # construction — that's how MCP's per-agent connect tool ends
+      # up keyed to the sub-agent rather than the parent.
+      #
+      # @param max_steps [Integer] step budget for each sub-agent
+      #   run, passed to {Tool::SubAgent#initialize}.
+      # @raise [RuntimeError] if called more than once on the same
+      #   Configurator.
+      # @return [void]
+      def allow_sub_agent(max_steps: 10)
+        raise 'allow_sub_agent may only be called once per agent' if @sub_agent_request
+
+        @sub_agent_request = SubAgentRequest.new(max_steps: max_steps)
+        nil
+      end
+    end
+  end
+end

data/lib/pikuri/agent/context_window_detector.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+module Pikuri
+  class Agent
+    # Resolves the model's context-window cap from three sources, in order:
+    # an explicit override, the value ruby_llm reports for the model, or a
+    # llama.cpp +/props+ probe. Returns +nil+ if none of those produce a
+    # value.
+    #
+    # Used by {Agent#initialize} at construction time to feed
+    # {Listener::TokenLog} a cap it can render alongside the running
+    # context size (so the +ctx=12.2k/32.0k+ line tells the operator how
+    # close the conversation is to the limit).
+    #
+    # == Precedence
+    #
+    # 1. +override+ — the +Agent.new(context_window:)+ kwarg. Wins over
+    #    everything; an explicit value is the operator's statement of
+    #    truth.
+    # 2. +ruby_llm_reported+ — +RubyLLM::Model::Info#context_window+ from
+    #    {Agent#chat}'s resolved model. Populated for models in ruby_llm's
+    #    bundled registry (OpenAI, Anthropic, Gemini, …); +nil+ for custom
+    #    local model ids that fall through to +Model::Info.default+.
+    # 3. +llama_probe_url+ — HTTP GET against llama.cpp's non-standard
+    #    +/props+ endpoint. The server exposes the launched +n_ctx+ at
+    #    +default_generation_settings.n_ctx+ there. Probed only when the
+    #    first two are +nil+. Provider-specific to llama.cpp; the caller
+    #    (typically +bin/pikuri-chat+) derives the right URL from its configured
+    #    base.
+    #
+    # == Failure handling
+    #
+    # The probe is best-effort. HTTP error, timeout, non-JSON body, or a
+    # missing/invalid +n_ctx+ field all return +nil+ and log one +warn+
+    # line via +Pikuri.logger_for('ContextWindowDetector')+. This is the
+    # CLAUDE.md "secondary to the loop" carve-out — a wedged or
+    # non-llama.cpp server should not abort agent construction over a
+    # cosmetic readout.
+    class ContextWindowDetector
+      # Subsystem logger; set its level with
+      # +PIKURI_LOG_CONTEXTWINDOWDETECTOR+ or the global +PIKURI_LOG+.
+      #
+      # @return [Logger]
+      LOGGER = Pikuri.logger_for('ContextWindowDetector')
+
+      # Connect timeout in seconds for the llama.cpp +/props+ probe.
+      # Short on purpose: this runs synchronously during +Agent.new+ and
+      # a wedged server should not stall startup noticeably.
+      #
+      # @return [Integer]
+      OPEN_TIMEOUT = 2
+      # Read timeout in seconds for the llama.cpp +/props+ probe; matches
+      # {OPEN_TIMEOUT} for the same reason.
+      #
+      # @return [Integer]
+      READ_TIMEOUT = 2
+
+      # @param override [Integer, nil] explicit cap from the caller; wins if
+      #   non-+nil+
+      # @param ruby_llm_reported [Integer, nil] value off
+      #   +RubyLLM::Chat#model.context_window+
+      # @param llama_probe_url [String, nil] full URL to llama.cpp +/props+;
+      #   +nil+ or empty string skips the probe
+      def initialize(override:, ruby_llm_reported:, llama_probe_url:)
+        @override = override
+        @ruby_llm_reported = ruby_llm_reported
+        @llama_probe_url = llama_probe_url
+      end
+
+      # @return [Integer, nil] resolved cap, or +nil+ if no source produced
+      #   one
+      def detect
+        return @override if @override
+        return @ruby_llm_reported if @ruby_llm_reported
+        return nil if @llama_probe_url.nil? || @llama_probe_url.empty?
+
+        probe_llama_cpp
+      end
+
+      private
+
+      def probe_llama_cpp
+        response = Faraday.new(
+          request: { open_timeout: OPEN_TIMEOUT, timeout: READ_TIMEOUT }
+        ).get(@llama_probe_url) do |req|
+          req.headers['Accept'] = 'application/json'
+        end
+
+        return warn_and_nil("HTTP #{response.status} from #{@llama_probe_url}") unless response.status == 200
+
+        data = JSON.parse(response.body)
+        n_ctx = data.dig('default_generation_settings', 'n_ctx')
+        return n_ctx if n_ctx.is_a?(Integer) && n_ctx.positive?
+
+        warn_and_nil(
+          "no positive integer at default_generation_settings.n_ctx in #{@llama_probe_url} response"
+        )
+      rescue Faraday::Error, JSON::ParserError => e
+        warn_and_nil("#{e.class.name.split('::').last}: #{e.message}")
+      end
+
+      def warn_and_nil(reason)
+        LOGGER.warn("llama.cpp /props probe failed: #{reason}")
+        nil
+      end
+    end
+  end
+end

data/lib/pikuri/agent/control/cancellable.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Agent
+    module Control
+      # Cooperative cancellation token. The instance is normally
+      # constructed on the main thread and handed to
+      # {Agent#initialize} via the +cancellable:+ kwarg; an
+      # out-of-band caller (a SIGINT trap, a TUI key binding, an
+      # IPC handler) calls {#cancel!} to flip the flag, and the
+      # next {#check!} on the run thread raises {Cancelled} —
+      # which {Agent#run_loop} catches, normalizes into an
+      # {Event::Cancelled} on the listener stream, and re-raises
+      # so the caller's REPL can return control to the user.
+      #
+      # == Cancellation boundary
+      #
+      # The +Agent+ calls {#check!} from its +before_tool_call+
+      # wiring — between an LLM response that requested a tool
+      # and the actual tool invocation — which is the only point
+      # at which the conversation state is consistent (no
+      # in-flight subprocess, no half-applied write). An in-flight
+      # LLM HTTP call is *not* interrupted; the response lands,
+      # then the next tool-call boundary trips. An in-flight tool
+      # (notably +Bash+) is also not interrupted — cancellation
+      # lands after the tool returns. Both are intentional v1
+      # scope: the "gentle cancel" semantic that pikuri promises.
+      #
+      # == Thread safety
+      #
+      # {#cancel!} is intended to be called from a thread other
+      # than the one running {Agent#run_loop} (the typical case
+      # is a SIGINT trap handler on the main thread while the
+      # agent runs on a worker, or vice versa). A plain boolean
+      # ivar is sufficient under MRI: writes and reads of a
+      # single reference are atomic with respect to the GVL, and
+      # the only state transition we care about is +false → true+
+      # before the next {#check!} fires. There is no double-cancel
+      # hazard; repeated {#cancel!} calls are idempotent.
+      #
+      # == Sub-agent semantics
+      #
+      # {#for_sub_agent} returns +self+ — the same instance is
+      # shared by reference across the parent, every sub-agent,
+      # and the synthesizer rescue. One {#cancel!} call stops the
+      # whole tree. This contrasts with {StepLimit}, which gives
+      # each agent its own counter (because step budgets are
+      # per-agent concerns) — cancellation is a global signal
+      # from the user, so it must propagate down.
+      class Cancellable
+        # Raised by {#check!} once {#cancel!} has been called.
+        # Carries no fields; the cancellation reason ("the user
+        # asked us to stop") is implicit in the exception class.
+        # {Agent#run_loop} catches this, emits {Event::Cancelled},
+        # and re-raises so the caller (typically a REPL) can
+        # return control to the user.
+        class Cancelled < StandardError
+          def initialize
+            super('Agent loop cancelled')
+          end
+        end
+
+        def initialize
+          @cancelled = false
+        end
+
+        # Flip the flag. Safe to call from a thread other than
+        # the one running the agent loop, and safe to call
+        # multiple times (idempotent). Takes effect at the next
+        # {#check!} on the run thread — see the class header for
+        # the "gentle cancel" caveats.
+        #
+        # @return [void]
+        def cancel!
+          @cancelled = true
+        end
+
+        # @return [Boolean] whether {#cancel!} has been called
+        #   since the last {#reset!}; observable from any thread.
+        def cancelled?
+          @cancelled
+        end
+
+        # Raise {Cancelled} when the flag is set; otherwise no-op.
+        # Called by {Agent} from its +before_tool_call+ wiring.
+        #
+        # @return [void]
+        # @raise [Cancelled] when {#cancel!} has been called since
+        #   the last {#reset!}
+        def check!
+          raise Cancelled if @cancelled
+        end
+
+        # Reset the flag back to armed. Called by {Agent} at the
+        # start of each turn so a stale cancellation from a prior
+        # turn does not poison the next one. Mid-loop
+        # {Control::Interloper} injections deliberately do *not*
+        # trigger a reset — otherwise the cancel-then-inject
+        # ordering would lose the cancellation: +cancel!+ sets
+        # the flag, the injection lands and resets it, and the
+        # next +before_tool_call+ no longer raises.
+        #
+        # @return [void]
+        def reset!
+          @cancelled = false
+        end
+
+        # Sub-agent variant: the same instance, shared by
+        # reference, so a single {#cancel!} stops the parent,
+        # every running sub-agent, and the synthesizer rescue.
+        # See the class header for the rationale.
+        #
+        # @return [Cancellable] the receiver
+        def for_sub_agent(**)
+          self
+        end
+
+        # @return [String] short label for {Agent#to_s}; reflects
+        #   the current flag state so a startup banner or debug
+        #   print can tell an armed token apart from one that has
+        #   already tripped.
+        def to_s
+          "Cancellable(#{@cancelled ? 'cancelled' : 'armed'})"
+        end
+      end
+    end
+  end
+end