claude-inbox 0.2.0 → 0.3.0

data/lib/claude_inbox/remote/start.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+require_relative "../agents_client"
+require_relative "../images"
+require_relative "../job_state"
+require_relative "../session"
+require_relative "../session_request"
+require_relative "../settings"
+require_relative "../text"
+require_relative "../trust"
+require_relative "http"
+
+module ClaudeInbox
+  module Remote
+    # What a paired phone may ask for: the choices, and a session started
+    # the way the `n` form starts one, within the permission cap. Listener
+    # hands it a request only once the token has checked out.
+    class Start
+      # Path => [verb, the method that answers it].
+      ROUTES = {"/api/options" => ["GET", :options], "/api/sessions" => ["POST", :post_session]}.freeze
+      VERBS = ROUTES.transform_values(&:first).freeze
+      MAX_BODY = 16 * 1024 * 1024
+      MAX_IMAGES = 8
+      BODY_TIMEOUT = 120
+      KEYS_KEPT = 16
+
+      def initialize(client:, store:, queue:, allowed_modes:, fixture: false, images_dir: Images::DEFAULT_DIR,
+        jobs_dir: JobState::DEFAULT_DIR, trust: Trust.method(:projects), settings: Settings.method(:defaults), bridge_wait: 3)
+        @client = client
+        @store = store
+        @queue = queue
+        @allowed_modes = allowed_modes
+        @fixture = fixture
+        @images_dir = images_dir
+        @jobs_dir = jobs_dir
+        @trust = trust
+        @settings = settings
+        @bridge_wait = bridge_wait
+        @mutex = Mutex.new
+        @spawn_lock = Mutex.new
+        @keys = {}
+      end
+
+      # => [status, headers, body, note], `note` being what `N` lists, if
+      # anything; or raises Http::Error.
+      def call(request, io, via) = send(ROUTES.fetch(request.path)[1], request, io, via)
+
+      private
+
+      def options(_request, _io, _via) = json(200, choices)
+
+      def json(status, body) = [status, Http::JSON_TYPE, JSON.generate(@fixture ? body.merge(fixture: true) : body)]
+
+      def choices
+        paths = dir_paths
+        {
+          models: AgentsClient::MODELS,
+          efforts: AgentsClient::EFFORTS,
+          permission_modes: AgentsClient::PERMISSION_MODES & @allowed_modes,
+          dirs: paths.map { |path| {path: path, label: SessionRequest.label(path, paths), defaults: @settings.call(path).to_h} }
+        }
+      end
+
+      # Where sessions ran lately, newest first, then every directory whose
+      # trust dialog was accepted: the likely choices first. Only an order;
+      # the CLI still decides where a session may start.
+      def dir_paths
+        recent = @store.sessions.sort_by { |s| -s.started_at.to_i }.filter_map { |s| s.cwd && SessionRequest.strip_worktree(s.cwd) }
+        (recent + @trust.call).uniq.select { |dir| File.directory?(dir) }
+      end
+
+      # Checked cheapest first, and nothing is written to disk until every
+      # check has passed. A retry with the same Idempotency-Key gets the
+      # first answer instead of a second session; the key sent with a
+      # different request is refused, since that answer isn't this one's.
+      def post_session(request, io, via)
+        params = read_json(io, request)
+        key = request.headers["idempotency-key"]
+        key = nil if key.to_s.empty?
+        digest = OpenSSL::Digest.digest("SHA256", JSON.generate(params)) if key
+        images = take_images(params)
+        earlier = key && claim(key, digest)
+        return json(200, earlier) if earlier
+        started = nil
+        begin
+          started = launch(params, images, via)
+          [*json(201, started), "started #{started[:id]}"]
+        ensure
+          settle(key, digest, started) if key
+        end
+      rescue AgentsClient::Error => e
+        reason = Text.printable(e.message.lines.first.to_s.strip)
+        @queue << [:notice, "remote start failed: #{reason}"]
+        raise Http::Error.new(500, e.message, source: "claude", note: reason)
+      end
+
+      def read_json(io, request)
+        type = request.headers["content-type"].to_s.split(";").first.to_s.strip
+        raise Http::Error.new(415, "send the request as application/json") unless type.casecmp?("application/json")
+        body = request.read_body(io, max: MAX_BODY, deadline: Http.monotonic + BODY_TIMEOUT).force_encoding(Encoding::UTF_8)
+        raise Http::Error.new(400, "the body isn't UTF-8") unless body.valid_encoding?
+        params = JSON.parse(body)
+        raise Http::Error.new(400, "the body must be a JSON object") unless params.is_a?(Hash)
+        params
+      rescue JSON::ParserError
+        raise Http::Error.new(400, "the body isn't JSON")
+      end
+
+      # Decoded and sniffed now, saved only once the request has passed.
+      def take_images(params)
+        images = params.delete("images") || []
+        raise Http::Error.new(422, "images is a list of {\"data\": base64}", field: "images") unless images.is_a?(Array)
+        raise Http::Error.new(413, "at most #{MAX_IMAGES} images", field: "images") if images.size > MAX_IMAGES
+        images.each_with_index.map do |image, i|
+          bytes = decode(image)
+          next bytes if bytes && Images.extension(bytes)
+          raise Http::Error.new(415, "image #{i + 1} isn't a PNG, JPEG, GIF or WebP image", field: "images", index: i)
+        end
+      end
+
+      def decode(image)
+        data = image["data"] if image.is_a?(Hash)
+        data.gsub(/\s+/, "").unpack1("m0") if data.is_a?(String)
+      rescue ArgumentError
+        nil
+      end
+
+      # The body an earlier request with this key got, or nil once the key
+      # is this request's; one still starting is a 409.
+      def claim(key, digest)
+        @mutex.synchronize do
+          sent, earlier = @keys[key]
+          if sent
+            raise Http::Error.new(422, "this Idempotency-Key was sent with a different request") unless sent == digest
+            raise Http::Error.new(409, "already starting") if earlier == :spawning
+            return earlier
+          end
+          @keys.shift while @keys.size >= KEYS_KEPT
+          @keys[key] = [digest, :spawning]
+          nil
+        end
+      end
+
+      # A failed start frees its key, so a retry goes through rather than
+      # getting 409 for ever.
+      def settle(key, digest, started)
+        @mutex.synchronize do
+          if started then @keys[key] = [digest, started]
+          else @keys.delete(key)
+          end
+        end
+      end
+
+      def launch(params, images, via)
+        values = SessionRequest.from_params(params, dirs: dir_paths)
+        field, message = SessionRequest.problem(values)
+        raise Http::Error.new(422, message, field: field) if field
+        defaults = @settings.call(values[:cwd])
+        values = SessionRequest.resolve(values, defaults)
+        values[:permission_mode] = capped_mode(values[:permission_mode] || defaults.permission_mode || builtin_mode)
+        paths = images.each_with_index.map { |bytes, i| Images.save(bytes, dir: @images_dir, index: i + 1) }
+        values[:prompt] = SessionRequest.attach(values[:prompt], paths)
+        @queue << [:notice, "remote: starting session…"]
+        id = Http.utf8(@spawn_lock.synchronize { @client.spawn(**values) })
+        url = remote_url(id, wait: values[:remote] ? @bridge_wait : 0)
+        @queue << [:remote_started, id, via]
+        {id: id, name: values[:name], cwd: values[:cwd], url: url}
+      rescue SessionRequest::Invalid => e
+        raise Http::Error.new(422, e.message, field: e.field)
+      end
+
+      # Unset, the mode is what the settings files say, so a project defaulting
+      # to bypassPermissions can't pass as "default". The spawn always names the
+      # mode that passed: the flag beats every settings file short of managed
+      # policy, so one the inbox doesn't read can't widen it.
+      def capped_mode(mode)
+        return mode if @allowed_modes.include?(mode)
+        raise Http::Error.new(403, "permission mode #{mode} isn't allowed from another device", field: "permission_mode")
+      end
+
+      # Unset in settings, the CLI's own default is auto or manual, never
+      # wider. Passed as "default" the CLI takes manual, so auto is named
+      # outright wherever it is allowed.
+      def builtin_mode = @allowed_modes.include?("auto") ? "auto" : "default"
+
+      # The session registers its bridge a moment after `claude --bg`
+      # returns; without it in time the reply has no URL, only the id.
+      # Without --remote-control it seldom registers one (docs/cli-quirks.md),
+      # so that start looks once rather than waits.
+      def remote_url(id, wait:)
+        deadline = Http.monotonic + wait
+        loop do
+          url = Session.new(id: id, job_state: JobState.read(id, jobs_dir: @jobs_dir)).remote_url
+          return url if url || Http.monotonic >= deadline
+          sleep 0.2
+        end
+      end
+    end
+  end
+end

data/lib/claude_inbox/remote.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module ClaudeInbox
+  # Starting sessions from another device. App reaches it only through
+  # Remote::Listener.
+  module Remote
+  end
+end
+
+require_relative "remote/listener"

data/lib/claude_inbox/renderer.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "pastel"
-require "tty-cursor"
 require_relative "text"
 require_relative "palette"
 require_relative "theme"
@@ -20,11 +19,17 @@ module ClaudeInbox
 
     Frame = Struct.new(:lines, :items, :top, :list_width)
 
-    # What App hands Renderer for one frame. `peek` is a Peek::View.
+    CHROME_ROWS = 2 # header + footer
+    MIN_LIST_WIDTH = 44 # with the peek open, the list keeps at least this many columns
+
+    def self.body_height(height) = height - CHROME_ROWS
+
+    # What App hands Renderer for one frame. `peek` is a Peek::View and
+    # `listening` a Remote::Listener::Snapshot.
     View = Data.define(:width, :height, :now, :selected, :top, :expanded, :peek, :modal, :screen,
-      :status, :usage, :filter, :filter_editing, :tick, :loading) do
+      :status, :usage, :filter, :filter_editing, :tick, :loading, :listening) do
       def initialize(width:, height:, now:, selected: nil, top: 0, expanded: {}, peek: nil, modal: nil, screen: nil,
-        status: nil, usage: nil, filter: nil, filter_editing: false, tick: 0, loading: nil) = super
+        status: nil, usage: nil, filter: nil, filter_editing: false, tick: 0, loading: nil, listening: nil) = super
     end
 
     SECTION_TITLES = {
@@ -37,6 +42,10 @@ module ClaudeInbox
 
     SECTION_HUES = {pinned: :cyan, needs_you: :red, active: :yellow, snoozed: :purple}.freeze
 
+    # GitHub's colors. A draft has no hue, so it dims; a state missing from
+    # the table isn't named on the badge at all.
+    PR_HUES = {"OPEN" => :green, "DRAFT" => nil, "MERGED" => :purple, "CLOSED" => :red}.freeze
+
     SPINNER = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze
 
     # The first poll usually lands inside a second. Past LOADING_QUIET the
@@ -61,11 +70,10 @@ module ClaudeInbox
       ["za", "fold"], ["/", "filter"], ["q", "quit"]
     ].freeze
 
-    def initialize(color: true, min_left: 44, home: Dir.home)
+    def initialize(color: true, home: Dir.home)
       @p = Pastel.new(enabled: color)
       @theme = Theme.new(enabled: color)
       @palette = Palette.new(enabled: color)
-      @min_left = min_left
       @home = home
     end
 
@@ -75,7 +83,7 @@ module ClaudeInbox
       return full_screen(sections, view) if view.screen
       width, height, now, selected = view.width, view.height, view.now, view.selected
       list_w = width_for_list(width, view.peek)
-      view_h = height - 2 # header + footer
+      view_h = Renderer.body_height(height)
       body, items =
         if view.loading
           [loading_state(list_w, view_h, view.loading, view.tick), []]
@@ -106,7 +114,7 @@ module ClaudeInbox
 
     def width_for_list(width, peek)
       return width unless peek
-      [(width * 0.4).floor, @min_left].max.clamp(0, width)
+      [(width * 0.4).floor, MIN_LIST_WIDTH].max.clamp(0, width)
     end
 
     def clamp_top(top, size, view_h, items, selected)
@@ -118,33 +126,43 @@ module ClaudeInbox
 
     def full_screen(sections, view)
       width = view.width
-      view_h = view.height - 2
+      view_h = Renderer.body_height(view.height)
       body = view.screen[:lines].first(view_h)
       body += [""] * (view_h - body.size)
       lines = [header(sections, width, view)] + body.map { |l| Text.pad(l, width) } + [Text.pad(" " + view.screen[:footer], width)]
-      Frame.new(lines, [nil] * (view_h + 2), view.top, width)
+      Frame.new(lines, [nil] * view.height, view.top, width)
     end
 
     # ----- chrome -------------------------------------------------------------
 
     def header(sections, width, view)
       brand = " " + @theme.cyan_bold("▌ claude-inbox")
-      right = [view.status && @p.dim(view.status), view.usage && usage_meters(view.usage, view.now)].compact.join(@p.dim("  ·  "))
-      right += " " unless right.empty?
+      right = header_right(view, width - Text.width(brand) - 3)
       room = width - Text.width(brand) - Text.width(right) - 3
-      chips = view.loading ? "" : header_chips(sections, compact: false)
-      chips = header_chips(sections, compact: true) if Text.width(chips) > room
+      chips = view.loading ? "" : header_chips(sections, compact: false, listening: view.listening)
+      chips = header_chips(sections, compact: true, listening: view.listening) if Text.width(chips) > room
       chips = "" if Text.width(chips) > room
       Text.pad(brand + "   " + chips, width - Text.width(right)) + right
     end
 
+    # The notice outranks the usage meters: they shed their reset times, then
+    # go, before the notice itself is cut to fit.
+    def header_right(view, room)
+      meters = view.usage ? [usage_meters(view.usage, view.now), usage_meters(view.usage, view.now, resets: false)] : []
+      (meters + [nil]).each do |m|
+        right = [view.status && @p.dim(view.status), m].compact.join(@p.dim("  ·  "))
+        return right.empty? ? right : right + " " if Text.width(right) < room
+      end
+      (view.status && room > 1) ? @p.dim(Text.truncate(view.status, room - 1)) + " " : ""
+    end
+
     # "session ██░░░░░░░░ 24% · 3h left" per window, drawn and colored the way
     # the context bar in the user's status line is, so the two read alike.
-    def usage_meters(windows, now)
+    def usage_meters(windows, now, resets: true)
       windows.map do |w|
         filled = w.percent / 10
         bar = "█" * filled + "░" * (10 - filled)
-        left = w.resets_at && w.resets_at.to_i - now.to_i
+        left = w.resets_at.to_i - now.to_i if resets && w.resets_at
         figure = left&.positive? ? "#{w.percent}% · #{Text.age(left)} left" : "#{w.percent}%"
         "#{@p.dim(w.label)} #{@theme.public_send(usage_hue(w.percent), bar)} #{@p.dim(figure)}"
       end.join("  ")
@@ -157,7 +175,7 @@ module ClaudeInbox
       end
     end
 
-    def header_chips(sections, compact:)
+    def header_chips(sections, compact:, listening: nil)
       pinned = sections.pinned.size
       needing = sections.needs_you.size
       working = sections.active.count { |r| r.session.effective_state == "working" && !r.session.waiting_on_work? }
@@ -177,7 +195,16 @@ module ClaudeInbox
         header_chip(settled, "◦", "settled", compact) { |s| @p.dim(s) }
       ].compact
       chips << @p.dim("nothing running") if sections.all.empty?
-      chips.join(compact ? "  " : @p.dim("  ·  "))
+      [*chips, listening_chip(listening)].compact.join(compact ? "  " : @p.dim("  ·  "))
+    end
+
+    # Red when the listener was asked for and isn't up. Nothing when it
+    # wasn't asked for.
+    def listening_chip(listening)
+      case listening&.state
+      when :listening then @theme.blue("◉ #{"lan" if listening.lan}:#{listening.port}")
+      when :in_use, :held, :failed then @theme.red("◉ !")
+      end
     end
 
     def header_chip(count, glyph, words, compact)
@@ -189,11 +216,16 @@ module ClaudeInbox
       text =
         if view.filter_editing then " " + @theme.cyan_bold("/") + line(view.filter, width - 2)
         elsif view.filter then " " + @theme.cyan_bold("/") + view.filter.to_s + @p.dim("  esc clears")
-        else " " + KEYS.map { |k, d| @theme.cyan_bold(k) + " " + @p.dim(d) }.join("  ")
+        else " " + footer_keys(view).map { |k, d| @theme.cyan_bold(k) + " " + @p.dim(d) }.join("  ")
         end
       Text.pad(text, width)
     end
 
+    def footer_keys(view)
+      return KEYS unless view.listening&.lan
+      KEYS.flat_map { |key| (key[0] == "n") ? [key, ["N", "pair"]] : [key] }
+    end
+
     def line(buffer, width) = buffer.row(width, cursor: caret)
 
     def section_title(name, count, width)
@@ -203,8 +235,9 @@ module ClaudeInbox
       Text.pad(" " + section_color(name, "▎") + section_color(name, @p.bold(title)) + @p.dim("─" * fill) + @p.dim(count_s), width)
     end
 
-    def section_color(name, s)
-      hue = SECTION_HUES[name]
+    def section_color(name, s) = tint(SECTION_HUES[name], s)
+
+    def tint(hue, s)
       hue ? @theme.public_send(hue, s) : @p.dim(s)
     end
 
@@ -366,19 +399,13 @@ module ClaudeInbox
       pr ? base + @p.dim(" · ") + pr : base
     end
 
-    # "#885 open" in GitHub's colors: green open, dim draft, purple merged,
-    # red closed. Only the first PR is shown; the peek subtitle lists them all.
+    # "#885 open". Only the first PR is shown; the peek subtitle lists them all.
     def pr_badge(s, section)
       pr = s.pr
       return nil unless pr
       return @p.dim("#{pr.short} #{pr.state&.downcase}".strip) if section == :settled
-      case pr.state
-      when "OPEN" then @theme.green("#{pr.short} open")
-      when "DRAFT" then @p.dim("#{pr.short} draft")
-      when "MERGED" then @theme.purple("#{pr.short} merged")
-      when "CLOSED" then @theme.red("#{pr.short} closed")
-      else @p.dim(pr.short)
-      end
+      return @p.dim(pr.short) unless PR_HUES.key?(pr.state)
+      tint(PR_HUES[pr.state], "#{pr.short} #{pr.state.downcase}")
     end
 
     def state_badge(s)
@@ -439,31 +466,4 @@ module ClaudeInbox
       out
     end
   end
-
-  # Diffs successive frames and writes only changed rows. No erase-to-end-of-
-  # line after a row: in the terminal's last column the cursor stays put
-  # (pending wrap), so EL would eat the glyph just drawn.
-  class Painter
-    def initialize(out, cursor: TTY::Cursor)
-      @out = out
-      @cursor = cursor
-      @prev = []
-    end
-
-    def paint(lines)
-      buf = +""
-      lines.each_with_index do |line, i|
-        next if @prev[i] == line
-        buf << @cursor.move_to(0, i) << line
-      end
-      if @prev.size > lines.size
-        (lines.size...@prev.size).each { |i| buf << @cursor.move_to(0, i) << @cursor.clear_line }
-      end
-      @out.print buf unless buf.empty?
-      @out.flush
-      @prev = lines
-    end
-
-    def invalidate = @prev = []
-  end
 end

data/lib/claude_inbox/session.rb

@@ -14,10 +14,8 @@ module ClaudeInbox
   ) do
     # Every member is optional so the parser and the specs name only what they
     # have; prs is [] rather than nil so nobody asks whether PullRequests has run.
-    def initialize(id: nil, cwd: nil, kind: nil, started_at: nil, session_id: nil, name: nil,
-      state: nil, pid: nil, status: nil, waiting_for: nil, origin: nil, prs: nil, job_state: nil, bridge_id: nil)
-      super(id: id, cwd: cwd, kind: kind, started_at: started_at, session_id: session_id, name: name,
-            state: state, pid: pid, status: status, waiting_for: waiting_for, origin: origin, prs: prs || [], job_state: job_state, bridge_id: bridge_id)
+    def initialize(prs: nil, **given)
+      super(**self.class.members.to_h { |m| [m, nil] }, **given, prs: prs || [])
     end
 
     def self.from_hash(h)
@@ -59,9 +57,9 @@ module ClaudeInbox
 
     def terminal? = interactive? && !remote? && !unattended?
 
-    # Where claude.ai/code shows this session. Every background session
-    # registers a bridge and records it in the job file; a worker a `claude
-    # remote-control` server spawned carries it on its command line.
+    # Where claude.ai/code shows this session. A background session with
+    # Remote Control on records its bridge in the job file; a worker a
+    # `claude remote-control` server spawned carries it on its command line.
     def remote_url
       bridge = bridge_id || job_state&.bridge_id
       bridge && "https://claude.ai/code/session_#{bridge.delete_prefix("cse_")}"
@@ -84,20 +82,8 @@ module ClaudeInbox
     def intent = job_state&.intent
 
     # The session's own one-line account of where it is, the same line
-    # `claude agents` prints under a row: what it needs while blocked, what
-    # it produced once done, otherwise its status line. Nil without a job
-    # file, or before the session has said anything.
-    def summary
-      return nil unless job_state
-      line =
-        case effective_state
-        when "blocked" then job_state.needs || job_state.detail
-        when "done" then job_state.result || job_state.detail
-        else job_state.detail
-        end
-      line = line.to_s.gsub(/\s+/, " ").strip
-      line.empty? ? nil : line
-    end
+    # `claude agents` prints under a row. Nil without a job file.
+    def summary = job_state&.summary(effective_state)
 
     def needs_you? = %w[blocked failed].include?(effective_state)
 

data/lib/claude_inbox/session_request.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require_relative "agents_client"
+
+module ClaudeInbox
+  # The rules a new session's settings follow, whichever way it is asked
+  # for: the `n` form, or a request that arrives as a hash of JSON values.
+  module SessionRequest
+    class Invalid < StandardError
+      attr_reader :field
+
+      def initialize(field, message)
+        @field = field
+        super(message)
+      end
+    end
+
+    KEYS = %w[prompt name cwd model effort permission_mode worktree remote].freeze
+    CHOICES = {
+      model: AgentsClient::MODELS,
+      effort: AgentsClient::EFFORTS,
+      permission_mode: AgentsClient::PERMISSION_MODES
+    }.freeze
+    FLAGS = {true => true, false => false, "yes" => true, "no" => false}.freeze
+    MAX_PROMPT = 100_000
+    MAX_NAME = 100
+
+    # The hash NewSessionForm#values builds, before `resolve`, from a
+    # request's fields, or Invalid. "default" is nil. An unknown key is
+    # refused rather than ignored, so a misspelt setting can't fall back to
+    # its default unnoticed. A blank prompt, or a directory that does not
+    # exist, passes here; `problem` reports it as the form does.
+    def self.from_params(params, dirs: [])
+      params = params.transform_keys(&:to_s)
+      unknown = params.keys - KEYS
+      raise Invalid.new(unknown.first.to_sym, "unknown key: #{unknown.first.inspect}") if unknown.any?
+      {
+        prompt: prompt_param(params["prompt"]),
+        name: name_param(params["name"]),
+        cwd: cwd_param(params["cwd"], dirs),
+        model: choice_param(:model, params["model"]),
+        effort: choice_param(:effort, params["effort"]),
+        permission_mode: choice_param(:permission_mode, params["permission_mode"]),
+        worktree: flag_param(:worktree, params["worktree"]) || false,
+        remote: flag_param(:remote, params["remote"])
+      }
+    end
+
+    # Unset Remote Control follows /config, then is passed either way so
+    # the daemon records it in respawnFlags. The rest stay nil, for the CLI.
+    def self.resolve(values, defaults)
+      values[:remote].nil? ? values.merge(remote: defaults.remote == "yes") : values
+    end
+
+    # What stops these values from starting a session, as [field, message]
+    # for the form to show and focus, or nil when nothing does.
+    def self.problem(values)
+      return [:prompt, "a prompt is required"] if values[:prompt].empty?
+      return [:cwd, "no such directory: #{values[:cwd]}"] unless File.directory?(values[:cwd])
+      nil
+    end
+
+    # Saved images go into the prompt as the @ mentions the CLI reads. An
+    # `[Image #n]` becomes the nth path, the way a chip expands in the form;
+    # a path the prompt never points at goes on the end.
+    def self.attach(prompt, paths)
+      used = []
+      text = prompt.gsub(/\[Image #(\d+)\]/i) do |token|
+        n = token[/\d+/].to_i
+        next token unless n.between?(1, paths.size)
+        used << n
+        AgentsClient.mention(paths[n - 1])
+      end
+      rest = paths.reject.with_index(1) { |_, n| used.include?(n) }.map { |path| AgentsClient.mention(path) }
+      [text, rest.join("\n")].reject(&:empty?).join("\n\n")
+    end
+
+    # A session's cwd may sit inside a worktree another agent is using;
+    # carrying that into a new prompt would spawn the new agent there too,
+    # writing over the same files. Fall back to the repo it was cut from.
+    def self.strip_worktree(cwd) = cwd.to_s.sub(%r{/\.claude/worktrees/[^/]+(?:/.*)?\z}, "")
+
+    # The daemon's summary line can echo the prompt to the terminal, so no
+    # control character but tab and newline gets that far. A CRLF, the
+    # newline an HTTP client may send, is taken as a newline.
+    def self.prompt_param(value)
+      prompt = string_param(:prompt, value || "").strip.gsub(/\r\n?/, "\n")
+      raise Invalid.new(:prompt, "the prompt is over #{MAX_PROMPT} characters") if prompt.length > MAX_PROMPT
+      if prompt.match?(/[[:cntrl:]&&[^\t\n]]/)
+        raise Invalid.new(:prompt, "the prompt has a control character other than tab or newline")
+      end
+      prompt
+    end
+
+    # The name comes back as the row's label, printed as it is.
+    def self.name_param(value)
+      return nil if value.nil?
+      name = string_param(:name, value).strip
+      raise Invalid.new(:name, "a name is one line") if name.match?(/[[:cntrl:]\u2028\u2029]/)
+      raise Invalid.new(:name, "the name is over #{MAX_NAME} characters") if name.length > MAX_NAME
+      name.empty? ? nil : name
+    end
+
+    # The fewest trailing components that name `path` alone among `dirs`.
+    def self.label(path, dirs)
+      parts = path.split("/").reject(&:empty?)
+      (1..parts.size).each do |n|
+        label = parts.last(n).join("/")
+        return label if dirs.one? { |other| other.end_with?("/#{label}") }
+      end
+      path
+    end
+
+    # A path is taken as given. Anything else names one of `dirs` by its
+    # `label`.
+    def self.cwd_param(value, dirs)
+      cwd = string_param(:cwd, value || "").strip
+      raise Invalid.new(:cwd, "a directory is required") if cwd.empty?
+      raise Invalid.new(:cwd, "a directory is one line") if cwd.match?(/[[:cntrl:]\u2028\u2029]/)
+      return File.expand_path(cwd) if cwd.match?(%r{\A(/|~(/|\z))})
+      found = dirs.select { |dir| dir.end_with?("/#{cwd}") }
+      raise Invalid.new(:cwd, "no directory called #{cwd}") if found.empty?
+      raise Invalid.new(:cwd, "#{cwd} could be any of #{found.join(", ")}") if found.size > 1
+      found.first
+    end
+
+    def self.choice_param(key, value)
+      return nil if value.nil? || value == "default"
+      return value if CHOICES[key].include?(value)
+      raise Invalid.new(key, "#{key} is one of #{CHOICES[key].join(", ")}")
+    end
+
+    def self.flag_param(key, value)
+      return nil if value.nil?
+      FLAGS.fetch(value) { raise Invalid.new(key, "#{key} is true, false, yes or no") }
+    end
+
+    # Each of these ends up in an argv or a path, where a NUL byte raises.
+    # The bytes are checked as UTF-8 whatever the string's tag says: a
+    # binary string always passes `valid_encoding?`.
+    def self.string_param(key, value)
+      raise Invalid.new(key, "#{key} must be a string") unless value.is_a?(String)
+      text = String.new(value, encoding: Encoding::UTF_8)
+      raise Invalid.new(key, "#{key} is not valid UTF-8") unless text.valid_encoding?
+      raise Invalid.new(key, "#{key} contains a NUL byte") if text.include?("\0")
+      text
+    end
+
+    private_class_method :prompt_param, :name_param, :cwd_param, :choice_param, :flag_param, :string_param
+  end
+end

data/lib/claude_inbox/sessions.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require_relative "job_state"
-require_relative "pull_requests"
 
 module ClaudeInbox
   # Puts the list together. JobState goes before PullRequests because the PR