openlanes 3.0.1 → 3.1.0

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Live
+    class Copilot
+      # The three things a person may tell the run from the copilot's box
+      # (plan 020.00): `/stop NNN`, `/restart NNN` and `/concurrency N`. Each
+      # becomes an engine {Command} on the same stream the page's buttons use
+      # (W13), so c3po-operator stays read-only and the commands get the
+      # gate's idempotency, replies and logging for nothing.
+      #
+      # The grammar lives here and nowhere else: the page draws a hint but
+      # parses nothing, so page and server cannot disagree on what a command is.
+      module Slash
+        # What a slash message that is not one of the three is answered with.
+        #
+        # @!attribute [r] text
+        #   @return [String] the usage, then why this message was not a command
+        Help = Data.define(:text)
+
+        # The usage, which the help turn starts with.
+        USAGE = <<~TEXT.chomp
+          Slash commands:
+          /stop NNN — stop every agent on plan NNN and take it off the board
+          /restart NNN — start plan NNN again when it is on the board with no agent
+          /concurrency N — let N agents run at once; lowering it waits for agents to finish
+        TEXT
+
+        # Word to the command kind it queues.
+        PLAN_KINDS = { "stop" => "stop_plan", "restart" => "restart_plan" }.freeze
+
+        # @param text [String] the person's message, stripped
+        # @param id [String] the message id, which becomes the command's, so
+        #   the engine's reply and its copilot turn name the message
+        # @return [OpenLanes::Live::Command, Help, nil] nil when +text+ is not
+        #   a slash message, so it goes to the copilot as before
+        def self.parse(text, id:)
+          return unless text.start_with?("/")
+
+          word, *args = text.delete_prefix("/").split
+          word = word.to_s.downcase
+          if PLAN_KINDS.key?(word)
+            plan_command(word, args, id)
+          elsif word == "concurrency"
+            concurrency(args, id)
+          else
+            help("/#{word} is not one of them.")
+          end
+        end
+
+        # @return [OpenLanes::Live::Command, Help]
+        def self.plan_command(word, args, id)
+          plan = Plans::Ordinal.parse(args.first) if args.size == 1
+          return help("/#{word} needs a plan number, like /#{word} 20 or /#{word} 020.00.") unless plan
+
+          command(id, PLAN_KINDS.fetch(word), plan: plan.to_s)
+        end
+
+        # @return [OpenLanes::Live::Command, Help]
+        def self.concurrency(args, id)
+          limit = args.first.to_i if args.size == 1 && args.first.match?(/\A\d+\z/)
+          return help("/concurrency needs a whole number of at least 1, like /concurrency 3.") unless limit&.positive?
+
+          command(id, "set_concurrency", limit:)
+        end
+
+        # @return [OpenLanes::Live::Command]
+        def self.command(id, kind, plan: nil, **payload)
+          Command.parse("id" => id,
+            "kind" => kind,
+            "plan" => plan,
+            "payload" => payload.transform_keys(&:to_s).merge("source" => "copilot"))
+        end
+
+        # @return [Help]
+        def self.help(why) = Help.new(text: "#{USAGE}\n\n#{why}")
+
+        private_class_method :plan_command, :concurrency, :command, :help
+      end
+    end
+  end
+end

data/lib/openlanes/live/copilot.rb

@@ -59,17 +59,35 @@ module OpenLanes
       # whole of it would keep the page from showing the message, or that
       # the copilot is reading, until the answer was already written.
       #
+      # A slash command ({Slash}, plan 020.00) is not the copilot's to
+      # answer: it is queued for this node's engine under the message's id,
+      # and the engine's reply comes back into the conversation as turn
+      # `"<id>.1"`. A slash message that is not a command is answered here,
+      # at once, with the usage. Neither reaches the responder, so a server
+      # with no copilot still takes them, and {Turn#slash?} tells the caller
+      # not to {#answer} them.
+      #
       # @param input [String, Hash] `CopilotMessage`: `{id, text}`
       # @return [OpenLanes::Live::Copilot::Turn] the person's turn
       # @raise [OpenLanes::Live::Copilot::Invalid] for the API server's 422
-      # @raise [OpenLanes::Live::Copilot::Unanswered] when nobody would answer
+      # @raise [OpenLanes::Live::Copilot::Unanswered] when nobody would
+      #   answer: no copilot for plain text, no live engine for a command
       def say(input)
         turn = message(input)
+        slash = Slash.parse(turn.text, id: turn.id)
         # Refused before it is stored: a message kept where nothing will ever
         # answer it reads, on the page, as a copilot that is merely slow.
-        raise Unanswered, "the copilot is not running in this server" unless @responder
+        raise Unanswered, "the copilot is not running in this server" unless slash || @responder
+        if slash.is_a?(Command) && !engine?
+          raise Unanswered, "no engine is running to apply #{turn.text.split.first}"
+        end
 
-        turn.tap { append(it) }
+        append(turn)
+        case slash
+        when Command then EventBus.for(@store).append(@keys.commands, { json: JSON.generate(slash.wire) })
+        when Slash::Help then append(Turn.new(id: "#{turn.id}.1", from: "copilot", kind: "text", text: slash.text))
+        end
+        turn
       end
 
       # Store whatever the responder answers to +turn+. A responder that
@@ -136,12 +154,24 @@ module OpenLanes
         @store.xrevrange(@keys.copilot, count:).reverse.map { JSON.parse(it.fields["json"]) }
       end
 
+      # Whether this node's engine is there to read {Keys#commands}: its
+      # snapshot key lives only while it publishes (`EX 30`), so a command
+      # queued without one would sit unanswered and the page would read on.
+      #
+      # @return [Boolean]
+      def engine? = !@store.get(@keys.snapshot).nil?
+
       # @return [Hash, nil]
       def latest_usage(turns) = turns.reverse_each.map { it["usage"] }.find(&:itself)
 
+      # Written here, in the API server rather than by the Dispatcher, so the
+      # open streams are nudged here too: a turn has no other way to reach a
+      # stream that waits on {Keys#news}.
+      #
       # @return [void]
       def append(turn)
-        @store.xadd(@keys.copilot, { json: turn.to_json }, maxlen: Keys::COPILOT_LENGTH)
+        EventBus.for(@store).append(@keys.copilot, { json: turn.to_json }, maxlen: Keys::COPILOT_LENGTH)
+        News.publish(store: @store, keys: @keys, kind: "copilot")
       end
     end
 
@@ -174,6 +204,10 @@ module OpenLanes
         # @return [Hash] as the wire carries it
         def wire = { id:, from:, kind:, text:, at: at.utc.iso8601, usage: }.merge(fields.transform_keys(&:to_sym))
 
+        # @return [Boolean] whether this is the person's slash message, which
+        #   the engine or {Slash} answers and the copilot never does
+        def slash? = from == "you" && text.start_with?("/")
+
         # @return [String]
         def to_json(*) = JSON.generate(wire)
       end

data/lib/openlanes/live/event_bus/base.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Live
+    module EventBus
+      # What every bus answers, delegated to the store behind it.
+      class Base
+        # @return [OpenLanes::Live::Store, OpenLanes::Live::MemoryStore]
+        attr_reader :store
+
+        # @param store [OpenLanes::Live::Store, OpenLanes::Live::MemoryStore]
+        def initialize(store)
+          @store = store
+          freeze
+        end
+
+        # @param channel [String]
+        # @param payload [String]
+        # @return [Integer] how many subscriptions received it
+        def publish(channel, payload) = store.publish(channel, payload)
+
+        # A subscription of its own; the caller closes it.
+        #
+        # @param channels [Array<String>]
+        # @param patterns [Array<String>]
+        # @return [#next_message, #close]
+        def subscribe(channels: [], patterns: []) = store.subscriber(channels:, patterns:)
+
+        # A durable append, in stream order.
+        #
+        # @param stream [String]
+        # @param fields [Hash]
+        # @param maxlen [Integer, nil] approximate trim
+        # @return [String] the entry id
+        def append(stream, fields, maxlen: nil) = store.xadd(stream, fields, maxlen:)
+
+        # The appends and writes the block makes, applied atomically.
+        #
+        # @yieldparam tx [OpenLanes::Live::EventBus::Transaction]
+        # @return [void]
+        def transaction
+          store.multi { |raw| yield Transaction.new(raw) }
+        end
+
+        # The database pub/sub channel names carry (see {Keys#news}).
+        #
+        # @return [Integer]
+        def db = store.db
+      end
+    end
+  end
+end

data/lib/openlanes/live/event_bus/memory_bus.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Live
+    module EventBus
+      # The bus for the suite and `--demo`, over {MemoryStore}: one process,
+      # one keyspace, the same contract.
+      class MemoryBus < Base
+        # @param store [OpenLanes::Live::MemoryStore]
+        def initialize(store = MemoryStore.new) = super
+      end
+    end
+  end
+end

data/lib/openlanes/live/event_bus/redis_bus.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Live
+    module EventBus
+      # The production bus, over {Store}: Redis pub/sub and streams.
+      class RedisBus < Base; end
+    end
+  end
+end

data/lib/openlanes/live/event_bus/transaction.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Live
+    module EventBus
+      # One {Base#transaction} block's writes: {#append} for the streams, and
+      # the store's other writes ({Store::WRITES}) beside them, so a site that
+      # sets a key and appends an entry together keeps doing both atomically.
+      class Transaction
+        # @param raw [OpenLanes::Live::Store::Transaction]
+        def initialize(raw)
+          @raw = raw
+        end
+
+        # @param stream [String]
+        # @param fields [Hash]
+        # @param maxlen [Integer, nil]
+        # @return [nil]
+        def append(stream, fields, maxlen: nil) = @raw.xadd(stream, fields, maxlen:)
+
+        (Store::WRITES - %i[xadd]).each do |name|
+          define_method(name) { |*args, **kwargs| @raw.public_send(name, *args, **kwargs) }
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/live/event_bus.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Live
+    # The port every publish, subscribe and stream append goes through.
+    #
+    # Engine, Live and Web used to call `store.publish`, `store.subscriber`
+    # and `store.xadd` directly, on whichever of {Store} and {MemoryStore}
+    # they were handed, so the two shared a duck type nobody declared. A bus
+    # names that surface, and the stores become its backing: {RedisBus} over
+    # {Store}, {MemoryBus} over {MemoryStore}. Key layout, stream ids and the
+    # wire format are the store's, unchanged, because web cursors rely on them.
+    module EventBus
+      module_function
+
+      # The bus over +store+, or +store+ itself when it already is one.
+      #
+      # @param store [OpenLanes::Live::Store, OpenLanes::Live::MemoryStore, Base]
+      # @return [Base]
+      def for(store)
+        case store
+        when Base then store
+        when MemoryStore then MemoryBus.new(store)
+        else RedisBus.new(store)
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/live/interviewer.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module OpenLanes
+  module Live
+    # Grills a new idea before its spec.md is written (M6): the questions the
+    # agents downstream would otherwise block to ask, each as a short context
+    # paragraph and lettered options with exactly one recommended. The page
+    # asks them one at a time, and the answers reach {Commands#create_plans}
+    # as `payload.decisions`, which writes them into the spec.
+    #
+    # One call to a small model on OpenRouter, as {ChoiceConverter} makes,
+    # and every question is checked the same way: written with
+    # {Plans::Choices.write} and read back with {Plans::Choices.parse}. A
+    # question that does not survive the trip is dropped, not the interview:
+    # four good questions are worth asking without the fifth.
+    #
+    # A seam: the suite sets {Live.interviewer} to nil, and examples about it
+    # hand it an adapter double, so nothing in the tests reaches OpenRouter.
+    class Interviewer
+      # The most questions one idea is asked. A person is interviewed while
+      # they wait, so the list stays short (M0).
+      LIMIT = 5
+
+      # Seconds a person waits for the questions before the plan is created
+      # without them. The HTTP client alone allows 10 to connect and 30 to
+      # read, and a Puma thread and the dialog are held for all of it.
+      TIMEOUT = 20
+
+      # What the model reads with the idea.
+      PROMPT = <<~PROMPT.freeze
+        A person described a software feature they want built. Agents will turn it into a spec, a plan and
+        code without being able to ask anything, so interview the person now. Return `questions`: an array
+        of at most #{LIMIT} objects, the decisions that most change what gets built and that the idea leaves open.
+        Ask nothing the idea already answers. Each object is:
+
+        - `context`: one short paragraph saying what must be decided and why it matters.
+        - `options`: an array of 2 to 5 objects `{"label": String, "recommended": Boolean}`, each a distinct
+          answer on one short line. Exactly one has `"recommended": true`: the one you would choose.
+
+        Never add an option for "something else" or "type something instead": the page has a text box.
+        An idea that leaves nothing open gets an empty array.
+      PROMPT
+
+      # One question, ready for the page.
+      #
+      # @!attribute [r] context
+      #   @return [String]
+      # @!attribute [r] options
+      #   @return [Array<String>] labels, in order
+      # @!attribute [r] recommended
+      #   @return [Integer] the index of the recommended option
+      Question = Data.define(:context, :options, :recommended) do
+        # @return [Hash] as `POST /api/interview` sends it
+        def wire = { context:, options:, recommended: }
+      end
+
+      # An interviewer when OPENROUTER_API_KEY is set, nil otherwise.
+      #
+      # @param env [#[]]
+      # @param config [OpenLanes::Config]
+      # @return [OpenLanes::Live::Interviewer, nil]
+      def self.from_env(env = ENV, config: Config.current)
+        key = env["OPENROUTER_API_KEY"].to_s.strip
+        key.empty? ? nil : new(api_key: key, model: config.questions_model || ChoiceConverter::DEFAULT_MODEL)
+      end
+
+      # The model's questions, each cleaned the way {ChoiceConverter.render}
+      # cleans one, keeping those that survive.
+      #
+      # @param output [Hash] `questions`, as the adapter parsed it
+      # @return [Array<OpenLanes::Live::Interviewer::Question>] at most {LIMIT}
+      def self.render(output)
+        output = output.to_h.transform_keys(&:to_sym)
+        Array(output[:questions]).filter_map { question(it) }.first(LIMIT)
+      end
+
+      # @param raw [Object]
+      # @return [OpenLanes::Live::Interviewer::Question, nil]
+      def self.question(raw)
+        return unless raw.is_a?(Hash)
+
+        body = ChoiceConverter.render(raw)
+        choices = Plans::Choices.parse(body)
+        Question.new(context: choices.context,
+          options: choices.options.map(&:label),
+          recommended: choices.options.index(&:recommended))
+      rescue ChoiceConverter::Invalid
+        nil
+      end
+      private_class_method :question
+
+      # @param api_key [String, nil] OpenRouter's; only read to build the default adapter
+      # @param model [String] an OpenRouter model id
+      # @param adapter [#call, nil] answers `call(node, answers)` with a Hash
+      #   holding `questions`; built on first use when nil
+      # @param timeout [Numeric] seconds before the interview is given up
+      def initialize(api_key: nil, model: ChoiceConverter::DEFAULT_MODEL, adapter: nil, timeout: TIMEOUT)
+        @api_key = api_key
+        @model = model
+        @adapter = adapter
+        @timeout = timeout
+        @mutex = Mutex.new
+      end
+
+      # @return [String]
+      attr_reader :model
+
+      # Blocks for at most {TIMEOUT} seconds.
+      #
+      # @param idea [String] Markdown, as the idea dialog sends it
+      # @return [Array<OpenLanes::Live::Interviewer::Question>]
+      # @raise [StandardError] whatever the adapter raises: no network, a 4xx,
+      #   bad JSON, or Timeout::Error past the limit
+      def call(idea:)
+        output = Timeout.timeout(@timeout, Timeout::Error, "no questions within #{@timeout}s") do
+          adapter.call(node, { idea: idea.to_s })
+        end
+        self.class.render(output)
+      end
+
+      private
+
+      def adapter
+        @mutex.synchronize do
+          @adapter ||= begin
+            require "inquirex-llm"
+            Inquirex::LLM::OpenRouterAdapter.new(api_key: @api_key, model:)
+          end
+        end
+      end
+
+      def node
+        @node ||= begin
+          require "inquirex-llm"
+          Inquirex::LLM::Node.new(id: :interview,
+            verb: :extract,
+            prompt: PROMPT,
+            schema: Inquirex::LLM::Schema.new(questions: :array),
+            from_steps: %i[idea])
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/live/keys.rb

@@ -62,6 +62,14 @@ module OpenLanes
       # @return [String]
       def run(of = node) = "#{base}:#{of}:run"
 
+      # Pub/sub: `{json}`, one line of this node's {Engine::EventJournal},
+      # mirrored after it is fsync'd. The file is the record; a subscriber
+      # that misses a message reads the file.
+      #
+      # @param of [String]
+      # @return [String]
+      def journal(of = node) = "#{base}:#{of}:journal"
+
       # Stream: `{json}`, one `CopilotTurn`: the conversation with this
       # node's copilot (W17), the person's messages and its answers in the
       # order they were said. {Copilot} writes and reads it.
@@ -79,6 +87,23 @@ module OpenLanes
       # @return [String]
       def copilot_session(of = node) = "#{base}:#{of}:copilot-session"
 
+      # Stream: `{json}`, one mailbox message and the plan it belongs to,
+      # what `openlanes mail send` publishes after writing `state.json`
+      # (plan 003, B3). One stream per checkout; the plan rides in the entry,
+      # and each plan reads it through a group of its own ({Keys#mail_group}).
+      #
+      # @param of [String]
+      # @return [String]
+      def mail(of = node) = "#{base}:#{of}:mail"
+
+      # The consumer group one plan drains {#mail} through. Every group sees
+      # every entry, so a plan's harness thread acks what it read, its own
+      # or not, without taking anything from another plan's.
+      #
+      # @param plan [#to_s] e.g. "003.00"
+      # @return [String]
+      def mail_group(plan) = "mail:#{plan}"
+
       # Pub/sub channel: one chat's messages, joins, leaves and idle notices
       # (plan 006). Redis delivers a `PUBLISH` to every database's
       # subscribers, so the database is part of every chat channel's name: a
@@ -116,6 +141,33 @@ module OpenLanes
       # @return [String]
       def chat_base(db) = "#{base}:chat:#{db}"
 
+      # Pub/sub channel: "look again", one per project, published by
+      # whoever wrote something an open page shows ({News}). Every node's
+      # engine on the project publishes here, because every page shows every
+      # node's board. The database is in the name for the reason it is in
+      # {#chat_room}'s: a `PUBLISH` reaches every database's subscribers.
+      #
+      # @param db [Integer] the Redis database the nodes share
+      # @return [String]
+      def news(db:) = "#{base}:news:#{db}"
+
+      # Hash: plan ordinal to that plan's running app, its process statuses
+      # and a heartbeat ({Apps::Listing}). One per machine, not per
+      # checkout: the app runs in a plan's worktree and the control room in
+      # the main checkout, and both are this machine.
+      #
+      # @param machine [String] a node id, 24 hex digits of `user@host`
+      # @return [String]
+      def apps(machine = node.split(":").first) = "#{base}:apps:#{machine}"
+
+      # Stream: `{json}`, one request from the Preview tab's toolbar
+      # (restart, stop), read by `openlanes app start`. Not {#commands}: the
+      # engine never runs an app, so it would never read them.
+      #
+      # @param machine [String]
+      # @return [String]
+      def app_commands(machine = node.split(":").first) = "#{apps(machine)}:commands"
+
       # String: the node name holding a plan, `SET NX EX`.
       #
       # @param ordinal [#to_s] e.g. "004.00"
@@ -138,6 +190,10 @@ module OpenLanes
       # can scroll back through, not an archive.
       COPILOT_LENGTH = 500
 
+      # Seconds a message stays in {#mail}. `state.json` is the record; the
+      # stream only has to outlast a harness tick, and an hour is generous.
+      MAIL_TTL = 3600
+
       # Seconds a snapshot outlives its last refresh.
       SNAPSHOT_TTL = 30
 

data/lib/openlanes/live/mail.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module OpenLanes
+  module Live
+    # Mail between agents, over Redis as well as through `state.json`
+    # (plan 003, B3).
+    #
+    # `state.json` stays the record: `openlanes mail send` writes it first
+    # and publishes here only when Redis answers, so a run without Redis
+    # loses nothing. What the stream adds is delivery to the harness thread
+    # beside each agent, which drains it once a second (B4) instead of
+    # re-reading every plan's file.
+    #
+    # A stream with a consumer group per plan, not pub/sub: a message
+    # published while nobody drains waits for the next drain instead of
+    # vanishing. Every publish trims what is older than {Keys::MAIL_TTL}
+    # and renews the key's expiry, so the stream never outgrows an hour.
+    #
+    # Delivery is acked once the drain's block kept it, never before: an
+    # entry acked ahead of a failed write would be gone from the stream with
+    # only a log line left. An entry not kept stays pending and is offered
+    # again on the next drain. An ack says the bytes arrived, nothing more: a message is read when its recipient runs `openlanes mail ack`,
+    # and that lands in `state.json`, never here.
+    class Mail
+      # @param store [OpenLanes::Live::Store, OpenLanes::Live::MemoryStore]
+      # @param keys [OpenLanes::Live::Keys]
+      # @param now [Proc] wall time, which the trim's cutoff is taken from
+      def initialize(store:, keys:, now: -> { Time.now })
+        @store = store
+        @keys = keys
+        @now = now
+      end
+
+      # Publish one message that `state.json` already holds.
+      #
+      # @param plan [#to_s] the plan's number, e.g. "003.00"
+      # @param message [OpenLanes::Plans::Mailbox::Message, Hash]
+      # @return [void]
+      def publish(plan:, message:)
+        payload = JSON.generate("plan" => plan.to_s, "message" => wire(message))
+        EventBus.for(@store).transaction do |tx|
+          tx.append(@keys.mail, { json: payload })
+          tx.xtrim(@keys.mail, minid: cutoff)
+          tx.expire(@keys.mail, Keys::MAIL_TTL)
+        end
+      end
+
+      # Every message for +plan+ that this plan's group has not had kept
+      # yet: first the ones offered before and left pending, then the new.
+      # Entries for other plans, and entries that are not messages, are
+      # acked in this plan's group straight away, which leaves other plans'
+      # groups untouched.
+      #
+      # With a block, each message is yielded and acked only when the block
+      # returns truthy; one it returns false for, or raises on, stays pending
+      # for the next drain. Without one, each is acked as it is returned.
+      #
+      # @param plan [#to_s]
+      # @param consumer [String] who is draining, e.g. the agent's name
+      # @yieldparam message [Hash] as `state.json` holds it
+      # @yieldreturn [Boolean] whether it was kept
+      # @return [Array<Hash>] messages as `state.json` holds them, oldest
+      #   first; with a block, the ones left pending
+      def drain(plan:, consumer:)
+        group = @keys.mail_group(plan)
+        @store.expire(@keys.mail, Keys::MAIL_TTL) if @store.xgroup_create(@keys.mail, group)
+        entries = @store.xreadgroup(@keys.mail, group, consumer, id: "0") + @store.xreadgroup(@keys.mail, group, consumer)
+        entries.filter_map do |entry|
+          message = message_in(entry, plan.to_s)
+          kept = message.nil? || !block_given? || yield(message)
+          @store.xack(@keys.mail, group, entry.id) if kept
+          message if message && (kept ? !block_given? : true)
+        end
+      end
+
+      # Which plans have mail in the stream after +cursor+, so a drain can
+      # reach a plan with nobody running on it: a worktree's `mail send` has
+      # no other way into the main checkout's `state.json`, and the stream
+      # forgets it after {Keys::MAIL_TTL}.
+      #
+      # @param cursor [String] the last stream id already looked at, "0" for
+      #   all of it
+      # @return [Array(Array<String>, String)] the plans, and the new cursor
+      def plans_since(cursor)
+        plans = []
+        loop do
+          entries = @store.xread(@keys.mail, id: cursor)
+          break if entries.empty?
+
+          cursor = entries.last.id
+          plans.concat(entries.filter_map { plan_in(it) })
+        end
+        [plans.uniq, cursor]
+      end
+
+      private
+
+      # The oldest id a publish keeps: {Keys::MAIL_TTL} seconds ago.
+      #
+      # @return [String]
+      def cutoff = "#{((@now.call.to_f - Keys::MAIL_TTL) * 1000).to_i}-0"
+
+      # @param message [OpenLanes::Plans::Mailbox::Message, Hash]
+      # @return [Hash] string keys, `at` in ISO 8601 as `state.json` has it
+      def wire(message)
+        hash = message.to_h.transform_keys(&:to_s)
+        hash.merge("at" => iso8601(hash["at"])).compact
+      end
+
+      # @param at [String, Time, nil]
+      # @return [String, nil]
+      def iso8601(at)
+        return at.iso8601 if at.respond_to?(:iso8601)
+
+        Time.parse(at.to_s).iso8601
+      rescue ArgumentError
+        at&.to_s
+      end
+
+      # @param entry [OpenLanes::Live::Store::Entry]
+      # @return [String, nil] the plan the entry is for
+      def plan_in(entry)
+        data = JSON.parse(entry.fields["json"].to_s)
+        data["plan"] if data.is_a?(Hash) && data["plan"].is_a?(String)
+      rescue JSON::ParserError
+        nil
+      end
+
+      # @param entry [OpenLanes::Live::Store::Entry]
+      # @param plan [String]
+      # @return [Hash, nil] the message, when the entry is one and for +plan+
+      def message_in(entry, plan)
+        data = JSON.parse(entry.fields["json"].to_s)
+        data["message"] if data.is_a?(Hash) && data["plan"] == plan && data["message"].is_a?(Hash)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end