pikuri-lsp 0.1.0

data/lib/pikuri/lsp/lsp_tool.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Lsp
+    # The +lsp+ tool: one tool, ten operations, and no column ever asked for.
+    #
+    #   tool = LspTool.new(servers: servers, filesystem: filesystem)
+    #   tool.run('operation' => 'goToDefinition', 'symbol' => 'resolve_for_read',
+    #            'file' => 'read.rb', 'line' => 165)
+    #
+    # The *surface* lives here — the schema, the description the model reads, the
+    # legs, the progress emitter. The behaviour is {Navigator}'s, the enum is
+    # {Operation}'s, and why a column is derived rather than asked for is {Anchor}'s.
+    #
+    # Ten +lsp_*+ tools would be ten descriptions in every request's prompt budget,
+    # and all three shipped harnesses reached the same one-tool conclusion. The
+    # +foo_*+ prefix convention is still satisfied: the family shares one backing
+    # resource, and +Tool::Parameters+ validates the enum strictly.
+    #
+    # == The legs, including the one that will surprise you
+    #
+    # +untrusted: :hard+, **unconditionally** — not riding +filesystem.trusted?+ the
+    # way {Pikuri::Workspace::Read} does. +read+'s conditional cannot be copied
+    # because +read+ is confined to the root, so a human's "yes, I trust this
+    # checkout" covers exactly what +read+ can reach. A server's index does not stop
+    # at the root: it reaches the whole bundle, the JDK and four hundred transitive
+    # jars, and the +jdt:+ content path reads text out of a jar nobody ever diffed.
+    # Quoting third-party prose into the context in bulk is this gem's *marquee
+    # feature*, not an edge case of it. The consequence is deliberate: on a trusted
+    # checkout +read+ declares +:none+, so wiring +lsp+ beside +fetch+ or
+    # +web_search+ can light the untrusted leg where nothing fired before.
+    #
+    # +egress_payload_review: :no_egress+, and *not* because the server is trusted:
+    # a seat whose outbound bytes do not originate in the model's choosing holds no
+    # leg to grade. +operation+, +symbol+, +file+ and +line+ reach an in-memory
+    # index, never a socket. A registered server may go online on its own — jdtls
+    # resolving a jar — but that traffic follows the project's build files and
+    # happens identically if the model never issues a single call.
+    #
+    # +private:+ is inherited from the workspace, never claimed here: the host
+    # already asked the human whether this project is private.
+    #
+    # == Sharing
+    #
+    # +P_one_agent+, and accepted as such: one wiring, one agent. Three things
+    # bind it — a per-agent {Pikuri::Agent::Control::Cancellable}, a mutable
+    # +on_progress+ hook installed after construction, and {Servers}, whose
+    # open-document bookkeeping assumes one caller (a second agent's
+    # +didClose+ can land on a document the first is still asking about).
+    #
+    # Ten agents over one project therefore means ten registries and ten sets
+    # of child processes, which is the honest cost of not having built a shared
+    # server pool. Nothing here refuses the sharing; it just goes wrong
+    # quietly, so don't.
+    class LspTool < Pikuri::Tool
+      # Description shown to the LLM (opencode-shape). Per-parameter constraints
+      # live in the parameter descriptions; the operation list is generated from
+      # {Operation::ALL} so it cannot drift from what dispatch accepts.
+      #
+      # Two things it deliberately does *not* say, both of which an earlier draft
+      # did. It does not mention that the first call waits for the server to
+      # finish indexing — the model has no notion of time, so the only content in
+      # that sentence is an implied promise that results are now complete, and a
+      # fully-started server can still be broken. And it does not announce that an
+      # unsupported operation refuses cleanly: the model learns that from the
+      # refusal, which names the missing capability. What stays is mechanics —
+      # how to anchor a call, what shapes the answer comes in — never a claim
+      # about the *quality* of what comes back, which is the model's to judge.
+      DESCRIPTION = <<~DESC
+        Ask a language server about code: where a name is defined, who calls it, what it inherits from.
+
+        Usage:
+        - Anchor a query with `symbol` plus `file` and `line` — the line number as printed when you read the file or searched it. The column is worked out from that line's text, so it is never asked for.
+        - `symbol` on its own searches every configured server's index instead. Best effort: a short name is matched against fully qualified ones and can score below a server's own threshold, and some servers index types but no methods.
+        - Servers are configured per file type. A file type nothing claims is refused, never guessed at.
+        - Results are capped and grouped, references and callers most aggressively; a truncation marker means there was more.
+        - A server's index reaches outside the project, so a result may live in a dependency rather than in your code. Such a result always carries its line of code, and carries a path when this workspace can read that file — otherwise just the file's name, or the type's name and the archive it came from.
+
+        Operations:
+        #{Operation::ALL.map { |operation| "- #{operation.name} — #{operation.summary}" }.join("\n")}
+      DESC
+
+      # @return [Proc] called with a {ServerProgress}, on the calling thread, while
+      #   a call waits for a server to finish indexing. A host installs its event
+      #   emitter here after construction; the default drops them, which is what a
+      #   tool built outside an agent wants.
+      attr_accessor :on_progress
+
+      # @param servers [Servers] started clients. The tool never spawns.
+      # @param filesystem [Pikuri::Workspace::Filesystem] the project: path
+      #   resolution, root confinement, the +denied?+ pass every walked path owes,
+      #   and the +private?+ answer this tool's legs inherit.
+      # @param cancellable [Pikuri::Agent::Control::Cancellable, nil] what makes an
+      #   unbounded index wait acceptable.
+      def initialize(servers:, filesystem:, cancellable: nil)
+        @servers = servers
+        @filesystem = filesystem
+        @cancellable = cancellable
+        @on_progress = ->(_progress) {}
+        tool = self
+        super(
+          name: 'lsp',
+          description: DESCRIPTION,
+          parameters: Pikuri::Tool::Parameters.build { |p|
+            p.required_enum :operation,
+                            'Which question to ask; see the Operations list, ' \
+                            'e.g. "goToDefinition".',
+                            values: Operation.names
+            p.required_string :symbol,
+                              'The name to ask about, spelled exactly as the ' \
+                              'source spells it, e.g. "resolve_for_read" or ' \
+                              '"Pikuri::Workspace::Read".'
+            p.optional_string :file,
+                              'File the symbol is in, e.g. ' \
+                              '"pikuri-workspace/lib/pikuri/workspace/read.rb". ' \
+                              'Relative paths resolve against the workspace ' \
+                              'root. Picks the language server and, with line, ' \
+                              'anchors the query; without it every server\'s ' \
+                              'index is searched. Required for documentSymbol, ' \
+                              'and needed in practice for goToTypeDefinition, ' \
+                              'whose usual target is a local variable that is in ' \
+                              'no index.'
+            p.optional_integer :line,
+                               '1-based line the symbol appears on, as printed ' \
+                               'when you read the file, e.g. 165. Needs file, ' \
+                               'and the symbol must occur literally on that line.'
+          },
+          execute: lambda { |operation:, symbol:, file: nil, line: nil|
+            tool.navigate(operation: operation, symbol: symbol, file: file, line: line)
+          },
+          trifecta_legs: Pikuri::Tool::TrifectaLegs.new(
+            private: filesystem.private?,
+            untrusted: :hard,
+            egress_payload_review: :no_egress
+          )
+        )
+      end
+
+      # Run one call.
+      #
+      # A fresh {Navigator} per call, rather than one captured in the +execute+
+      # lambda: {#on_progress} is installed *after* the tool is built, so a
+      # navigator built once would keep emitting into the default no-op forever.
+      #
+      # @param operation [String]
+      # @param symbol [String]
+      # @param file [String, nil]
+      # @param line [Integer, nil]
+      # @return [String] the observation.
+      def navigate(operation:, symbol:, file: nil, line: nil)
+        Navigator.new(servers: @servers, filesystem: @filesystem,
+                      on_progress: @on_progress, cancellable: @cancellable)
+                 .navigate(operation: operation, symbol: symbol, file: file, line: line)
+      end
+    end
+  end
+end

data/lib/pikuri/lsp/mailbox.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Lsp
+    # A thread boundary that keeps only the *newest* value per key. A producer
+    # thread pushes; one consumer thread drains, and the block runs on the
+    # consumer's thread:
+    #
+    #   mailbox = Mailbox.new
+    #   Thread.new { mailbox.push('token-1', progress) }   # the reader thread
+    #
+    #   mailbox.drain(tick: 0.1) do |value|                # nil on an idle tick
+    #     cancellable&.check!
+    #     break if ready?
+    #     emit.call(value) if value
+    #   end
+    #
+    # {#drain} loops until the block +break+s — the consumer has to poll its own
+    # exit conditions anyway, so it gets one place to do it. No +stop_when:+
+    # predicate, no sentinel value.
+    #
+    # It exists for the one shape a queue gets wrong. ruby-lsp emits hundreds of
+    # +$/progress+ reports while it indexes, and a consumer blocked for three
+    # minutes would replay every one of them — a burst of stale percentages
+    # racing to catch up. Coalescing per key means the first drain yields
+    # *current* state and then tracks live, which makes +Thread::Queue+ the wrong
+    # primitive: it faithfully preserves exactly what this discards.
+    #
+    # Per key rather than one global latest because concurrent tasks are normal —
+    # jdtls holds "Importing project" and "Building workspace" open at once. The
+    # key is a parameter, so nothing here knows what the value is.
+    #
+    # Thread-safe, and that is its whole purpose. One consumer only: two threads
+    # draining would each see an arbitrary half of the values.
+    class Mailbox
+      def initialize
+        @mutex = Mutex.new
+        @pushed = ConditionVariable.new
+        @latest = {}
+      end
+
+      # Park +value+ under +key+, replacing whatever was parked there, and wake
+      # the consumer.
+      #
+      # @param key [Object] what to coalesce on, e.g. a progress token.
+      # @param value [Object] the newest state for that key.
+      # @return [void]
+      def push(key, value)
+        @mutex.synchronize do
+          @latest[key] = value
+          @pushed.signal
+        end
+        nil
+      end
+
+      # Yield parked values on this thread until the block breaks, waking every
+      # +tick+ seconds to yield +nil+ so the consumer can check its own exit
+      # conditions. Values arrive in the order their keys were first pushed;
+      # +nil+ means the mailbox was empty, not that anything ended.
+      #
+      # @param tick [Float] seconds between idle yields. A push wakes the wait
+      #   early, so this bounds the *idle* latency, not the live one.
+      # @yieldparam value [Object, nil] the newest value for one key, or +nil+ on
+      #   an idle tick.
+      # @return [Object] whatever the block broke with.
+      def drain(tick:)
+        loop do
+          parked = take_all
+          if parked.empty?
+            yield nil
+            @mutex.synchronize { @pushed.wait(@mutex, tick) if @latest.empty? }
+          else
+            parked.each { |value| yield value }
+          end
+        end
+      end
+
+      # @return [Integer] how many keys are parked. For tests and diagnostics;
+      #   a consumer polls by draining.
+      def size
+        @mutex.synchronize { @latest.size }
+      end
+
+      private
+
+      # Atomically: everything parked, and an empty mailbox. Nothing is yielded
+      # under the mutex — the producer must stay free to push while the consumer
+      # works.
+      def take_all
+        @mutex.synchronize do
+          values = @latest.values
+          @latest.clear
+          values
+        end
+      end
+    end
+  end
+end

data/lib/pikuri/lsp/navigator.rb

@@ -0,0 +1,340 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Lsp
+    # One +lsp+ call, end to end: route to a server, wait for its index, re-open
+    # the document, ask, render. {LspTool} holds the schema and the legs; this holds
+    # the behaviour, so a spec can drive it with no tool in sight.
+    #
+    #   navigator = Navigator.new(servers: servers, filesystem: filesystem,
+    #                             on_progress: ->(progress) { ctx.emit_event(progress) })
+    #   navigator.navigate(operation: 'goToDefinition', symbol: 'resolve_for_read',
+    #                      file: 'read.rb', line: 165)
+    #
+    # == The order of the five steps is the design
+    #
+    # 1. **Route on the file**, or fan out when there is none — the model names no
+    #    server, and a registry keyed by language would fail in exactly the
+    #    mixed-language repo that makes a registry worth having.
+    # 2. **Gate on what that server advertised**, per workspace and at dispatch.
+    #    Extension routing without this is how a shipped client leaks
+    #    +Method not found: textDocument/implementation+ at the model.
+    # 3. **Wait for the index** — the one place waiting beats relaying, because a
+    #    mid-index server answers +[]+ with a success code and there is nothing in
+    #    +[]+ to reason about. No timeout: a cold Java import measured 78 seconds,
+    #    no number separates that from a hang, and progress events plus
+    #    +cancellable+ make the human the timeout.
+    # 4. **Re-open the document** ({ClientWrapper#open_document}), and hand it
+    #    back once every reply is in ({#release_documents}) — the pair is per
+    #    *call*, because one call can ask several questions about one document.
+    # 5. **Ask and render**, running the +prepare+ hop and the per-level walk here
+    #    so the model issues one call and never holds an opaque protocol item.
+    #
+    # == Errors are relayed, never worked around
+    #
+    # Every server is broken in its own way and the ways do not generalize — one
+    # advertises a type hierarchy whose downward half is a +# TODO+, another indexes
+    # no methods, a third crashes on a notification the spec allows. So there is no
+    # per-server workaround and no known-stub list here: what the server said and
+    # what it was asked go back, and the model decides. That includes a reply pikuri
+    # cannot parse ({#relaying}) — the server's bug, and dying on it would be the
+    # one failure mode this stance exists to prevent.
+    class Navigator
+      # Items a +prepare+ hop may produce before the rest are dropped with a note.
+      # +prepare+ can legitimately answer several — Java overloads, one name
+      # declared in several classes — and the model has no more idea which is meant
+      # than this does, so each is queried and the results are labelled.
+      MAX_PREPARED = 3
+
+      # @param servers [Servers] the live clients.
+      # @param filesystem [Pikuri::Workspace::Filesystem] path resolution, root
+      #   confinement, the denylist pass and the seam every read routes through.
+      # @param on_progress [Proc, nil] called with a {ServerProgress} while a wait
+      #   blocks — on *this* thread, which is what makes it safe to emit as an
+      #   agent event.
+      # @param cancellable [Pikuri::Agent::Control::Cancellable, nil] polled by
+      #   every wait and every request.
+      def initialize(servers:, filesystem:, on_progress: nil, cancellable: nil)
+        @servers = servers
+        @filesystem = filesystem
+        @on_progress = on_progress || ->(_progress) {}
+        @cancellable = cancellable
+        @ready = []
+        @texts = {}
+        @opened = []
+      end
+
+      # Answer one call.
+      #
+      # @param operation [String] an {Operation} name; +Tool::Parameters+ has
+      #   already refused anything outside the enum.
+      # @param symbol [String] the name to ask about.
+      # @param file [String, nil] workspace-relative or absolute; the server
+      #   selector, and the document an anchor is located in.
+      # @param line [Integer, nil] 1-based, as +read+ and +grep+ print it.
+      # @return [String] the observation, including +"Error: …"+ for everything
+      #   the model can react to.
+      # @raise [Pikuri::Agent::Control::Cancellable::Cancelled] on cancellation —
+      #   deliberately *not* an observation.
+      def navigate(operation:, symbol:, file: nil, line: nil)
+        op = Operation[operation]
+        raise ArgumentError, "unknown lsp operation #{operation.inspect}" if op.nil?
+
+        renderer = Renderer.new(sources: Sources.new(filesystem: @filesystem))
+        @ready = []
+        @texts = {}
+        @opened = []
+        raise Refusal, 'no language server is configured' if @servers.empty?
+
+        dispatch(op, symbol, file, line, renderer)
+      rescue Refusal, Pikuri::Workspace::Filesystem::Error, ClientWrapper::ServerDied => e
+        "Error: #{e.message}"
+      rescue Connection::ServerError => e
+        "Error: the language server refused #{operation}: #{e.message}"
+      ensure
+        release_documents
+      end
+
+      private
+
+      def dispatch(operation, symbol, file, line, renderer)
+        case operation.anchor
+        when :query then fan_out(operation, symbol, renderer)
+        when :document then outline(operation, symbol, file, renderer)
+        else positional(operation, symbol, file, line, renderer)
+        end
+      end
+
+      # +workspaceSymbol+ takes no position at all, so every server that can search
+      # is asked. Fanning out starts each of them and costs the *first* call their
+      # remaining index time — the accepted price of a question that names no file,
+      # and why {Servers#active} narrows the set to servers the project has files
+      # for.
+      def fan_out(operation, symbol, renderer)
+        clients = @servers.active
+        raise Refusal, no_relevant_server_message if clients.empty?
+
+        usable, refusing = clients.partition { |client| client.supports?(operation.capability) }
+        raise Refusal, unsupported_message(operation, clients) if usable.empty?
+
+        refusing.each { |client| renderer.note(cannot_answer(operation, client)) }
+        blocks = usable.map do |client|
+          ensure_ready(client)
+          rows = client.request(operation.request, { query: symbol }, cancellable: @cancellable)
+          block = relaying(operation, client) do
+            renderer.symbols(Array(rows), operation: operation, symbol: symbol, client: client)
+          end
+          usable.length > 1 ? "From the #{client.entry.id} server:\n#{block}" : block
+        end
+        renderer.finish(blocks.join("\n\n"))
+      end
+
+      # +documentSymbol+: the only file-keyed operation, and the one route from a
+      # method *name* to a position where a server's project-wide index holds
+      # types only.
+      def outline(operation, symbol, file, renderer)
+        raise Refusal, "#{operation.name} outlines one file, so it needs file:" if file.nil?
+
+        resolved = readable(file)
+        client = @servers.client_for(resolved)
+        raise Refusal, Anchor.no_server_message(resolved) if client.nil?
+        raise Refusal, unsupported_message(operation, [client]) unless client.supports?(operation.capability)
+
+        ensure_ready(client)
+        uri = open_document(client, resolved)
+        rows = client.request(operation.request, { textDocument: { uri: uri } }, cancellable: @cancellable)
+        renderer.finish(relaying(operation, client) do
+          renderer.symbols(Array(rows), operation: operation, symbol: symbol, client: client, uri: uri)
+        end)
+      end
+
+      # Everything with a cursor. The capability check is per *anchor*, not per
+      # call: a bare name fans out, so two anchors can sit on two servers with
+      # different capability sets.
+      def positional(operation, symbol, file, line, renderer)
+        resolution = Anchor.resolve(servers: @servers, filesystem: @filesystem, symbol: symbol,
+                                    file: file, line: line, ready: method(:ensure_ready))
+        resolution.notes.each { |note| renderer.note(note) }
+        anchors = resolution.anchors.select { |anchor| anchor.client.supports?(operation.capability) }
+        if anchors.empty?
+          raise Refusal, unsupported_message(operation, resolution.anchors.map(&:client).uniq)
+        end
+
+        answers = anchors.map { |anchor| [anchor, answer(operation, anchor, symbol, renderer)] }
+        renderer.finish(merge(answers))
+      end
+
+      # One anchor, one answer. Identical answers from several anchors collapse in
+      # {#merge}; different ones are labelled by column, which is what replaces the
+      # +character+ parameter for +names = names.trim()+.
+      def answer(operation, anchor, symbol, renderer)
+        client = anchor.client
+        ensure_ready(client)
+        open_document(client, Pathname.new(anchor.path))
+
+        relaying(operation, client) do
+          case operation.shape
+          when :hover
+            renderer.hover(request(client, operation.request, anchor.params),
+                           operation: operation, symbol: symbol)
+          when :calls
+            renderer.calls(hierarchy(operation, anchor, symbol, renderer),
+                           operation: operation, symbol: symbol, client: client)
+          when :supertypes
+            renderer.supertypes(ancestry(operation, anchor, symbol, renderer),
+                                operation: operation, symbol: symbol)
+          else
+            result = request(client, operation.request, location_params(operation, anchor))
+            renderer.locations(Location.list_from_wire(result, encoding: client.position_encoding),
+                               operation: operation, symbol: symbol, client: client)
+          end
+        end
+      end
+
+      # A reply whose *shape* pikuri cannot read is the server's bug, not
+      # pikuri's, so it is relayed like everything else the server said. Without
+      # this the wire types raise +KeyError+ for a location missing its +range+ and
+      # +ArgumentError+ for a +definition+ that answered a bare String, and the
+      # turn dies on a message nobody sees — which is the one thing the relay
+      # stance is supposed to prevent.
+      def relaying(operation, client)
+        yield
+      rescue KeyError, TypeError, ArgumentError => e
+        raise Refusal, "the #{client.entry.id} server's #{operation.name} reply could not be " \
+                       "read (#{e.class}: #{e.message})"
+      end
+
+      # The declaration is a reference too — a caller asking "who uses this" wants
+      # it in the list, and every shipped harness includes it.
+      def location_params(operation, anchor)
+        params = anchor.params
+        params = params.merge(context: { includeDeclaration: true }) if operation.name == 'findReferences'
+        params
+      end
+
+      # The +prepare+ hop, collapsed. LSP makes both hierarchies a two-step chain
+      # and both harnesses that ship the call family hand the model the
+      # intermediate item to echo back; running it here costs one round trip the
+      # model never sees.
+      def prepared(operation, anchor, symbol, renderer)
+        items = Array(request(anchor.client, operation.prepare, anchor.params))
+        exact = items.select { |item| SymbolName.matches?(item['name'], symbol) }
+        chosen = exact.empty? ? items : exact
+        if exact.empty? && !items.empty?
+          renderer.note("nothing the server prepared here is named #{symbol.inspect}; it offered " \
+                        "#{items.map { |item| item['name'] }.uniq.join(', ')}.")
+        end
+        if chosen.length > MAX_PREPARED
+          renderer.note("#{chosen.length} declarations were prepared for #{symbol.inspect}; the " \
+                        "first #{MAX_PREPARED} were queried.")
+        end
+        chosen.first(MAX_PREPARED)
+      end
+
+      def hierarchy(operation, anchor, symbol, renderer)
+        prepared(operation, anchor, symbol, renderer).flat_map do |item|
+          Array(request(anchor.client, operation.request, { item: item }))
+        end
+      end
+
+      # The ancestor *chain*, walked level by level — which is the whole value of
+      # the operation, since a definition hop on the name after +extends+ answers
+      # one level and the chain costs one round trip per level.
+      #
+      # Each level is deduplicated by name before the next query, or a Ruby
+      # namespace reopened in 14 files would fan out into 14 queries for the level
+      # above it.
+      def ancestry(operation, anchor, symbol, renderer)
+        current = prepared(operation, anchor, symbol, renderer)
+        levels = []
+        operation.cap.times do
+          parents = current.flat_map { |item| Array(request(anchor.client, operation.request, { item: item })) }
+          break if parents.empty?
+
+          levels << parents
+          current = parents.group_by { |item| item['name'].to_s }.values.map(&:last).first(2)
+        end
+        if levels.length == operation.cap
+          renderer.note("the chain was walked #{operation.cap} levels deep and did not end there.")
+        end
+        levels
+      end
+
+      def request(client, method, params)
+        client.request(method, params, cancellable: @cancellable)
+      end
+
+      # Identical bodies collapse — the overwhelmingly common case, since a
+      # repeated identifier on one line usually denotes the same entity.
+      def merge(answers)
+        grouped = answers.group_by(&:last)
+        return grouped.keys.first if grouped.length == 1
+
+        grouped.map do |text, pairs|
+          "At #{pairs.map { |anchor, _| anchor.to_s }.join(', ')}:\n#{text}"
+        end.join("\n\n")
+      end
+
+      # Blocks until the index is built, emitting progress on this thread. Memoized
+      # per call, so a fan-out over three anchors on one server costs one wait.
+      def ensure_ready(client)
+        return if @ready.include?(client.entry.id)
+
+        client.wait_until_ready(cancellable: @cancellable) { |progress| @on_progress.call(progress) }
+        @ready << client.entry.id
+      rescue ClientWrapper::ServerDied => e
+        raise Refusal, "the #{client.entry.id} server died while its index was building: #{e.message}"
+      end
+
+      # The re-open, once per document per call, with the text on disk *now*.
+      def open_document(client, resolved)
+        uri = Uris.for_path(resolved)
+        unless @texts.key?(resolved.to_s)
+          client.open_document(resolved.to_s, text_of(resolved))
+          @opened << [client, resolved.to_s]
+        end
+        uri
+      end
+
+      # Give back every document this call opened, once every reply is in.
+      #
+      # Per *call*, not per request: +supertypes+ and the call-hierarchy operations
+      # ask several questions about one document, and a close after the first would
+      # drop it under the rest.
+      def release_documents
+        opened = @opened
+        @opened = []
+        opened.each { |client, path| client.close_document(path) }
+      end
+
+      # Through the seam, always: the text a +didOpen+ carries is a read of a
+      # workspace file like any other.
+      def text_of(resolved)
+        @texts[resolved.to_s] ||= @filesystem.resolve_for_read(resolved).read
+      end
+
+      def readable(file)
+        resolved = @filesystem.resolve_for_read(file)
+        raise Refusal, "#{file}: no such file in the workspace" unless resolved.file?
+
+        resolved
+      end
+
+      def unsupported_message(operation, clients)
+        ids = clients.map { |client| client.entry.id }
+        "the #{ids.join(' and ')} server does not support #{operation.name} in this workspace — " \
+          "it advertises no #{operation.capability}"
+      end
+
+      def cannot_answer(operation, client)
+        "the #{client.entry.id} server does not support #{operation.name}, so its files were not searched."
+      end
+
+      def no_relevant_server_message
+        ids = @servers.registry.entries.map(&:id)
+        "no configured language server has files in this project (configured: #{ids.join(', ')}) — " \
+          'name a file to ask a specific one'
+      end
+    end
+  end
+end