openlanes 3.0.0 → 3.0.1

data/lib/openlanes/live/copilot/brief.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Live
+    class Copilot
+      # What c3po-operator is told with each message: the board as it stands,
+      # where to read further, and the person's words.
+      #
+      # The board lives in Redis, which the agent cannot read: its Bash runs
+      # only `openlanes` commands that read state, and none of them prints the
+      # live board. So the server reads the snapshot and writes it in here,
+      # fresh with every message, since the run moves between two questions.
+      # It is written as lines rather than the snapshot's JSON because the
+      # agent pays for every token of it on every message.
+      class Brief
+        # Recent log lines carried.
+        LOG_LINES = 20
+
+        # Characters of a question's body carried; the agent reads the rest
+        # from blocked.md when it needs it.
+        BODY = 400
+
+        # @param text [String] what the person typed
+        # @param board [Hash, nil] this node's `Snapshot` as parsed JSON
+        # @param others [Array<Hash>] other machines' snapshots
+        # @param plans_dir [String]
+        # @param trace_dir [String]
+        def initialize(text:, board:, plans_dir:, trace_dir:, others: [])
+          @text = text
+          @board = board
+          @others = others
+          @plans_dir = plans_dir
+          @trace_dir = trace_dir
+        end
+
+        # @return [String]
+        def to_s
+          [board, others, where, "## The person says\n\n#{@text}"].compact.join("\n\n")
+        end
+
+        private
+
+        # @return [String]
+        def board
+          return "## The board\n\nNo engine is publishing a board for this checkout: no run is going, or it has ended." unless @board
+
+          run = @board["run"] || {}
+          lines = ["## The board at #{@board["at"]}",
+                   "",
+                   "Run #{run["status"]}, #{run["agents_working"].to_i} agents working, ↑ #{run["up"].to_i} ↓ #{run["down"].to_i} tokens, " \
+                   "$#{format("%.2f", run["cost"].to_f)}."]
+          plans = Array(@board["plans"])
+          lines << (plans.empty? ? "No plans on this machine's board." : "")
+          plans.each { lines.concat(plan(it)) }
+          backlog = Array(@board["backlog"])
+          lines << "Backlog: #{backlog.map { "#{it["ordinal"]} #{it["title"]} (#{it.dig("status", "label")})" }.join("; ")}" unless backlog.empty?
+          lines.concat(log)
+          lines.join("\n")
+        end
+
+        # @param plan [Hash]
+        # @return [Array<String>]
+        def plan(plan)
+          lines = ["- #{plan["ordinal"]} #{plan["title"]}: #{plan.dig("status", "emoji")} #{plan.dig("status", "label")}, " \
+                   "#{plan["lane"]} lane, #{minutes(plan["elapsed"])} worked, $#{format("%.2f", plan["cost"].to_f)}" \
+                   "#{", PR ##{plan.dig("pr", "number")} #{plan.dig("pr", "state")}" if plan["pr"]}"]
+          Array(plan["cars"]).each { lines << car(it) }
+          Array(plan["questions"]).each { lines << question(it) }
+          if (stop = plan["interrupted"])
+            lines << "  - interrupted: #{stop["agent"]} at #{stop["at"]}: #{stop["note"]}"
+          end
+          lines
+        end
+
+        # @param car [Hash]
+        # @return [String]
+        def car(car)
+          "  - car #{car["key"]}: #{car["state"]}#{", #{car["phase"]}" if car["phase"]}, round #{car["round"]}/#{car["rounds"]}, " \
+            "#{car["model"]}, ↑ #{car["up"].to_i} ↓ #{car["down"].to_i}, #{minutes(car["elapsed"])} elapsed" \
+            "#{", #{minutes(car["remaining"])} left" if car["remaining"]}#{", held" if car["held"]}: #{car["message"].to_s.inspect}"
+        end
+
+        # @param question [Hash]
+        # @return [String]
+        def question(question)
+          body = question["body"].to_s.gsub(/\s+/, " ").strip
+          body = "#{body[0, BODY]}…" if body.length > BODY
+          "  - question #{question["id"]} (#{question["owner"]}, asked by #{question["agent"] || "unknown"}" \
+            "#{", held" if question["held"]}): #{question["heading"]}: #{body}"
+        end
+
+        # @return [Array<String>]
+        def log
+          lines = Array(@board["log"]).last(LOG_LINES)
+          return [] if lines.empty?
+
+          ["", "Recent log, newest last:"] + lines.map { "  #{it["at"]} #{it["source"]} #{it["level"]}: #{it["text"]}" }
+        end
+
+        # @return [String, nil]
+        def others
+          return nil if @others.empty?
+
+          machines = @others.map do |snapshot|
+            node = snapshot["node"] || {}
+            plans = Array(snapshot["plans"]).map { "#{it["ordinal"]} #{it.dig("status", "label")}" }
+            "- #{node["user"]}@#{node["host"]}: #{plans.empty? ? "no plans" : plans.join(", ")}"
+          end
+          "## Other machines (read only)\n\n#{machines.join("\n")}"
+        end
+
+        # @return [String]
+        def where
+          <<~TEXT.strip
+            ## Where to read more
+
+            - Plan folders: #{@plans_dir}. Each holds spec.md, plan.md, blocked.md when blocked, and state.json with its signatures and mailbox.
+            - Agents' transcripts: #{@trace_dir}, one NDJSON file per invocation, named by time, plan and agent.
+          TEXT
+        end
+
+        # @param seconds [Numeric, nil]
+        # @return [String]
+        def minutes(seconds) = "#{(seconds.to_f / 60).round}m"
+      end
+    end
+  end
+end

data/lib/openlanes/live/copilot/cards.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "json"
+
+module OpenLanes
+  module Live
+    class Copilot
+      # How what c3po-operator wrote becomes the turns the page draws.
+      #
+      # The agent writes prose, and wherever it wants the page to draw a card
+      # it writes one fenced block whose info string is `c3po`, holding one
+      # JSON object:
+      #
+      #   ```c3po
+      #   {"card": "confirm", "text": "luke has not moved in 20 minutes.",
+      #    "command": {"kind": "stop", "plan": "002", "agent": "luke-backend"},
+      #    "confirm": "Stop luke-backend", "done": "luke-backend was asked to stop"}
+      #   ```
+      #
+      #   ```c3po
+      #   {"card": "draft", "question": "002/B1", "draft": "Ninety days.", "text": "A draft:"}
+      #   ```
+      #
+      # The agent proposes; this module decides. A card is drawn only when
+      # every check passes: the JSON parses, the card is one of the two kinds,
+      # a confirm card's command is one of {CONFIRMABLE} and one the command
+      # gate itself would take ({Command.parse}, W13), and what it names is on
+      # this node's board. Anything else comes back as plain text with the
+      # reason, so a card the agent got wrong is something the person reads,
+      # never something the page can send. Nothing here sends anything: even a
+      # good card only reaches the engine when the person presses its button.
+      module Cards
+        # A card: a fence opened with exactly `c3po` and closed on a line of its
+        # own. An unclosed one does not match, and so stays prose.
+        FENCE = /^```c3po[ \t]*\r?\n(.*?)^```[ \t]*$/m
+
+        # The commands a confirm card may carry: W17's "stop, discard and stop
+        # run", the ones that cannot be undone and so wait for a person.
+        # Message and hold are left out on purpose: the engine files a
+        # `message` in the plan's mailbox as from `human`, and a card the
+        # person confirms without reading would put the copilot's words there
+        # under the person's name.
+        CONFIRMABLE = %w[stop discard stop_all].freeze
+
+        # Cards one answer may offer. More is a model listing every action it
+        # can think of, and a wall of red buttons is not a question.
+        MAX = 3
+
+        # Characters a confirm button's label may hold.
+        LABEL = 60
+
+        # Characters the line a confirm card shows once accepted may hold.
+        DONE = 200
+
+        # Characters one prose turn keeps. A model that pastes a whole
+        # transcript back is cut here rather than sent to every open page.
+        PROSE = 20_000
+
+        # A question's id, as the board writes it: `<ordinal>/B<n>`.
+        QUESTION = %r{\A[0-9]{3}(?:\.[0-9]{2})?/B[1-9][0-9]*\z}
+
+        # What an answer with nothing in it reads as.
+        SILENT = "c3po-operator finished without saying anything."
+
+        module_function
+
+        # @param answer [String, nil] the agent's final message
+        # @param id [String] the person's message id; the turns are `<id>.1`, `<id>.2`, …
+        # @param usage [Hash, nil] `{model, up, down}`, carried by every turn
+        # @param board [Hash, nil] this node's `Snapshot` as parsed JSON; nil
+        #   when no engine is publishing one, and then no card names anything
+        # @return [Array<OpenLanes::Live::Copilot::Turn>]
+        def turns(answer, id:, usage: nil, board: nil)
+          offered = 0
+          said = pieces(answer.to_s).filter_map do |kind, body|
+            next prose(body) if kind == :prose
+
+            offered += 1
+            offered > MAX ? refused(body, "an answer offers at most #{MAX} cards") : card(body, board)
+          end
+          said = [{ kind: "text", text: SILENT }] if said.empty?
+          said.each_with_index.map do |piece, index|
+            Turn.new(id: "#{id}.#{index + 1}", from: "copilot", usage:, fields: {}, **piece)
+          end
+        end
+
+        # The answer cut into prose and card bodies, in the order written.
+        #
+        # @param answer [String]
+        # @return [Array<Array(Symbol, String)>]
+        def pieces(answer)
+          found = []
+          at = 0
+          while (match = FENCE.match(answer, at))
+            found << [:prose, answer[at...match.begin(0)]] << [:card, match[1]]
+            at = match.end(0)
+          end
+          found << [:prose, answer[at..]]
+        end
+
+        # @param body [String]
+        # @return [Hash, nil] nil for whitespace between cards
+        def prose(body)
+          text = body.strip
+          return nil if text.empty?
+
+          { kind: "text", text: text.length > PROSE ? "#{text[0, PROSE]}…" : text }
+        end
+
+        # @param body [String] the JSON between the fences
+        # @param board [Hash, nil]
+        # @return [Hash] a card, or the text it degrades to
+        def card(body, board)
+          data = JSON.parse(body)
+          raise Invalid, "a card is one JSON object" unless data.is_a?(Hash)
+
+          data = data.transform_keys(&:to_s)
+          case data["card"]
+          when "confirm" then confirm(data, board)
+          when "draft" then draft(data, board)
+          else raise Invalid, "#{data["card"].inspect} is not a card; there are confirm and draft"
+          end
+        rescue JSON::ParserError
+          refused(body, "it is not JSON")
+        rescue Invalid, Command::Invalid => e
+          refused(body, e.message)
+        end
+
+        # @param data [Hash]
+        # @param board [Hash, nil]
+        # @return [Hash]
+        # @raise [OpenLanes::Live::Copilot::Invalid, OpenLanes::Live::Command::Invalid]
+        def confirm(data, board)
+          raw = data["command"]
+          raise Invalid, "a confirm card needs a command object" unless raw.is_a?(Hash)
+
+          raw = raw.transform_keys(&:to_s)
+          kind = raw["kind"].to_s
+          raise Invalid, "#{kind.inspect} is not a command c3po-operator may offer; it offers #{CONFIRMABLE.join(", ")}" unless CONFIRMABLE.include?(kind)
+
+          # The payload is dropped: none of these kinds reads one, and a card
+          # carries exactly what its button says and nothing the person cannot see.
+          command = Command.parse(raw.slice("kind", "plan", "agent").merge("id" => "card", "payload" => {}))
+          on_board!(command, board)
+          { kind:   "confirm",
+            text:   words(data["text"], LIMIT) || "This needs you to confirm it.",
+            fields: { "command" => command.wire.except(:id).transform_keys(&:to_s),
+                      "confirm" => words(data["confirm"], LABEL) || raise(Invalid, "a confirm card needs its button's label"),
+                      "done"    => words(data["done"], DONE) || raise(Invalid, "a confirm card needs what it says once done") } }
+        end
+
+        # @param data [Hash]
+        # @param board [Hash, nil]
+        # @return [Hash]
+        # @raise [OpenLanes::Live::Copilot::Invalid]
+        def draft(data, board)
+          question = data["question"].to_s
+          raise Invalid, "#{question.inspect} is not a question id like 002/B1" unless question.match?(QUESTION)
+
+          # The board writes ids in full (`002.00/B1`); the agent may write `002/B1`.
+          plan, number = question.split("/")
+          question = "#{ordinal(plan)}/#{number}"
+          raise Invalid, "no question #{question} is waiting on this board" unless questions(board).include?(question)
+
+          draft = words(data["draft"], LIMIT) or raise Invalid, "a draft card needs the draft"
+          { kind: "draft", text: words(data["text"], LIMIT) || "A draft answer to #{question}.",
+            fields: { "question" => question, "draft" => draft } }
+        end
+
+        # The engine refuses a command for a plan or a car it does not have,
+        # but only once the person has pressed the button. Checking here keeps
+        # a card for something that is not running off the page altogether.
+        #
+        # @param command [OpenLanes::Live::Command]
+        # @param board [Hash, nil]
+        # @return [void]
+        # @raise [OpenLanes::Live::Copilot::Invalid]
+        def on_board!(command, board)
+          raise Invalid, "no run is publishing a board here, so there is nothing to act on" if board.nil?
+          return unless Command::PLAN_KINDS.include?(command.kind)
+
+          plan = Array(board["plans"]).find { ordinal(it["ordinal"]) == ordinal(command.plan) }
+          raise Invalid, "plan #{command.plan} is not on this board" unless plan
+          return unless Command::AGENT_KINDS.include?(command.kind)
+          return if Array(plan["cars"]).any? { it["agent"] == command.agent }
+
+          raise Invalid, "#{command.agent} is not working #{command.plan}"
+        end
+
+        # @param board [Hash, nil]
+        # @return [Array<String>] every question id waiting on the board
+        def questions(board) = Array(board&.dig("plans")).flat_map { Array(it["questions"]) }.map { it["id"].to_s }
+
+        # @param value [Object]
+        # @return [String, nil]
+        def ordinal(value) = Plans::Ordinal.parse(value.to_s)&.to_s || value.to_s
+
+        # @param value [Object]
+        # @param limit [Integer]
+        # @return [String, nil] stripped, nil when empty
+        # @raise [OpenLanes::Live::Copilot::Invalid] when longer than +limit+
+        def words(value, limit)
+          return nil unless value.is_a?(String)
+
+          text = value.strip
+          return nil if text.empty?
+          raise Invalid, "#{text[0, 24].inspect}… is longer than #{limit} characters" if text.length > limit
+
+          text
+        end
+
+        # What a card the gate would not take becomes: its body as text, with
+        # the reason, so the person sees what was meant and nothing is sent.
+        #
+        # @param body [String]
+        # @param reason [String]
+        # @return [Hash]
+        def refused(body, reason)
+          { kind: "text",
+            text: "I wrote a card the control room does not accept (#{reason}), so nothing was offered. " \
+                  "What I wrote:\n\n#{body.strip[0, PROSE]}" }
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/live/copilot/operator.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module OpenLanes
+  module Live
+    class Copilot
+      # c3po-operator itself (W17): the responder the API server hands
+      # {Copilot}. Each message the person sends becomes one `claude -p`,
+      # resumed from the conversation's session, so the agent remembers what
+      # was said before; it answers in prose and `c3po` cards, which {Cards}
+      # turns into the turns the page draws.
+      #
+      # It runs in the API server because that is where the conversation
+      # already arrives and is stored: the server takes the message, answers
+      # it, and writes the answer to the stream the page follows. It needs no
+      # engine, so it also answers under `openlanes web` alone, after a run
+      # has ended. The server calls it through {Copilot#answer} on its
+      # background path ({Web::Context#background}), apart from the request,
+      # and on that thread's own Redis connection; a failure that escapes
+      # here is answered for by {Copilot#answer}. Messages are answered one
+      # at a time, so two `claude` processes never resume one session at once.
+      #
+      # The boundary is the plan agents' boundary, narrowed. The tools are
+      # fixed to {TOOLS} and the Bash commands to the agent's `allowed_tools`,
+      # the read-only `openlanes` queries; {Execution::Executor#denied_for}
+      # adds the network tools and every command that leaves the machine, and
+      # {WRITE_TOOLS} goes on top. And it acts on nothing: a card is a
+      # proposal, sent only when the person presses its button.
+      class Operator
+        # The agent's definition, in `agents/`.
+        NAME = "c3po-operator"
+
+        # The only built-in tools it has: reading files, and Bash for the
+        # `openlanes` queries its definition allows.
+        TOOLS = %w[Read Grep Glob Bash].freeze
+
+        # Denied as well, should a CLI or a settings file offer them anyway:
+        # it never edits code or plan documents (W17), and a sub-agent would
+        # start with tools of its own.
+        WRITE_TOOLS = %w[Edit Write MultiEdit NotebookEdit Task Agent].freeze
+
+        # What `claude -p --resume` prints, on stderr, for a session it does not have.
+        MISSING = /No conversation found with session ID/
+
+        # Seconds an answer may take when the definition names none.
+        TIMEOUT = 180
+
+        # @param root [String] the checkout
+        # @param plans_dir [String]
+        # @param stores [#current] a store per thread; the answering thread
+        #   takes its own, which the server's background path releases
+        # @param keys [OpenLanes::Live::Keys]
+        # @param agent [OpenLanes::Agents::Agent]
+        # @param spawn [Proc] `argv, chdir:, env:` → {Execution::Child}; the suite's seam
+        # @param trace_dir [String] where each answer's raw stream is kept, and
+        #   where the agents' transcripts are read from
+        def initialize(root:, plans_dir:, stores:, keys:, agent: Agents.find(NAME), spawn: Execution::Child.method(:spawn),
+          trace_dir: Execution::Executor::TRACE_DIR)
+          raise OpenLanes::Error, "no agent definition named #{NAME}" unless agent
+
+          @root = File.expand_path(root)
+          @plans_dir = plans_dir
+          @stores = stores
+          @keys = keys
+          @agent = agent
+          @spawn = spawn
+          @trace_dir = trace_dir
+          @mutex = Mutex.new
+          @turns = Mutex.new
+          @child = nil
+          @stopped = false
+        end
+
+        # Answer one message, the responder's side of {Copilot#answer}: run
+        # the agent, keep its session and what it spent, and turn what it
+        # said into turns. A run that fails is answered as text saying why; a
+        # message that waits while another is answered waits its turn.
+        #
+        # @param turn [OpenLanes::Live::Copilot::Turn] the person's
+        # @return [Array<OpenLanes::Live::Copilot::Turn>]
+        # @raise [OpenLanes::Error] when the server is stopping
+        def call(turn) = @turns.synchronize { answer(turn) }
+
+        # @param turn [OpenLanes::Live::Copilot::Turn]
+        # @return [Array<OpenLanes::Live::Copilot::Turn>]
+        def answer(turn)
+          raise OpenLanes::Error, "the server is stopping" if @stopped
+
+          board = Live.board(store:, keys: @keys)
+          brief = Brief.new(text: turn.text, board: board[:me], others: board[:others], plans_dir: @plans_dir, trace_dir: @trace_dir)
+          record = session
+          run = invoke(brief.to_s, record["session"])
+          # A session `claude` no longer has (its history was cleared, or the
+          # conversation was started on another machine) fails at once; the
+          # conversation starts again rather than staying broken.
+          if stale?(run, record)
+            store.hdel(@keys.copilot_session, "session")
+            run = invoke(brief.to_s, nil)
+          end
+          usage = spend(run, record)
+          return [failure(turn, run, usage)] unless run.ok
+
+          Cards.turns(run.transcript.result, id: turn.id, usage:, board: board[:me])
+        end
+
+        # Stop answering: the message under way is cut short, and any still
+        # waiting is answered with why. The server calls it on its way down.
+        #
+        # @return [void]
+        def stop
+          child = @mutex.synchronize do
+            @stopped = true
+            @child
+          end
+          child&.terminate(grace: 1, drain: 1)
+        end
+
+        # The argv one answer runs, exposed so a spec can check the boundary
+        # without starting anything.
+        #
+        # @param prompt [String]
+        # @param session [String, nil] the conversation to carry on
+        # @return [Array<String>]
+        def argv(prompt, session)
+          profile.adapter.argv(
+            Adapters::Invocation.new(prompt:,
+              root:            @root,
+              model:           profile.model,
+              effort:          profile.effort,
+              allowed_tools:   @agent.allowed_tools,
+              denied_tools:    executor.denied_for(@agent) + WRITE_TOOLS,
+              denied_commands: executor.denied_commands(@agent),
+              network:         @agent.network,
+              resume:          (session if profile.adapter.resumes?),
+              dirs:            [@trace_dir],
+              brief:           false,
+              tools:           TOOLS,
+              system:          @agent.prompt)
+          )
+        end
+
+        # @return [OpenLanes::Agents::Profile]
+        def profile = @profile ||= Agents::Profile.resolve(@agent)
+
+        private
+
+        # What one `claude -p` did.
+        Run = Data.define(:ok, :transcript, :note)
+
+        # @return [OpenLanes::Live::Store, OpenLanes::Live::MemoryStore] this thread's
+        def store = @stores.current
+
+        # @param prompt [String]
+        # @param session [String, nil]
+        # @return [Run]
+        def invoke(prompt, session)
+          FileUtils.mkdir_p(@trace_dir)
+          trace = File.join(@trace_dir,
+            format("%s-copilot-%s-%d-%04x.ndjson",
+              Time.now.strftime("%Y%m%d-%H%M%S"),
+              NAME,
+              Process.pid,
+              rand(0x10000)))
+          transcript = profile.adapter.transcript(trace:)
+          child = @spawn.call(argv(prompt, session), chdir: @root, env: profile.adapter.environment)
+          # {#stop} may have run while this was starting, and seen no child to end.
+          stopping = @mutex.synchronize do
+            @child = child
+            @stopped
+          end
+          child.terminate(grace: 1, drain: 1) if stopping
+          status = watched(child) { child.each_chunk { transcript.push(it) } }
+          transcript.finish
+          Run.new(ok: status.success? && !transcript.failed? && !@timed_out, transcript:, note: note(status, transcript, trace))
+        ensure
+          transcript&.finish
+          @mutex.synchronize { @child = nil }
+        end
+
+        # Wait for the child, ending it once {#timeout} has passed. The
+        # answer is advisory; a copilot that hangs must not hold the next
+        # message for ever.
+        #
+        # @param child [OpenLanes::Execution::Child]
+        # @return [Process::Status]
+        def watched(child)
+          @timed_out = false
+          watchdog = Thread.new do
+            sleep(timeout)
+            @timed_out = true
+            child.terminate
+          end
+          yield
+          child.wait
+        ensure
+          watchdog&.kill
+        end
+
+        # @return [Boolean] whether `claude` said it has no such session, on one
+        #   it was asked to resume; any other failure is reported, not retried
+        def stale?(run, record)
+          !run.ok && record["session"] && [run.transcript.error, *run.transcript.plain].any? { it.to_s.match?(MISSING) }
+        end
+
+        # @return [Integer] seconds
+        def timeout = @agent.timeout || TIMEOUT
+
+        # @return [String] why an answer failed, for the person
+        def note(status, transcript, trace)
+          return "it took longer than #{timeout} seconds" if @timed_out
+          return "#{profile.adapter.executable} reported: #{transcript.error}" if transcript.failed?
+          return "#{profile.adapter.executable} exited #{status.exitstatus}: #{transcript.plain.last(3).join(" ")}" unless status.success?
+
+          "trace: #{trace}"
+        end
+
+        # The session, the model and the running total, kept in Redis
+        # ({Keys#copilot_session}) so the next message, from this server or
+        # one started after it, carries on the same conversation.
+        #
+        # @param run [Run]
+        # @param record [Hash{String => String}]
+        # @return [Hash] `{model, up, down}`
+        def spend(run, record)
+          usage = { model: model, up: record["up"].to_i + run.transcript.up, down: record["down"].to_i + run.transcript.down }
+          key = @keys.copilot_session
+          store.hset(key, "session", run.transcript.session) if run.transcript.session
+          store.hset(key, "model", usage[:model].to_s)
+          store.hset(key, "up", usage[:up])
+          store.hset(key, "down", usage[:down])
+          usage
+        end
+
+        # @return [Hash{String => String}]
+        def session = store.hgetall(@keys.copilot_session)
+
+        # The full id the header shows, as a car's does.
+        #
+        # @return [String, nil]
+        def model = profile.adapter.model_entry(profile.model)&.id || profile.model
+
+        # @return [OpenLanes::Live::Copilot::Turn]
+        def failure(turn, run, usage)
+          Turn.new(id: "#{turn.id}.1",
+            from: "copilot",
+            kind: "text",
+            usage:,
+            text: "c3po-operator could not answer: #{run.note}. Ask again, or look at the trace.")
+        end
+
+        # For its boundary only: who may run what, as plan agents are told.
+        #
+        # @return [OpenLanes::Execution::Executor]
+        def executor = @executor ||= Execution::Executor.new(root: @root)
+      end
+    end
+  end
+end