hecks 6.0.0 → 7.0.0

data/lib/hecks/adapters/driving/cli_runner/verb_names.rb

@@ -4,11 +4,15 @@ module Hecks
       module CliRunner
         # Reads the spellings a line may give a command or query. The launcher indexes them by the
         # snake-case `aggregate.verb` the projection prints; the bluebook's own verb form, such as
-        # `Hecks::PushTrain.Board`, reaches the same one. Extended into `CliRunner`.
+        # `Hecks::SendTrain.Board`, reaches the same one. Extended into `CliRunner`.
         module VerbNames
           # A realm written before the aggregate: `Hecks::`.
           REALM = /\A(?:[A-Z]\w*::)+/
 
+          # The spelling notices this process has already printed, keyed by the spelling typed, so each
+          # prints once.
+          NOTED = Set.new
+
           # The name the projection indexes a typed name under: the name itself when it is one,
           # else its verb form read into snake case, else the name as typed, for the refusal to
           # name.
@@ -20,8 +24,36 @@ module Hecks
             [typed, *verb_form_names(typed)].find { |name| indexed?(cli, name) } || typed
           end
 
+          # Says once, on standard error, that a line used an aggregate's former name and names the
+          # spelling to use. Short-name aliases stay silent.
+          #
+          # @param cli [Hash] the projection
+          # @param typed [String] the word typed, without its `!`
+          # @param name [String] the name the index resolved the word to
+          # @return [void]
+          def note_former_name(cli, typed, name)
+            spec = indexed_spec(cli, name)
+            return unless former_spelling?(spec, typed)
+            return unless NOTED.add?("spelling #{typed}")
+
+            warn "hecks: #{typed} is the former name of #{spec[:command]}; use that spelling (this notice prints once)"
+          end
+
+          # The command or query a name in the index resolves to, or nil.
+          def indexed_spec(cli, name)
+            target = cli[:names][:command][name] || cli[:names][:question][name]
+            cli[:commands][target] || cli[:questions][target]
+          end
+
+          # Whether the word typed begins with the former name of the aggregate its spec belongs to.
+          def former_spelling?(spec, typed)
+            return false unless spec && spec[:formerly]
+
+            snake_form(typed).start_with?("#{Naming.snake(spec[:formerly])}.")
+          end
+
           # A typed name as the projection spells it, to match what was typed against the names it
-          # indexes: `Hecks::PushTrain.bord` as `push_train.bord`.
+          # indexes: `Hecks::SendTrain.bord` as `send_train.bord`.
           #
           # @param typed [String] the word typed, without its `!`
           # @return [String] the realm dropped and each dotted segment in snake case
@@ -29,8 +61,8 @@ module Hecks
 
           private
 
-          # `Hecks::PushTrain.board` as `push_train.board`; a verb that names an entity's command,
-          # `PushTrain.Launcher.Refresh`, also as `push_train.refresh`, the way the projection
+          # `Hecks::SendTrain.board` as `send_train.board`; a verb that names an entity's command,
+          # `SendTrain.Launcher.Refresh`, also as `send_train.refresh`, the way the projection
           # exposes it.
           def verb_form_names(typed)
             segments = snake_segments(typed)

data/lib/hecks/adapters/driving/cli_runner/verbosity.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # The launcher's output levels. `-q` prints only the result and any refusal, so the progress
+        # and the context line are left out. `-v` adds, on standard error, the command that ran, its
+        # checkout and stores, and how long it took. The default prints what the launcher always
+        # printed. The flags are taken from anywhere in the line, and cannot be given together.
+        module Verbosity
+          QUIET_FLAG = "-q"
+          VERBOSE_FLAG = "-v"
+          FLAGS = { QUIET_FLAG => :quiet, VERBOSE_FLAG => :verbose }.freeze
+          CONFLICT = "hecks: -q and -v cannot be given together; give one of them, or neither"
+
+          # Takes the level flags out of a line.
+          #
+          # @param argv [Array<String>] the words the launcher was given
+          # @return [Array(Symbol, Array<String>)] the level (`:quiet`, `:verbose`, `:default`, or
+          #   `:conflict` when both flags came) and the words without the flags
+          def split_verbosity(argv)
+            levels = argv.filter_map { |word| FLAGS[word] }.uniq
+            return [:conflict, argv] if levels.length > 1
+
+            [levels.first || :default, argv.reject { |word| FLAGS.key?(word) }]
+          end
+
+          # Runs a block at one level, and resets the level and the stage progress afterwards.
+          #
+          # @param level [Symbol] `:quiet`, `:verbose` or `:default`
+          # @yield the answer the line gets at that level
+          # @return [Object] the block's value
+          def with_verbosity(level)
+            require_relative "../../../tools/stage_progress"
+            previous = Thread.current[:hecks_verbosity]
+            Thread.current[:hecks_verbosity] = level
+            Tools::StageProgress.quiet = level == :quiet
+            yield
+          ensure
+            Thread.current[:hecks_verbosity] = previous
+            Tools::StageProgress.quiet = previous == :quiet
+          end
+
+          # @return [Symbol] the level the line runs at
+          def verbosity = Thread.current[:hecks_verbosity] || :default
+
+          # @return [Boolean] whether only the result and any refusal are printed
+          def quiet? = verbosity == :quiet
+
+          # @return [Boolean] whether each step's details are printed on standard error
+          def verbose? = verbosity == :verbose
+
+          # The details `-v` adds after a command ran: the command, how long it took, and the
+          # checkout and stores the line ran in.
+          #
+          # @param err [#puts] where the details go
+          # @param name [String] the command or query that ran
+          # @param started [Float] the monotonic clock reading when the line began
+          # @return [void]
+          def verbose_details(err, name, started)
+            elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+            err.puts("command #{name}", format("took %.2fs", elapsed), checkout_line)
+          end
+
+          # @return [String] the context line, as `-v` prints it
+          def checkout_line
+            ContextLine.line(directory: Dir.pwd, stores: SettingsReading.new.stores(Dir.pwd),
+                             audience: ContextLine.audience(Dir.pwd))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/cli_runner.rb

@@ -1,6 +1,9 @@
 require "json"
 require_relative "cli"
 require_relative "command_request"
+require_relative "context_line"
+require_relative "exit_status"
+require_relative "write_guard"
 require_relative "json"
 require_relative "launcher_options"
 require_relative "newcomer"
@@ -8,25 +11,45 @@ require_relative "../../projector"
 require_relative "../../ports/clock"
 require_relative "cli_runner/answers"
 require_relative "cli_runner/resolution"
+require_relative "cli_runner/run_replay"
+require_relative "cli_runner/search_words"
+require_relative "cli_runner/completion_words"
+require_relative "cli_runner/tour_words"
+require_relative "cli_runner/resume_words"
+require_relative "cli_runner/json_words"
 require_relative "cli_runner/settling"
 require_relative "cli_runner/streaming"
 require_relative "cli_runner/suggestions"
 require_relative "cli_runner/verb_names"
+require_relative "cli_runner/renamed_names"
+require_relative "cli_runner/verbosity"
+require_relative "cli_runner/name_index"
 
 module Hecks
   module Adapters
     module Driving
       # Parses and dispatches a command line against a `Projector::CliProjector` projection.
-      # Does no IO: it answers `[text, status]` and leaves printing and exiting to its callers.
+      # Does no IO: it answers `[text, status]` (an `ExitStatus`) and leaves printing and exiting
+      # to its callers.
       module CliRunner
+        include ExitStatus
+        extend Verbosity
+
         # The class an adapter raises when the tool it wraps refuses.
         TOOL_REFUSAL = "Hecks::Adapters::ConsoleCapture::Failure".freeze
         # The words that open the query namespace; `ask` is the older spelling.
         QUERY_WORDS = %w[query ask].freeze
 
         extend Resolution
+        extend SearchWords
+        extend CompletionWords
+        extend TourWords
+        extend ResumeWords
+        extend JsonWords
         extend Suggestions
+        extend NameIndex
         extend VerbNames
+        extend RenamedNames
         extend Answers
         extend Settling
         extend Streaming
@@ -38,18 +61,91 @@ module Hecks
         #
         # @param runtime [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the booted domain
         # @param argv [Array<String>] an optional `query` (or `ask`), the command or query name,
-        #   then
-        #   `path=value` pairs; `--help`, `-h`, `help` or nothing answers usage
+        #   then `path=value` pairs; `--help`, `-h`, `help` or nothing answers usage
         # @param program [String] how the caller was invoked, echoed in usage and hints
-        # @return [Array(String, Integer)] the text and the status: 0 answered, 1 refused or misused
+        # @return [Array(String, Integer)] the text and the `ExitStatus`: `ANSWERED`, `REFUSED`
+        #   when the domain said no or the run failed, `USAGE` when the line could not be read
         # @raise [Runtime::WiringError] if a repository or the clock adapter cannot be resolved
         # @raise [Runtime::StaleWrite] if concurrent writers beat the command through every retry
-        def call(runtime:, argv:, program: "hecks run")
+        def call(runtime:, argv:, program: "hecks run", usage_log: false, err: $stderr)
+          level, argv = split_verbosity(argv)
+          return [Verbosity::CONFLICT, USAGE] if level == :conflict
+          return if argv.first == "resume" && argv[1] # a resume that names a run runs a saga: it needs a booted domain
+
+          with_verbosity(level) { answer_line(runtime, argv, program, usage_log, err) }
+        rescue Interrupt
+          [interrupted(argv), ExitStatus::REFUSED]
+        end
+
+        # Answers one line: resolves it, guards a write, dispatches it and records its usage.
+        #
+        # @api private
+        # @return [Array(String, Integer)] the text and the `ExitStatus`
+        def answer_line(runtime, argv, program, usage_log, err)
+          started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           plan = resolve(runtime, argv, program)
           return plan[:answer] if plan[:answer]
 
-          dispatch(runtime, plan[:spec], plan[:name], plan[:rest], plan[:program], plan[:asking],
-                   bluebook: plan[:bluebook], launcher: plan[:launcher])
+          refused = guard_command(plan, err)
+          return [refused, ExitStatus::REFUSED] if refused
+
+          answer = dispatch(runtime, plan[:spec], plan[:name], plan[:rest], plan[:program], plan[:asking],
+                            bluebook: plan[:bluebook], launcher: plan[:launcher])
+          finish_line(answer, plan, started, { argv: argv, usage_log: usage_log, err: err })
+        end
+
+        # Records a line that ran and prints its details when `-v` asked for them.
+        #
+        # @api private
+        # @return [Array(String, Integer)] the answer, unchanged
+        def finish_line(answer, plan, started, details)
+          UsageLog.record(argv: details[:argv], resolved: plan[:name], status: answer[1], started: started) if details[:usage_log]
+          verbose_details(details[:err], plan[:name], started) if verbose?
+          answer
+        end
+
+        # The line an interrupted command ends with: what it was and that it was not finished,
+        # so the caller sees a refusal rather than a bare stop.
+        #
+        # @api private
+        # @return [String] the text the caller prints on standard error
+        def interrupted(argv)
+          name = argv.first || "the command"
+          "interrupted during #{name}: the run was stopped before it finished"
+        end
+
+        # Before a command (not a query) runs: refuses a write that would land in Memory from a
+        # worktree whose main checkout stores it elsewhere, else prints the context line.
+        #
+        # @api private
+        # @return [String, nil] the refusal, or nil when the command may run
+        def guard_command(plan, err)
+          return if plan[:asking]
+
+          refusal = WriteGuard.refusal(Dir.pwd, plan[:bluebook]&.name)
+          return refusal if refusal
+
+          ContextLine.announce(err) unless quiet?
+          nil
+        end
+
+        # The names a person can type at the launcher, as the projection names them: commands and
+        # queries, leaving out the internal steps a run records about itself.
+        #
+        # @param runtime [#registry] a booted domain, or what `Hecks.describe` answers
+        # @param program [String] how the caller was invoked
+        # @return [Array<String>] the sorted names
+        def known_names(runtime:, program: "hecks run")
+          bluebook, = bluebook_for(runtime, [], program)
+          launcher = LauncherOptions.settings(runtime, bluebook.name)
+          options = LauncherOptions.projection(launcher, program)
+          cli = Projector.call(:cli, bluebook: bluebook, options: options.merge(audience(runtime, launcher)))
+          public_names(cli[:names][:command], cli[:commands]) + public_names(cli[:names][:question], cli[:questions])
+        end
+
+        # @return [Array<String>] the names whose spec is not internal
+        def public_names(names, specs)
+          names.reject { |_, id| specs.dig(id, :internal) }.keys.sort
         end
 
         # Answers a command line that asks only for usage, from the projection alone.
@@ -64,6 +160,9 @@ module Hecks
         # @return [Array(String, Integer), nil] the text and status, or nil when the line would
         #   run a command or question and so needs a booted domain
         def usage(runtime:, argv:, program: "hecks run")
+          level, argv = split_verbosity(argv)
+          return [Verbosity::CONFLICT, USAGE] if level == :conflict
+
           UsageCache.fetch(runtime, argv, program, audience: audience_key) { resolve(runtime, argv, program)[:answer] }
         end
       end

data/lib/hecks/adapters/driving/context_line.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "launcher_options"
+
+module Hecks
+  module Adapters
+    module Driving
+      # The one line a command prints before it writes: which checkout it runs in, the store each
+      # bluebook uses, and the audience the launcher lists for. It reads only, through the store
+      # resolution `hecks config` uses, so the line cannot disagree with a boot.
+      module ContextLine
+        MEMORY = "Memory"
+
+        # The store of a bluebook, as a label with no aggregate in it.
+        BLUEBOOK_STORE = /\Astore [^:]+\z/
+
+        # The storage kinds a store description starts with.
+        SQLITE_STORE = /\ASqlite/i
+        POSTGRES_STORE = /\APostgres/
+
+        module_function
+
+        # Prints the line on a terminal; a pipe or a file gets nothing, so stdout stays clean.
+        #
+        # @param err [#tty?, #puts] where the line goes
+        # @param directory [String] the checkout a command runs in
+        # @return [String, nil] the line printed, or nil when nothing was printed
+        def announce(err, directory: Dir.pwd)
+          return unless err.respond_to?(:tty?) && err.tty?
+
+          require_relative "../../hecks/adapters/settings_reading"
+
+          text = line(directory: directory, stores: SettingsReading.new.stores(directory),
+                      audience: audience(directory))
+          err.puts(text)
+          text
+        end
+
+        # @param directory [String] the checkout a command runs in
+        # @param stores [Array<Array(String, String, String)>] store rows, as `stores` answers them
+        # @param audience [String] the audience the launcher lists for
+        # @return [String] the line
+        def line(directory:, stores:, audience:)
+          ["checkout #{File.basename(directory)} (#{branch(directory)})", stored(stores),
+           "audience #{audience}"].join(" · ")
+        end
+
+        # @param stores [Array<Array(String, String, String)>] store rows
+        # @return [String] "Tickets in SQLite" for each bluebook off Memory, else Memory
+        def stored(stores)
+          found = stores.filter_map do |label, value, _source|
+            next unless label.match?(BLUEBOOK_STORE) && kind(value) != MEMORY
+
+            "#{label.delete_prefix("store ")} in #{kind(value)}"
+          end
+          found.empty? ? MEMORY : found.join(", ")
+        end
+
+        # @param value [String] a store's description, as the rows give it
+        # @return [String] the store's kind
+        def kind(value)
+          case value.to_s
+          when SQLITE_STORE then "SQLite"
+          when POSTGRES_STORE then "Postgres"
+          else value.to_s.split.first || MEMORY
+          end
+        end
+
+        # @param directory [String]
+        # @return [String] the checked-out branch, or "detached" when there is none
+        def branch(directory)
+          out, status = Open3.capture2e("git", "-C", directory, "symbolic-ref", "--short", "HEAD")
+          status.success? ? out.strip : "detached"
+        end
+
+        # @param directory [String]
+        # @return [String] "maintainer" inside a hecks checkout, else "person"
+        def audience(directory)
+          LauncherOptions.maintainer?(directory) ? "maintainer" : "person"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/exit_status.rb

@@ -0,0 +1,31 @@
+module Hecks
+  module Adapters
+    module Driving
+      # The statuses a launcher exits with, which a script branches on: `CliRunner` answers them
+      # beside its text, the runner returns them, and every generated launcher passes them to
+      # `exit`. Three suffice: the line was answered, the domain said no, or the line could not
+      # be read. A crash and a domain that cannot be opened both end as `REFUSED`, because the
+      # launcher distinguishes neither from a refusal.
+      module ExitStatus
+        # The line ran and was answered: a usage, a command's outcome, a query's rows, a stream
+        # that ended, and a port operation's refusal event, which is an answer.
+        ANSWERED = 0
+
+        # The domain said no, or the run failed: a refusal, a record that is not there, a
+        # `--wait` run that ended in a failure state or whose reaction was refused or crashed, a
+        # question that reports a gap under `--wait`, the door refusing the caller, or a domain
+        # that cannot be opened.
+        REFUSED = 1
+
+        # The line could not be read: no command named, a command or query the bluebook does not
+        # declare, a word the command does not take, a value its type cannot hold, or a flag the
+        # command lacks.
+        USAGE = 2
+
+        # One line a launcher's help prints, naming the three statuses.
+        HELP_LINE = "exit status: #{ANSWERED} answered, #{REFUSED} refused or failed, " \
+                    "#{USAGE} a line it could not read".freeze
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/launcher_options.rb

@@ -59,7 +59,7 @@ module Hecks
         # @param program [String] how the caller was invoked
         # @return [Hash{Symbol => Object}] the options `Projector::CliProjector` reads
         def projection(settings, program)
-          { program: program, names: settings && settings[:names], mint_run_keys: settings && settings[:run_keys] }
+          { program:, opted: !settings.nil?, **settings.to_h.slice(:names, :renamed), mint_run_keys: settings&.dig(:run_keys) }
         end
 
         # Whether the person is working on a hecks checkout: `dir` or a directory above it holds
@@ -79,17 +79,19 @@ module Hecks
 
         # The help options one audience gets: the aggregates left out of the lists (`maintainer`,
         # shown only in a hecks checkout or to `--maintainer`) and the bluebooks pointed at
-        # (`bluebooks`, plus `maintainer_bluebooks` in a checkout). A bluebook that did not opt in
-        # gets neither.
+        # (`bluebooks`, plus `maintainer_bluebooks` in a checkout), and the commands listed first
+        # (`everyday`). A bluebook that did not opt in gets none of them.
         #
         # @param settings [Hash, nil] the bluebook's `launcher` setting
         # @param maintainer [Boolean] whether the help is for someone working on a hecks checkout
-        # @return [Hash{Symbol => Object}] `:hide` and `:bluebooks`, to merge into the projection
+        # @return [Hash{Symbol => Object}] `:hide`, `:bluebooks` and `:everyday` (empty when the
+        #   setting names none), to merge into the projection
         def audience(settings, maintainer)
           return {} unless settings
 
           named = Array(settings[:bluebooks]) + (maintainer ? Array(settings[:maintainer_bluebooks]) : [])
-          { hide: maintainer ? [] : Array(settings[:maintainer]).map(&:to_s), declarations: named.map(&:to_s) }
+          { hide: maintainer ? [] : Array(settings[:maintainer]).map(&:to_s), declarations: named.map(&:to_s),
+            everyday: Array(settings[:everyday]).map(&:to_s) }
         end
 
         # Runs the block with standard error held back, so the wiring notes hecks prints about its

data/lib/hecks/adapters/driving/mcp/progress_sink.rb

@@ -0,0 +1,45 @@
+require "json"
+require_relative "../../../tools/stage_progress"
+
+module Hecks
+  module Adapters
+    module Driving
+      module Mcp
+        # Where a stage's progress lines go when the client asked for them with a progress token: each
+        # line becomes one `notifications/progress` message on the server's output, ahead of the
+        # response to the call. Stands in for the standard error that `Tools::StageProgress` writes to.
+        class ProgressSink
+          # @param token [Object] the client's `progressToken`, echoed back on every notification
+          # @param out [#puts] the server's output, where each notification is written
+          def initialize(token, out:)
+            @token = token
+            @out   = out
+            @count = 0
+          end
+
+          # Sends one line as a progress notification. The count rises by one per line, so a client
+          # can order them.
+          # @param text [String] the line
+          # @return [void]
+          def puts(text)
+            @count += 1
+            @out.puts(JSON.generate(notification(text)))
+          end
+
+          # Nothing is buffered, so there is nothing to flush.
+          # @return [nil]
+          def flush = nil
+
+          private
+
+          # @param text [String] the line
+          # @return [Hash] the JSON-RPC notification carrying it
+          def notification(text)
+            { jsonrpc: "2.0", method: "notifications/progress",
+              params: { progressToken: @token, progress: @count, message: text } }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/mcp/tool_calls.rb

@@ -48,10 +48,10 @@ module Hecks
 
           # A question, once the scope has admitted its arguments.
           def query_tool(args)
-            Mcp.scope.admit_arguments!(args["args"])
+            Mcp.scope.admit_arguments!(args["args"], args["question"])
             Storehouse.query(runtime: Mcp.boot(args["domain"]), question: args["question"],
                              summary: args["summary"], args: args["args"] || {}, source: args["source"],
-                             role: args["role"], actor_id: args["actor_id"])
+                             role: args["role"], actor_id: args["actor_id"], surface: "mcp")
           end
 
           # A single command or a batch, once the scope has admitted every command in it.
@@ -62,14 +62,16 @@ module Hecks
             Mcp.scope.admit_command!(runtime, args["command"], args["args"])
             Storehouse.dispatch(runtime: runtime, command: args["command"], summary: args["summary"],
                                 args: args["args"] || {}, source: args["source"],
-                                dry_run: args["dry_run"] == true, role: args["role"], actor_id: args["actor_id"])
+                                dry_run: args["dry_run"] == true, role: args["role"], actor_id: args["actor_id"],
+                                surface: "mcp")
           end
 
           # Several commands in one call.
           def dispatch_steps(runtime, args)
             Mcp.scope.admit_steps!(runtime, args["steps"])
             Storehouse.dispatch_batch(runtime: runtime, steps: args["steps"], summary: args["summary"],
-                                      source: args["source"], role: args["role"], actor_id: args["actor_id"])
+                                      source: args["source"], role: args["role"], actor_id: args["actor_id"],
+                                      surface: "mcp")
           end
 
           def events_tool(args)
@@ -79,7 +81,7 @@ module Hecks
 
           def state_tool(args)
             Storehouse.state(runtime: Mcp.boot(args["domain"]), aggregate: args["aggregate"],
-                             summary: args["summary"], id: args["id"])
+                             summary: args["summary"], id: args["id"], surface: "mcp")
           end
 
           def catalog_tool(args)

data/lib/hecks/adapters/driving/mcp.rb

@@ -1,8 +1,9 @@
 require "json"
 require_relative "../.."
-require_relative "../../cli/mcp"
+require_relative "../../tools/mcp"
 require_relative "mcp/tool_definitions"
 require_relative "mcp/tool_calls"
+require_relative "mcp/progress_sink"
 
 module Hecks
   module Adapters
@@ -42,7 +43,7 @@ module Hecks
         # Read once, so a bad setting refuses to start the server before anything is
         # written to stdout.
         def scope
-          @scope ||= McpScope.start!(server: CLI::Mcp::SERVER)
+          @scope ||= McpScope.start!(server: Tools::Mcp::SERVER)
         end
 
         # The standing notes, then what this server's scope says about `domain:`.
@@ -51,7 +52,7 @@ module Hecks
         end
 
         def serve
-          McpStdioGuard.warn!(server: CLI::Mcp::SERVER, notes: warning_notes)
+          McpStdioGuard.warn!(server: Tools::Mcp::SERVER, notes: warning_notes)
           $stdout.sync = true
 
           $stdin.each_line { |line| answer_line(line.strip) }
@@ -138,7 +139,7 @@ module Hecks
 
         def initialize_result(_params)
           { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} },
-            serverInfo: { name: CLI::Mcp::SERVER, version: "1.1.0" } }
+            serverInfo: { name: Tools::Mcp::SERVER, version: "1.1.0" } }
         end
 
         # The tools this server's scope permits, each presented with the command guide.
@@ -149,9 +150,28 @@ module Hecks
         end
 
         def tools_call(params)
-          tool_result(answer_tool(params["name"], params["arguments"] || {}))
+          token = params.dig("_meta", "progressToken")
+          return tool_result(answer_tool(params["name"], params["arguments"] || {})) if token.nil?
+
+          with_progress(token) { tool_result(answer_tool(params["name"], params["arguments"] || {})) }
+        end
+
+        # Runs the block with a progress seam for this call's stages, so their lines reach the client as
+        # notifications. The seam is per thread and removed when the call ends.
+        # @param token [Object] the client's progress token
+        # @return [Object] the block's value
+        def with_progress(token)
+          previous = Thread.current[:mcp_progress]
+          Thread.current[:mcp_progress] = Tools::StageProgress.new(ProgressSink.new(token, out: $stdout))
+          yield
+        ensure
+          Thread.current[:mcp_progress] = previous
         end
 
+        # The progress seam of the call on this thread: nil when the client sent no progress token.
+        # @return [Tools::StageProgress, nil]
+        def progress = Thread.current[:mcp_progress]
+
         def ping_result(_params) = {}
       end
     end