samagotchi 0.2.0

data/lib/samagotchi/web/server.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "rack"
+require "rackup/handler/webrick"
+require "uri"
+require "webrick"
+
+require_relative "app"
+require_relative "session_hub"
+require_relative "../project_scope"
+require_relative "../log"
+require_relative "../version"
+
+module Samagotchi
+  module Web
+    # Launcher for the single-port Web UI.
+    #
+    # Binds strictly to 127.0.0.1 (localhost-only). Use `bin/chi web` to start.
+    class Server
+      # WEBrick logs every exception out of its request loop as an ERROR with
+      # a backtrace, among them a browser dropping a kept-alive connection
+      # (sock.eof? raising ECONNRESET): harmless, so not logged.
+      class Log < WEBrick::Log
+        DROPPED = [Errno::ECONNRESET, Errno::EPIPE, Errno::ECONNABORTED].freeze
+
+        def error(msg)
+          return if DROPPED.any? { |klass| msg.is_a?(klass) }
+
+          super
+        end
+
+        # WEBrick logs the signal that ends its loop (Ctrl-C, a kill) as
+        # FATAL with a backtrace, then re-raises it: .launch says it in a
+        # line instead.
+        def fatal(msg)
+          return if msg.is_a?(SignalException)
+
+          super
+        end
+      end
+
+      DEFAULT_PORT = 4567
+      DEFAULT_HOST = "127.0.0.1"
+      # How long `chi web` waits for a server already on its port to answer.
+      PROBE_TIMEOUT = 0.3
+
+      # `chi web`: one server serves every project, the scope is in the page
+      # URL. If a chi web already runs on the port, print (and with --open,
+      # open) its page for +dir+ and leave it be; else start one.
+      # @param scope ["project", "all"] "all": the plain page, every session
+      # @return [Integer] the exit status
+      def self.launch(port: nil, host: nil, scope: "project", dir: Dir.pwd, open_browser: false, markdown: false, turn_view: true)
+        host = resolve_host(host)
+        port = resolve_port(port)
+        url = scope_url(host, port, dir: dir, scope: scope)
+        found = probe(host, port)
+        case found
+        when Hash
+          puts "chi web already runs on port #{port} (pid #{found["pid"]}): #{url}"
+          open_url(url) if open_browser
+          0
+        when :other
+          warn in_use_message(port)
+          1
+        else
+          start(port: port, host: host, url: url, open_browser: open_browser, markdown: markdown, turn_view: turn_view) ? 0 : 1
+        end
+      rescue Interrupt
+        # Ctrl-C: the server has stopped (start's ensure); one line, and the
+        # status a shell gives a command it interrupted.
+        puts "#{"\n" if $stdout.tty?}Chi Web stopped."
+        130
+      end
+
+      # @param hub [SessionHub, nil] the session projection the page streams
+      #   from; built over the app's state dir unless given
+      # @return [Boolean] false when the port was taken (said so on stderr)
+      def self.start(port: nil, host: nil, url: nil, open_browser: false, state_dir: nil, manager: nil, markdown: false,
+                     turn_view: true, hub: nil)
+        port = resolve_port(port)
+        host = resolve_host(host)
+        url ||= "http://#{url_host(host)}:#{port}/"
+
+        hub ||= SessionHub.new(state_dir: state_dir || Session.default_state_dir, manager: manager || SessionManager)
+        app = App.new(manager: manager, state_dir: state_dir, markdown: markdown, turn_view: turn_view, hub: hub)
+        Samagotchi::Log.info(:web, "start", url: "http://#{host}:#{port}", version: Samagotchi::VERSION)
+        hub.start
+        # Said once the port is bound: a second chi web racing for it gets
+        # the in-use line instead.
+        started = lambda do
+          puts "Chi Web on #{url} (public: #{File.expand_path("public", __dir__)})"
+          puts "Press Ctrl-C to stop."
+          $stdout.flush # a log file isn't line-buffered
+          if open_browser
+            Thread.new do
+              sleep 0.8
+              open_url(url)
+            end
+          end
+        end
+
+        # The event loops (GET /api/events) end once WEBrick leaves
+        # :Running: it joins every request thread before run returns.
+        Rackup::Handler::WEBrick.run(app, Host: host, Port: port, AccessLog: [], Logger: Log.new($stderr, WEBrick::Log::WARN),
+                                          StartCallback: started) do |server|
+          app.server_running = -> { server.status == :Running }
+        end
+        true
+      rescue Errno::EADDRINUSE
+        warn in_use_message(port)
+        false
+      ensure
+        hub&.stop
+        Samagotchi::Log.info(:web, "stop") if app
+      end
+
+      def self.resolve_host(host)
+        host = (host || ENV.fetch("SAMAGOTCHI_WEB_HOST", DEFAULT_HOST)).to_s.strip
+        host = DEFAULT_HOST if host.empty?
+        return host if %w[127.0.0.1 ::1 localhost].include?(host)
+
+        Samagotchi::Log.warn(:web, "bind_forced", echo: "Web server only binds to 127.0.0.1 (got #{host}); forcing 127.0.0.1", host: host.to_s)
+        DEFAULT_HOST
+      end
+
+      # The page for +dir+: its project view (?dir=) when it is in a repo,
+      # the plain page (every session) outside one or with scope "all".
+      def self.scope_url(host, port, dir:, scope: "project")
+        base = "http://#{url_host(host)}:#{port}/"
+        return base if scope.to_s == "all" || ProjectScope.root_for(dir).nil?
+
+        # Slashes stay as they are (valid in a query): a URL people can read.
+        "#{base}?dir=#{URI.encode_www_form_component(dir).gsub("%2F", "/")}"
+      end
+
+      def self.url_host(host)
+        host.include?(":") ? "[#{host}]" : host
+      end
+
+      # What answers on the port: the /api/info hash of a chi web that knows
+      # ?dir, :free when nothing listens, :other for anything else (an older
+      # chi web, another program).
+      def self.probe(host, port, timeout: PROBE_TIMEOUT)
+        response = Net::HTTP.start(host, port, open_timeout: timeout, read_timeout: timeout) { |http| http.get("/api/info") }
+        probe_verdict(response.code.to_i, response.body)
+      rescue Errno::ECONNREFUSED, Errno::EADDRNOTAVAIL
+        :free
+      rescue StandardError
+        :other
+      end
+
+      def self.probe_verdict(status, body)
+        info = status == 200 ? JSON.parse(body.to_s) : nil
+        info.is_a?(Hash) && info["app"] == "chi-web" && Array(info["features"]).include?("dir") ? info : :other
+      rescue JSON::ParserError
+        :other
+      end
+
+      def self.in_use_message(port)
+        "Error: port #{port} is in use (an older chi web? restart it, or use --port)"
+      end
+
+      def self.resolve_port(port)
+        raw = port || ENV.fetch("SAMAGOTCHI_WEB_PORT", DEFAULT_PORT.to_s)
+        parsed = raw.to_s.to_i
+        parsed.positive? ? parsed : DEFAULT_PORT
+      end
+
+      def self.open_url(url)
+        case RbConfig::CONFIG["host_os"]
+        when /darwin/ then system("open", url)
+        when /linux/ then system("xdg-open", url)
+        when /mswin|mingw/ then system("start", url)
+        else Samagotchi::Log.info(:web, "open_manually", echo: "Please open #{url} manually")
+        end
+      rescue StandardError => e
+        Samagotchi::Log.warn(:web, "open_failed", echo: "Failed to open browser: #{e.message} — please open #{url} manually", error: e.class.name)
+      end
+    end
+  end
+end

data/lib/samagotchi/web/session_hub.rb

@@ -0,0 +1,329 @@
+# frozen_string_literal: true
+
+require "json"
+require "monitor"
+require "time"
+
+require_relative "../session"
+require_relative "../session_manager"
+require_relative "../bridge_client"
+require_relative "../log"
+require_relative "session_summary"
+
+module Samagotchi
+  module Web
+    # chi web's one in-memory projection of the session list, fed by a cheap
+    # watcher over the state dir, pushed to every open tab (GET /api/events).
+    # Files stay the source of truth; workers and the Bridge don't know it.
+    #
+    # Every session-JSON writer goes tmp + rename, and rename-into-dir and
+    # unlink bump the parent dir's mtime, so one stat of the state dir says
+    # "some session file changed" and one stat of `<id>/` says "recap.json
+    # or bridge.json appeared, changed or went". Nothing in-place is
+    # watched: the pid file and owner.lock are read by the owner probes.
+    #
+    # #scan does one pass and is driven by the tick thread (#start) or by a
+    # spec. Scan, #touch, the projection and the deliveries all run under
+    # one Monitor, and a subscriber is added and its snapshot taken as one
+    # step under it, so no stale upsert can follow a fresh snapshot.
+    class SessionHub
+      SCAN_INTERVAL = 1.0
+      # The flock leaves no file trace when its holder dies, so owners are
+      # probed: every tick for the sessions the projection believes owned
+      # (a handful; OwnerLock.owner is open + LOCK_SH|LOCK_NB + close), and
+      # all sessions this often (a plain REPL that opened an old session
+      # without saving it has no file signal until its first save).
+      FULL_PROBE_INTERVAL = 10.0
+
+      # What a subscriber gets: `session` with {session: summary} for an
+      # upsert, `session_gone` with {id:} for a removal. seq is monotonic per
+      # hub, for the log's sake: there is no replay.
+      Event = Struct.new(:type, :seq, :data, keyword_init: true)
+
+      # The projection's entry: the summary the page sees, the parsed
+      # (messages-less) Session it was built from, and the stamps that say
+      # whether anything changed: the file's [mtime, size], the session
+      # dir's mtime, and the live stamp {pid, kind, bridge_started_at} so
+      # a change of worker is a change even when `owner` reads the same.
+      Entry = Struct.new(:session, :summary, :stamp, :dir_stamp, :owner, :live, keyword_init: true)
+
+      # Returned by #subscribe.
+      class Subscription
+        def initialize(sink, hub)
+          @sink = sink
+          @hub = hub
+        end
+
+        def call(event)
+          @sink.call(event)
+        end
+
+        def unsubscribe
+          @hub.unsubscribe(self)
+        end
+      end
+
+      # @param state_dir [String] the sessions dir (Session.default_state_dir)
+      # @param manager [#session_owner, #retention_sweep_if_due] SessionManager,
+      #   or a stand-in
+      # @param now [#call] a monotonic clock in seconds (specs drive it)
+      def initialize(state_dir:, manager: SessionManager, now: nil, scan_interval: SCAN_INTERVAL,
+                     full_probe_interval: FULL_PROBE_INTERVAL)
+        @state_dir = state_dir
+        @manager = manager
+        @now = now || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+        @scan_interval = scan_interval
+        @full_probe_interval = full_probe_interval
+        @monitor = Monitor.new
+        @sessions = {}      # id → Entry
+        @subscribers = []
+        @seq = 0
+        @dir_mtime = nil    # the state dir's mtime at the last glob
+        @root_cache = {}    # folder → project root, for sessions saved before project_root
+        @next_full_probe = nil
+        @wakeup = Queue.new # stop wakes the tick thread out of its sleep
+        @thread = nil
+        @stopped = false
+      end
+
+      # Spawn the tick thread (idempotent). Logs nothing: Server.start's
+      # start and stop lines are the web log's.
+      def start
+        return self if @thread&.alive?
+
+        @stopped = false
+        @thread = Thread.new { run_loop }
+        self
+      end
+
+      # End the tick thread (idempotent); the event loops see #stopped?.
+      def stop
+        @stopped = true
+        @wakeup << :stop
+        thread = @thread
+        @thread = nil
+        thread&.join(@scan_interval + 1.0)
+        nil
+      end
+
+      def stopped?
+        @stopped
+      end
+
+      # One pass: what changed on disk since the last one, emitted. Every
+      # +full_probe_interval+ it also probes every session's owner and
+      # gives the retention sweep its chance (it used to run on
+      # GET /api/sessions, which the page no longer calls).
+      def scan
+        @monitor.synchronize do
+          full = full_probe_due?
+          scan_files
+          @sessions.each_key { |id| refresh(id, probe: full) }
+          sweep if full
+        end
+        nil
+      end
+
+      # Rescan one session now (its file, its folder, its owner), for the
+      # page's own actions: no waiting for the next tick.
+      def touch(id)
+        @monitor.synchronize do
+          path = File.join(@state_dir, "#{id}#{Session::FILE_EXT}")
+          if File.file?(path)
+            @sessions[id] ||= Entry.new
+            refresh(id, probe: true)
+          elsif @sessions.key?(id)
+            drop(id)
+          end
+        end
+        nil
+      end
+
+      # The projection as the list route answers it: sorted, and only
+      # +project_root+'s sessions when one is given (nil: every session, as
+      # outside a repo).
+      # @return [Array<Hash>] summaries
+      def snapshot(project_root: nil, sort: "updated_at", order: "desc")
+        @monitor.synchronize do
+          entries = @sessions.values.reject { |e| e.summary.nil? }
+          entries = entries.select { |e| e.summary[:project_root] == project_root } if project_root
+          key = sort.to_s == "created_at" ? :created_at : :updated_at
+          sorted = entries.sort_by { |e| sort_time(e.summary[key]) }
+          sorted.reverse! unless order.to_s == "asc"
+          sorted.map(&:summary)
+        end
+      end
+
+      # Register a sink (#call(event)). With +snapshot:+ the current
+      # projection comes back with the handle, taken in the same step, so
+      # every event after it is newer than it.
+      # @return [Subscription, (Subscription, Array<Hash>)]
+      def subscribe(sink, snapshot: false, project_root: nil)
+        @monitor.synchronize do
+          handle = Subscription.new(sink, self)
+          @subscribers << handle
+          return handle unless snapshot
+
+          [handle, self.snapshot(project_root: project_root)]
+        end
+      end
+
+      def unsubscribe(handle)
+        @monitor.synchronize { !@subscribers.delete(handle).nil? }
+      end
+
+      private
+
+      def run_loop
+        until @stopped
+          begin
+            scan
+          rescue StandardError => e
+            Log.warn(:web, "hub_scan_failed", error: e.class.name, msg: e.message)
+          end
+          @wakeup.pop(timeout: @scan_interval)
+        end
+      end
+
+      def full_probe_due?
+        now = @now.call
+        return false if @next_full_probe && now < @next_full_probe
+
+        @next_full_probe = now + @full_probe_interval
+        true
+      end
+
+      def sweep
+        return unless @manager.respond_to?(:retention_sweep_if_due)
+
+        @manager.retention_sweep_if_due(state_dir: @state_dir)
+      rescue StandardError
+        nil
+      end
+
+      # The state dir's files: a new id is parsed and emitted, an id gone
+      # from disk is dropped, a changed file is re-parsed. Skipped when the
+      # dir's mtime says nothing was renamed in or unlinked since.
+      def scan_files
+        dir_stat = begin
+          File.stat(@state_dir)
+        rescue SystemCallError
+          nil
+        end
+        if dir_stat.nil?
+          @sessions.keys.each { |id| drop(id) }
+          @dir_mtime = nil
+          return
+        end
+        return if dir_stat.mtime == @dir_mtime
+
+        @dir_mtime = dir_stat.mtime
+        on_disk = Dir.glob(File.join(@state_dir, "*#{Session::FILE_EXT}")).to_h do |path|
+          [File.basename(path, Session::FILE_EXT), path]
+        end
+        (@sessions.keys - on_disk.keys).each { |id| drop(id) }
+        on_disk.each_key { |id| @sessions[id] ||= Entry.new }
+      end
+
+      # Bring one entry up to date with its file, its folder and its owner;
+      # emit when the page would see a difference. The owner is probed when
+      # asked (+probe+), when the entry believes it has one (to see it go),
+      # and when its folder changed (a new owner.lock, a bridge.json).
+      def refresh(id, probe: false)
+        entry = @sessions[id]
+        path = File.join(@state_dir, "#{id}#{Session::FILE_EXT}")
+        stat = begin
+          File.stat(path)
+        rescue SystemCallError
+          nil
+        end
+        return drop(id) if stat.nil?
+
+        stamp = [stat.mtime, stat.size]
+        changed = false
+        if stamp != entry.stamp
+          session = Session.summary_from_file(path)
+          # Corrupt, or missing a field: not a session, as Session.list has it.
+          return drop(id) if session.nil?
+
+          # Looked up once per parse (a git call for a session saved before
+          # the field), never per tick.
+          session.project_root = session.project_root(cache: @root_cache)
+          entry.session = session
+          entry.stamp = stamp
+          changed = true
+        end
+        dir = Session.session_dir(id, state_dir: @state_dir)
+        dir_stamp = dir_mtime(dir)
+        if dir_stamp != entry.dir_stamp
+          entry.dir_stamp = dir_stamp
+          changed = true
+        end
+        owner = probe || changed || entry.owner ? owner_of(id) : entry.owner
+        live = live_stamp(owner, dir)
+        live_changed = live != entry.live
+        return unless changed || live_changed
+
+        entry.owner = owner
+        entry.live = live
+        summary = SessionSummary.build(entry.session, owner: owner, session_dir: dir)
+        # A new worker (pid) or a new Bridge for the same session is an
+        # event for the page even when the summary reads the same: it
+        # reconnects its stream on it.
+        return if summary == entry.summary && !live_changed
+
+        entry.summary = summary
+        emit("session", session: summary)
+      end
+
+      def drop(id)
+        entry = @sessions.delete(id)
+        emit("session_gone", id: id) if entry&.summary
+      end
+
+      def owner_of(id)
+        return nil unless @manager.respond_to?(:session_owner)
+
+        @manager.session_owner(id, state_dir: @state_dir)
+      rescue StandardError
+        nil
+      end
+
+      def dir_mtime(dir)
+        File.stat(dir).mtime
+      rescue SystemCallError
+        nil
+      end
+
+      # A change of worker is a change even when `owner` reads "worker"
+      # both times: the pid, or the Bridge's start time, tells them apart.
+      def live_stamp(owner, dir)
+        return nil unless owner
+
+        { pid: owner["pid"], kind: owner["kind"], bridge_started_at: bridge_started_at(dir) }
+      end
+
+      def bridge_started_at(dir)
+        JSON.parse(File.read(File.join(dir, BridgeClient::SIDECAR_FILE)))["started_at"]
+      rescue StandardError
+        nil
+      end
+
+      def emit(type, data)
+        @seq += 1
+        event = Event.new(type: type, seq: @seq, data: data)
+        @subscribers.dup.each do |handle|
+          handle.call(event)
+        rescue StandardError => e
+          Log.warn(:web, "hub_subscriber_failed", error: e.class.name, msg: e.message)
+        end
+      end
+
+      def sort_time(value)
+        Time.iso8601(value.to_s)
+      rescue ArgumentError
+        Time.at(0)
+      end
+    end
+  end
+end

data/lib/samagotchi/web/session_summary.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "../session"
+require_relative "../recap_store"
+require_relative "../bridge_client"
+
+module Samagotchi
+  module Web
+    # A session as the page's cards and list see it: the saved session's
+    # fields with its live owner applied. Built the same way wherever a
+    # session is answered (GET /api/sessions, the session view, the session
+    # hub's events), so every path agrees on status, owner and bridge_up.
+    module SessionSummary
+      module_function
+
+      # @param session [Session] a saved session (messages may be empty)
+      # @param owner [Hash, nil] SessionManager.session_owner's answer; its
+      #   kind is shown as `owner`
+      # @param session_dir [String] the session's folder (recap.json, bridge.json)
+      # @param status [String] the turn state to show; by default
+      #   .displayed_status of the session and its owner
+      # @param root_cache [Hash, nil] ProjectScope.root_for's cache, shared
+      #   across one listing (a session saved before project_root existed
+      #   looks its project up)
+      # @return [Hash] symbol keys
+      def build(session, owner:, session_dir:, status: displayed_status(session, owner: owner), root_cache: nil)
+        used = session.respond_to?(:used_memory_names) ? Array(session.used_memory_names) : []
+        {
+          id: session.id,
+          status: status,
+          mode: session.mode,
+          model_name: session.model_name,
+          working_directory: session.working_directory,
+          created_at: session.created_at,
+          updated_at: session.updated_at,
+          last_prompt: session.last_prompt,
+          short_id: session.id.to_s[0, 8],
+          test_run: !!session.test_run,
+          used_memory_names: used,
+          # The session's --memory and --mute lists (info-bar tooltip).
+          preloaded_memory_names: session.respond_to?(:preloaded_memory_names) ? Array(session.preloaded_memory_names) : [],
+          muted_memory_names: session.respond_to?(:muted_memory_names) ? Array(session.muted_memory_names) : [],
+          # The session that delegated this one (the `delegate` tool), else nil.
+          parent_id: session.respond_to?(:parent_id) ? session.parent_id : nil,
+          first_preview: first_preview_for(session),
+          owner: owner&.fetch("kind", nil),
+          # The saved recap's first sentence, for the session card.
+          recap: RecapStore.preview(session_dir),
+          project_root: session.project_root(cache: root_cache),
+          # A worker is reachable: its Bridge sidecar is there and the
+          # owner lock is held. A sidecar a dead worker left is not up.
+          bridge_up: bridge_up?(session_dir, owner)
+        }
+      end
+
+      # status is turn state (idle/running). The live worker's snapshot is the
+      # truth; on disk, a "running" with no live owner was left by a worker
+      # that died mid-turn.
+      def displayed_status(session, snapshot = nil, owner:)
+        return snapshot["status"] if snapshot.is_a?(Hash) && snapshot["status"]
+        return session.status unless session.status == Session::STATUS_RUNNING
+
+        owner ? session.status : Session::STATUS_IDLE
+      end
+
+      # @return [Boolean] the sidecar file is there and the session has a
+      #   live owner (the file alone says nothing: the worker may be gone)
+      def bridge_up?(session_dir, owner)
+        !owner.nil? && File.file?(File.join(session_dir, BridgeClient::SIDECAR_FILE))
+      rescue StandardError
+        false
+      end
+
+      def first_preview_for(session)
+        raw = session.first_preview || session.last_prompt || ""
+        norm = raw.to_s.gsub(/\s+/, " ").strip
+        return "" if norm.empty?
+
+        norm.length > 80 ? "#{norm[0, 80]}…" : norm
+      rescue StandardError
+        ""
+      end
+    end
+  end
+end