openlanes 3.0.0 → 3.1.0

data/lib/openlanes/live/choice_converter.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Live
+    # Rewrites a question an agent wrote as prose into D3's shape (D9): a
+    # short context paragraph and lettered options, exactly one recommended.
+    # The page draws a button per option and a text box under them, so a
+    # person can answer with one click instead of composing a reply to a
+    # paragraph.
+    #
+    # One call to a small model on OpenRouter, through `inquirex-llm`'s
+    # `OpenRouterAdapter`, which asks for a JSON object and checks that both
+    # fields came back. What the model returns is not trusted to be D3: it is
+    # cleaned, written out with {Plans::Choices.write}, and read back with
+    # {Plans::Choices.parse}, and anything that does not survive the trip is
+    # {Invalid}.
+    #
+    # It neither reads nor writes `blocked.md`; {Engine::Conversions} does,
+    # so this stays a function of text, and a seam: the suite sets
+    # {Live.choice_converter} to nil, and examples about it hand it an
+    # adapter double, so nothing in the tests reaches OpenRouter.
+    class ChoiceConverter
+      # Small and quick, and listed by OpenRouter and by inquirex-llm's own
+      # catalogue (`Models::OPENROUTER_ALIASES[:claude_haiku]`).
+      # `questions.model` in `.openlanes.yml` replaces it.
+      DEFAULT_MODEL = "anthropic/claude-haiku-5.5"
+
+      # What the model reads with the question.
+      PROMPT = <<~PROMPT
+        A software agent stopped and wrote the question below for a person. The person answers it in a
+        web page that shows one button per option and a free-text box under them. Rewrite the question as
+        multiple choice:
+
+        - `context`: one short paragraph with what the person needs to know to choose. Keep every fact,
+          number and name that matters; drop repetition. Do not repeat the heading.
+        - `options`: an array of 2 to 5 objects `{"label": String, "recommended": Boolean}`, each a distinct
+          answer the question already implies, written as one short line in the agent's own terms.
+          Exactly one has `"recommended": true`: the one the question itself prefers, or, if it prefers
+          none, the safest one.
+
+        Never change what is being asked, never add facts the question does not state, never answer it,
+        and never add an option for "something else" or "type something instead": the page has a text box.
+      PROMPT
+
+      # What the model answered could not be made into a D3 question.
+      class Invalid < Error; end
+
+      # @!attribute [r] body
+      #   @return [String] the question's new body, D3-shaped Markdown
+      # @!attribute [r] count
+      #   @return [Integer] how many options it offers
+      # @!attribute [r] model
+      #   @return [String] the model that wrote it
+      Result = Data.define(:body, :count, :model)
+
+      # A converter when OPENROUTER_API_KEY is set, nil otherwise.
+      #
+      # @param env [#[]]
+      # @param config [OpenLanes::Config]
+      # @return [OpenLanes::Live::ChoiceConverter, 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 || DEFAULT_MODEL)
+      end
+
+      # The model's answer, cleaned and written in D3's shape.
+      #
+      # @param output [Hash] `context` and `options`, as the adapter parsed them
+      # @return [String] the new body
+      # @raise [Invalid] when it cannot be one
+      def self.render(output)
+        output = output.to_h.transform_keys(&:to_sym)
+        context = output[:context].to_s.strip
+        raise Invalid, "no context" if context.empty?
+        # A heading inside the body would end the question there, and a
+        # `Bn` or `An` line would start another one.
+        if [Plans::BlockedFile::HEADING, Plans::OPEN_BLOCK, Plans::ANSWER_BLOCK].any? { context.match?(it) }
+          raise Invalid, "the context holds a heading"
+        end
+
+        options = Array(output[:options]).map { option(it) }
+                                         .reject { |label, _| label.match?(Plans::Choices::SOMETHING_ELSE) }
+        raise Invalid, "#{options.size} option#{"s" unless options.size == 1}, not 2 or more" if options.size < 2
+
+        recommended = options.each_index.select { options[it].last }
+        raise Invalid, "#{recommended.size} options recommended, not one" unless recommended.size == 1
+
+        body = Plans::Choices.write(context:, labels: options.map(&:first), recommended: recommended.first)
+        back = Plans::Choices.parse(body)
+        raise Invalid, "the rewrite does not read back as #{options.size} choices" unless back&.options&.size == options.size
+
+        body
+      end
+
+      # One option as a label on one line and whether it is recommended; a
+      # recommendation the model wrote into the label is taken out of it, since
+      # the flag already says so.
+      #
+      # @param raw [Hash, Object]
+      # @return [Array(String, Boolean)]
+      # @raise [Invalid]
+      def self.option(raw)
+        raise Invalid, "an option is not an object" unless raw.is_a?(Hash)
+
+        raw = raw.transform_keys(&:to_sym)
+        label = raw[:label].to_s.gsub(/\s+/, " ").sub(Plans::Choices::RECOMMENDED, " ").strip
+        raise Invalid, "an option has no label" if label.empty?
+
+        [label, [true, "true"].include?(raw[:recommended])]
+      end
+      private_class_method :option
+
+      # @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 `context` and `options`, as `Inquirex::LLM::OpenRouterAdapter`
+      #   does; built on first use when nil, so a process that never converts
+      #   never loads inquirex
+      def initialize(api_key: nil, model: DEFAULT_MODEL, adapter: nil)
+        @api_key = api_key
+        @model = model
+        @adapter = adapter
+        @mutex = Mutex.new
+      end
+
+      # @return [String]
+      attr_reader :model
+
+      # Blocks for as long as the request takes (the adapter gives up after
+      # 30 seconds without an answer), so the engine calls it on a thread.
+      #
+      # @param heading [String] the question's heading, for context; it is kept
+      # @param body [String] the question as the agent wrote it
+      # @return [OpenLanes::Live::ChoiceConverter::Result]
+      # @raise [Invalid] when the answer is not a D3 question
+      # @raise [StandardError] whatever the adapter raises: no network, a 4xx, bad JSON
+      def call(heading:, body:)
+        output = adapter.call(node, { heading: heading.to_s, question: body.to_s })
+        written = self.class.render(output)
+        Result.new(body: written, count: Plans::Choices.parse(written).options.size, model:)
+      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: :choices,
+            verb: :extract,
+            prompt: PROMPT,
+            schema: Inquirex::LLM::Schema.new(context: :string, options: :array),
+            from_steps: %i[heading question])
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/live/choice_judge.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module OpenLanes
+  module Live
+    # A second opinion on {Plans::Choices}: does this message ask its reader
+    # to choose one of the options it lists? Asked of Jev, TypeSafe's System
+    # One model, through `inquirex-llm`'s `JevAdapter`, as one boolean.
+    #
+    # The parser cannot tell "Done so far: 1. … 2. …" from a numbered choice;
+    # Jev can. Its answer only ever narrows: `false` takes the buttons away and
+    # leaves the text box, `true` keeps them, and `nil` (no answer, an error, a
+    # timeout, an answer too unsure to count) leaves the parser's verdict as it
+    # was. A missing key therefore costs nothing but the second opinion.
+    #
+    # The snapshot is rebuilt every time the board moves, so every answer is
+    # kept, in this process, by the SHA256 of the text: one request per
+    # distinct question, ever. A request still in flight when {#call} gives up
+    # waiting goes on in its thread, and the next snapshot finds its answer.
+    #
+    # A seam, like {Vcs::GitHub} and {Linear::API}: the suite sets
+    # {Live.choice_judge} to nil, and examples about the judge hand it an
+    # adapter double, so nothing in the tests reaches TypeSafe.
+    class ChoiceJudge
+      # What Jev reads with the message. Its boolean question is whether
+      # `asks_to_choose` is true according to the message.
+      PROMPT = <<~PROMPT
+        The message below was written by a software agent to a person, who answers it in a web page.
+        `asks_to_choose` is true when the message asks the person to pick one of the options it lists
+        (lettered or numbered alternatives, or a plain yes/no question), and false when the list is
+        something else: steps already done, findings, a plan, or a question that wants a written answer.
+      PROMPT
+
+      # How long a snapshot waits for an answer it does not have yet.
+      TIMEOUT = 3.0
+
+      # Below this Jev is guessing, and the parser's verdict stands.
+      MIN_CONFIDENCE = 0.6
+
+      # The schema field Jev answers.
+      FIELD = :asks_to_choose
+
+      # A judge when TYPESAFE_API_KEY is set, nil otherwise.
+      #
+      # @param env [#[]]
+      # @return [OpenLanes::Live::ChoiceJudge, nil]
+      def self.from_env(env = ENV)
+        key = env["TYPESAFE_API_KEY"].to_s.strip
+        key.empty? ? nil : new(api_key: key)
+      end
+
+      # @param api_key [String, nil] TypeSafe's; only read to build the default adapter
+      # @param adapter [#call, nil] answers `call(node, answers)` with a Hash
+      #   holding {FIELD}, as `Inquirex::LLM::JevAdapter` does; built on first
+      #   use when nil, so a process that never judges never loads inquirex
+      # @param timeout [Float] seconds {#call} waits for an answer it lacks
+      def initialize(api_key: nil, adapter: nil, timeout: TIMEOUT)
+        @api_key = api_key
+        @adapter = adapter
+        @timeout = timeout
+        @answers = {}
+        @mutex = Mutex.new
+      end
+
+      # @param text [String] the question, as the person would read it
+      # @return [Boolean, nil] whether it asks to choose; nil when Jev has not
+      #   said, or could not
+      def call(text)
+        key = Digest::SHA256.hexdigest(text.to_s)
+        asking = @mutex.synchronize { @answers[key] ||= ask(text.to_s) }
+        asking.join(@timeout) ? asking.value : nil
+      end
+
+      private
+
+      # @return [Thread] whose value is true, false or nil
+      def ask(text)
+        Thread.new do
+          Thread.current.report_on_exception = false
+          adapter.call(node, { message: text })[FIELD]
+        rescue StandardError => e
+          UI.log("choice judge: no verdict (#{e.class})")
+          nil
+        end
+      end
+
+      def adapter
+        @mutex.synchronize do
+          @adapter ||= begin
+            require "inquirex-llm"
+            Inquirex::LLM::JevAdapter.new(api_key: @api_key, min_confidence: MIN_CONFIDENCE)
+          end
+        end
+      end
+
+      def node
+        @node ||= begin
+          require "inquirex-llm"
+          Inquirex::LLM::Node.new(id: :choice,
+            verb: :extract,
+            prompt: PROMPT,
+            schema: Inquirex::LLM::Schema.new(FIELD => :boolean),
+            from_steps: [:message])
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/live/claims.rb

@@ -39,9 +39,17 @@ module OpenLanes
       # Extend every claim this node holds. One that lapsed and was taken by
       # another node in the meantime is dropped from {#held}, not fought for.
       #
+      # One that is simply gone is taken back: a Redis that restarted empty
+      # (W32) has lost every claim, and reading that as "another machine
+      # took it" stopped this machine's own agents for plans nobody else
+      # wanted. `SET NX` still loses to a node that got there first.
+      #
       # @return [Array<String>] the ordinals lost
       def renew
-        lost = held.reject { |ordinal| @store.compare_and_expire(@keys.claim(ordinal), @keys.node, @ttl) }
+        lost = held.reject do |ordinal|
+          key = @keys.claim(ordinal)
+          @store.compare_and_expire(key, @keys.node, @ttl) || @store.set(key, @keys.node, ex: @ttl, nx: true)
+        end
         @mutex.synchronize { @held -= lost }
         lost
       end

data/lib/openlanes/live/command.rb

@@ -42,25 +42,28 @@ module OpenLanes
 
       # Every kind the page may send.
       KINDS = %w[answer hold_blocked release_hold resume discard message hold wrap_up compact stop stop_all
-                 set_model switch_model add_plan create_plans].freeze
+                 set_model switch_model add_plan create_plans respond pause_discuss resume_anyway
+                 stop_plan restart_plan set_concurrency].freeze
 
       # Kinds that act on one plan, and so must name it.
       PLAN_KINDS = %w[answer hold_blocked release_hold resume discard message hold wrap_up compact stop
-                      set_model switch_model].freeze
+                      set_model switch_model respond pause_discuss resume_anyway stop_plan restart_plan].freeze
 
       # Kinds that act on one agent of that plan, and so must name it too.
       AGENT_KINDS = %w[hold wrap_up compact stop set_model switch_model].freeze
 
       # Payload fields each kind cannot do without.
       PAYLOAD = {
-        "answer"       => %w[question text],
-        "hold_blocked" => %w[question],
-        "release_hold" => %w[question],
-        "message"      => %w[text],
-        "set_model"    => %w[model],
-        "switch_model" => %w[model],
-        "add_plan"     => %w[ordinal],
-        "create_plans" => %w[idea]
+        "answer"          => %w[question text],
+        "hold_blocked"    => %w[question],
+        "release_hold"    => %w[question],
+        "message"         => %w[text],
+        "set_model"       => %w[model],
+        "switch_model"    => %w[model],
+        "add_plan"        => %w[ordinal],
+        "create_plans"    => %w[idea],
+        "respond"         => %w[text],
+        "set_concurrency" => %w[limit]
       }.freeze
 
       # Ids are ULIDs; this only keeps an absurd one out of a hash field.