samagotchi 0.2.0

data/lib/samagotchi/bridge/sse_writer.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "event_id"
+
+module Samagotchi
+  class Bridge
+    # Per-connection SSE writer.
+    #
+    # This object doubles as the per-connection live observer wired into the
+    # Engine via `Engine#subscribe`: its `#call` is invoked synchronously from
+    # `Engine#emit_event` inside the turn thread, so it must be strictly
+    # non-blocking — it only enqueues onto a bounded queue and returns. A
+    # dedicated writer thread (the connection's own thread) drains the queue
+    # and serialises SSE frames onto the socket, so a slow / hung client can
+    # never stall the running turn or other subscribers.
+    #
+    # #serve! performs the replay wiring in the correctness-ordered sequence
+    # mandated by the bridge design invariants:
+    #   1. subscribe the live queue FIRST
+    #   2. capture `event_count` (snapshot)
+    #   3. replay buffered `seq ∈ (from_seq, snapshot]`
+    #   4. drain the live queue for `seq > snapshot`
+    # which guarantees no gap and no overlap; a per-connection `event_seq`
+    # high-water mark de-duplicates the subscribe→capture window.
+    #
+    # A client joining with `?snapshot=1` (and no cursor) instead gets one
+    # `snapshot` frame: the session's messages, the turn in progress and the
+    # event_seq they cover, taken with the event log held, together with the
+    # subscribe. Live events follow from the next seq. A `reset` frame (the
+    # cursor can't be replayed) carries the same snapshot, numbered with its
+    # own seq.
+    #
+    # Frame ids are `<seq>-<epoch>`: event_seq starts over in each worker, so
+    # the epoch (one per Bridge, so per worker) tells whose seq a cursor is.
+    # A cursor from another epoch gets a `reset` frame. A plain numeric
+    # cursor (a client that keeps event_seq itself) replays as before.
+    class SSEWriter
+      DEFAULT_MAX_QUEUE = 1024
+      DEFAULT_HEARTBEAT_INTERVAL = 15.0
+
+      # @param engine [Samagotchi::Engine] the owning engine (live fan-out)
+      # @param ring [Samagotchi::Bridge::RingBuffer] shared capture buffer
+      # @param session_id [String]
+      # @param last_event_id [String, nil] reconnect cursor (or ?from_seq=):
+      #   `<seq>-<epoch>` or a plain seq
+      # @param epoch [String, nil] this worker's epoch, in every frame id
+      # @param snapshot_provider [#call] -> {status:, message_count:,
+      #   last_prompt:, event_seq:} (Engine#session_state_snapshot)
+      # @param turn_snapshot_provider [#call, nil] -> {messages:, current_turn:,
+      #   queued:, event_seq:}; called with the event log held
+      #   (Bridge#snapshot). Defaults to just the event_seq.
+      # @param join_with_snapshot [Boolean] start with a snapshot frame rather
+      #   than a replay
+      # @param bridge [Samagotchi::Bridge, nil] for stop signalling
+      # @param max_queue [Integer] bounded-queue capacity
+      # @param heartbeat_interval [Float] idle-seconds between `: ping` frames
+      def initialize(engine:, ring:, session_id:, last_event_id: nil, epoch: nil,
+                     snapshot_provider:, turn_snapshot_provider: nil, join_with_snapshot: false, bridge: nil,
+                     max_queue: DEFAULT_MAX_QUEUE,
+                     heartbeat_interval: DEFAULT_HEARTBEAT_INTERVAL)
+        @engine = engine
+        @ring = ring
+        @session_id = session_id
+        @last_event_id = last_event_id
+        @epoch = epoch
+        @snapshot_provider = snapshot_provider
+        @turn_snapshot_provider = turn_snapshot_provider || -> { { event_seq: @engine.event_count } }
+        @join_with_snapshot = join_with_snapshot
+        @bridge = bridge
+        @max_queue = max_queue
+        @heartbeat_interval = heartbeat_interval
+
+        @queue = BoundedQueue.new(capacity: @max_queue)
+        cursor_seq, cursor_epoch = EventId.parse(@last_event_id)
+        # A foreign cursor's seq means nothing here; its reset sets the mark.
+        @foreign_cursor = !cursor_epoch.nil? && cursor_epoch != @epoch
+        @high_water = @foreign_cursor ? 0 : cursor_seq
+        @handle = nil
+        @serving = false
+        @mutex = Monitor.new
+      end
+
+      # Non-blocking enqueue used as the per-connection live observer. Any
+      # caller runs in the turn thread; must never block. Events already
+      # served (seq <= high water) are dropped to avoid replay overlap.
+      def call(payload)
+        seq = payload[:event_seq]
+        return if seq && seq <= @high_water
+
+        @queue.push(payload)
+      rescue StandardError
+        # Enqueue isolation is best-effort; a bad payload must not break the
+        # running turn.
+        nil
+      end
+
+      # Run the serve loop on the caller's (connection) thread. Blocks until
+      # the client disconnects or the bridge stops.
+      def serve!(io)
+        @serving = true
+        write_sse_headers(io)
+        begin
+          if @join_with_snapshot
+            # Subscribe and snapshot as one step of the event log, then go live.
+            snapshot = @engine.synchronize_events do
+              @handle = @engine.subscribe(observer: self)
+              take_snapshot
+            end
+            write_snapshot_frame(io, :snapshot, snapshot)
+          else
+            # (1) subscribe the live queue FIRST.
+            @handle = @engine.subscribe(observer: self)
+            # (2) capture the snapshot sequence.
+            snapshot_seq = @engine.event_count
+            # (3) replay buffered (from_seq, snapshot].
+            replay!(io, snapshot_seq)
+          end
+          # (4) drain live events for seq > snapshot.
+          drain!(io)
+        rescue Errno::EPIPE, Errno::ECONNRESET, IOError
+          # Client hung up; nothing to do.
+        ensure
+          @serving = false
+          @engine.unsubscribe(handle: @handle) if @handle
+        end
+      end
+
+      private
+
+      def replay!(io, snapshot_seq)
+        from_seq = @high_water
+        oldest = @ring.oldest_seq
+        if @foreign_cursor || from_seq > snapshot_seq || (from_seq.positive? && oldest && from_seq < oldest - 1)
+          # Cursor is from another worker (epoch), ahead of the engine (a
+          # worker restarted, plain cursor) or behind the
+          # ring's buffered window (overflow): the server cannot replay the
+          # gap, so it emits a reset marker and the client re-syncs. A cursor
+          # at oldest - 1 has seen everything before the window, so it
+          # replays. A cold
+          # connect (from_seq == 0) replays the whole served window, and a
+          # fully caught-up cursor (from_seq == snapshot_seq) is NOT a reset
+          # case — it gets an empty replay and holds for live events.
+          emit_reset(io)
+        else
+          @ring.events_in_range(after_seq: from_seq, to_seq: snapshot_seq).each { |record| write_event(io, record[:data]) }
+        end
+      end
+
+      def drain!(io)
+        loop do
+          payload = @queue.pop(@heartbeat_interval)
+          if payload
+            if payload.is_a?(Hash) && payload[:sse_reset]
+              emit_reset(io)
+              next
+            end
+
+            write_event(io, payload)
+            # A fresh overflow since the last drain => the client fell too far
+            # behind; nudge a reconnect rather than flooding more events.
+            emit_reset(io) if @queue.overflow_dropped?
+            @queue.clear_overflow!
+          elsif @bridge&.stopped?
+            break
+          else
+            write_heartbeat(io)
+          end
+        end
+      rescue Errno::EPIPE, Errno::ECONNRESET, IOError
+        nil
+      end
+
+      def write_event(io, event)
+        seq = event[:event_seq]
+        return if seq && seq <= @high_water
+
+        write_frame(io, seq: seq, data: event)
+        @high_water = seq if seq && seq > @high_water
+      end
+
+      def write_sse_headers(io)
+        io.write(
+          "HTTP/1.1 200 OK\r\n" \
+          "Content-Type: text/event-stream\r\n" \
+          "Cache-Control: no-cache\r\n" \
+          "Connection: keep-alive\r\n" \
+          "X-Accel-Buffering: no\r\n" \
+          "Access-Control-Allow-Origin: *\r\n" \
+          "Access-Control-Allow-Methods: GET, POST, OPTIONS\r\n" \
+          "Access-Control-Allow-Headers: Content-Type, Last-Event-ID\r\n" \
+          "\r\n"
+        )
+        io.flush
+      rescue Errno::EPIPE, Errno::ECONNRESET, IOError
+        raise
+      end
+
+      # Serialise one SSE event: an `id:` line (the replay cursor), an optional
+      # `event:` line for EventSource.addEventListener, one or more `data:` lines,
+      # and the terminating blank line.
+      def write_frame(io, seq:, data:)
+        lines = []
+        lines << "id: #{EventId.format(seq, @epoch)}"
+        event_type = data.is_a?(Hash) && (data[:type] || data["type"])
+        lines << "event: #{event_type}" if event_type && !event_type.to_s.empty?
+        JSON.generate(data).each_line { |line| lines << "data: #{line.chomp}" }
+        io.write(lines.join("\r\n") + "\r\n\r\n")
+        io.flush
+      rescue Errno::EPIPE, Errno::ECONNRESET, IOError
+        raise
+      end
+
+      def write_heartbeat(io)
+        io.write(": ping\r\n\r\n")
+        io.flush
+      rescue Errno::EPIPE, Errno::ECONNRESET, IOError
+        raise
+      end
+
+      # Emit a control frame carrying the current snapshot so a client that
+      # cannot replay can re-derive state, then continue live.
+      def emit_reset(io)
+        write_snapshot_frame(io, :reset, @engine.synchronize_events { take_snapshot })
+      end
+
+      # With the event log held: the snapshot, and the high-water mark moved
+      # to its seq (down too, for a cursor from before a worker restart), so
+      # events after it pass #call and events it covers are skipped.
+      def take_snapshot
+        snapshot = @turn_snapshot_provider.call
+        @high_water = snapshot[:event_seq].to_i
+        snapshot.merge(event_id: EventId.format(@high_water, @epoch))
+      end
+
+      def write_snapshot_frame(io, type, snapshot)
+        seq = snapshot[:event_seq]
+        state = @snapshot_provider.call.merge(event_seq: seq, event_id: snapshot[:event_id])
+        write_frame(io, seq: seq, data: { type: type, snapshot: snapshot, session_state_snapshot: state })
+      end
+
+      def closed?
+        @mutex.synchronize { !@serving }
+      end
+    end
+  end
+end

data/lib/samagotchi/bridge/turn_accumulator.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require_relative "../kernel_loop"
+
+module Samagotchi
+  class Bridge
+    # Folds the event log into the state of the turn in progress, so a UI
+    # that joins mid-turn can render all of it at once (the Bridge's snapshot
+    # frame) instead of replaying events the ring buffer may have dropped.
+    #
+    # A persistent observer: #call runs under the SessionObserver's lock,
+    # enqueue-cheap (appends to strings and arrays). The turn is cleared on
+    # its terminal event, the same event that brings its messages into the
+    # session, so a snapshot shows a turn in exactly one of the two.
+    class TurnAccumulator
+      TERMINAL_EVENTS = %i[turn_completed turn_canceled turn_failed].freeze
+
+      def initialize(max_output_chars: KernelLoop::DEFAULT_MAX_TOOL_OUTPUT_CHARS)
+        @max_output_chars = max_output_chars
+        @mutex = Mutex.new
+        @turn = nil
+        @queued = []
+        @merged_origins = []
+        @recap = nil
+        @continue_offer = nil
+      end
+
+      def call(event)
+        @mutex.synchronize { fold(event) }
+      rescue StandardError
+        nil # never break the running turn
+      end
+
+      # @return [Hash, nil] a copy of the turn in progress: prompt, origin,
+      #   continue, ordered parts (thinking / text / tool / input / reminder / hook_notice),
+      #   pending_question and the last event_seq folded in
+      def current_turn
+        @mutex.synchronize { @turn && Marshal.load(Marshal.dump(@turn)) }
+      end
+
+      # The turn in progress as conversation messages, for a plugin's
+      # ctx.messages mid-turn (plan O1): its prompt (with its images), the
+      # model's text so far, and the lines merged into it, in order. Tool
+      # calls and thinking are left out.
+      # @return [Array<Hash>] [] with no turn running
+      def current_messages
+        @mutex.synchronize { @turn ? self.class.messages_of(@turn) : [] }
+      end
+
+      # @param turn [Hash] #current_turn's shape
+      # @return [Array<Hash>] {role: "user"|"model", content:, images:}
+      def self.messages_of(turn)
+        messages = []
+        text = +""
+        flush = lambda do
+          messages << { role: "model", content: text.dup } unless text.strip.empty?
+          text.clear
+        end
+        unless turn[:prompt].nil?
+          prompt = { role: "user", content: turn[:prompt].to_s }
+          prompt[:images] = turn[:images] if turn[:images]
+          messages << prompt
+        end
+        Array(turn[:parts]).each do |part|
+          case part[:kind]
+          when "text" then text << part[:text].to_s
+          when "input"
+            flush.call
+            messages << { role: "user", content: part[:text].to_s }
+          end
+        end
+        flush.call
+        messages
+      end
+
+      # @return [String, nil] the last idle recap, until a turn makes it stale
+      def recap
+        @mutex.synchronize { @recap }
+      end
+
+      # @return [Hash, nil] a copy of the pending continue offer ({context:,
+      #   no_interrupt:}), from :continue_offered until :continue_resolved
+      def continue_offer
+        @mutex.synchronize { @continue_offer && Marshal.load(Marshal.dump(@continue_offer)) }
+      end
+
+      # @return [Array<Hash>] turns announced as queued that haven't started
+      #   or been merged into a running turn yet
+      def queued
+        @mutex.synchronize { @queued.map(&:dup) }
+      end
+
+      private
+
+      def fold(event)
+        type = event[:type]
+        case type
+        when :turn_enqueued
+          queued = { enqueued_id: event[:enqueued_id], client_id: event[:client_id], prompt: event[:prompt] }
+          queued[:images] = event[:images] if event[:images]
+          @queued << queued
+        when :recap_ready
+          # One collected just as a turn started describes the chat before it.
+          @recap = event[:recap] unless @turn
+        when :continue_offered
+          @continue_offer = { context: event[:context], no_interrupt: !!event[:no_interrupt] }
+        when :continue_resolved
+          @continue_offer = nil
+        when :turn_started
+          @recap = nil
+          dequeue([event[:origin]])
+          @turn = { prompt: event[:prompt], origin: event[:origin], continue: !!event[:continue],
+                    parts: [], pending_question: nil }
+          @turn[:images] = event[:images] if event[:images]
+        when :input_merged
+          @merged_origins = Array(event[:origins])
+          dequeue(@merged_origins)
+        end
+        return unless @turn
+
+        fold_turn_event(event)
+        if TERMINAL_EVENTS.include?(type)
+          @turn = nil
+          @merged_origins = []
+        else
+          @turn[:event_seq] = event[:event_seq] if event[:event_seq]
+        end
+      end
+
+      def fold_turn_event(event)
+        parts = @turn[:parts]
+        case event[:type]
+        when :generation_chunk
+          if event.key?(:text)
+            # Profile-split stream: thinking and visible text separately.
+            append_text(event[:iteration], "thinking", event[:thinking])
+            append_text(event[:iteration], "text", event[:text])
+          else
+            append_text(event[:iteration], "text", event[:content])
+          end
+        when :tool_call_started
+          part = { kind: "tool", iteration: event[:iteration], call_index: event[:call_index],
+                   tool: event[:tool], params: event[:params], status: "running" }
+          part[:label] = event[:label] if event[:label]
+          parts << part
+        when :tool_call_completed
+          tool = parts.reverse_each.find do |part|
+            part[:kind] == "tool" && part[:iteration] == event[:iteration] && part[:call_index] == event[:call_index]
+          end
+          return unless tool
+
+          output = event[:output].to_s
+          capped = output.length > @max_output_chars
+          tool[:status] = (event.dig(:activity, :status) || "ok").to_s
+          tool[:output] = capped ? output[0, @max_output_chars] : output.dup
+          tool[:output_truncated] = capped || !!event[:output_truncated]
+          tool[:images] = event[:images] if event[:images]
+        when :pending_input_merged
+          parts << { kind: "input", iteration: event[:iteration], text: event[:content].to_s.dup, origins: @merged_origins }
+          @merged_origins = []
+        when :reminder_injected
+          parts << { kind: "reminder", reminders: Array(event[:reminders]).map(&:dup) }
+        when :hook_notice
+          parts << { kind: "hook_notice", hook: event[:hook].to_s, text: event[:text].to_s, level: event[:level].to_s }
+        when :question_requested
+          @turn[:pending_question] = event[:pending_question]&.dup
+        when :question_answered, :question_cancelled
+          @turn[:pending_question] = nil
+        end
+      end
+
+      def append_text(iteration, kind, text)
+        return if text.nil? || text.empty?
+
+        last = @turn[:parts].last
+        if last && last[:kind] == kind && last[:iteration] == iteration
+          last[:text] << text
+        else
+          @turn[:parts] << { kind: kind, iteration: iteration, text: String.new(text) }
+        end
+      end
+
+      def dequeue(origins)
+        ids = origins.filter_map { |origin| origin.is_a?(Hash) ? origin[:enqueued_id] : nil }
+        @queued.reject! { |entry| ids.include?(entry[:enqueued_id]) } unless ids.empty?
+      end
+    end
+  end
+end