samagotchi 0.8.1 → 0.10.0

data/lib/samagotchi/bridge/card_store.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../events"
+
 module Samagotchi
   class Bridge
     # The last cards (Engine#show_card), hook notices (:hook_notice) and
@@ -25,9 +27,6 @@ module Samagotchi
     # A failed turn leaves no prompt, so its cards stay before the next one.
     class CardStore
       CAPACITY = 20
-      # A failed turn's prompt goes back to the composer: no turn in the
-      # conversation.
-      TURN_ENDS = %i[turn_completed turn_canceled].freeze
 
       def initialize(capacity: CAPACITY)
         @capacity = capacity
@@ -79,7 +78,8 @@ module Samagotchi
         when :turn_failed
           @running = false
           settle_during(after_turn: false)
-        when *TURN_ENDS
+        # The turns that stay in the conversation.
+        when *Events::TURN_KEPT
           @running = false
           @turns_done += 1
           settle_during(after_turn: true)

data/lib/samagotchi/bridge/pending_card.rb

@@ -3,6 +3,7 @@
 require "json"
 require "fileutils"
 require_relative "../atomic_file"
+require_relative "../events"
 
 module Samagotchi
   class Bridge
@@ -18,7 +19,6 @@ module Samagotchi
     # writes it, nor does a card between turns.
     class PendingCard
       FILE = "pending_card.json"
-      TURN_ENDS = %i[turn_completed turn_canceled turn_failed].freeze
 
       # @param session_dir [String] the session's folder
       # @return [Hash, nil] {id:, bundle:}, nil without a readable file
@@ -58,7 +58,7 @@ module Samagotchi
       def fold(event)
         case event[:type]
         when :card then card(event)
-        when *TURN_ENDS then remove
+        when *Events::TURN_END then remove
         end
       end
 

data/lib/samagotchi/bridge/sse_writer.rb

@@ -46,18 +46,18 @@ module Samagotchi
       # @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 frame_provider [#call, nil] -> {snapshot: {messages:,
+      #   current_turn:, queued:, event_seq:, ...}, session_state_snapshot:
+      #   {status:, message_count:, ...}}; called with the event log held, so
+      #   both describe the same event_seq (Bridge#snapshot_frame). 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,
+                     frame_provider: nil, join_with_snapshot: false, bridge: nil,
                      max_queue: DEFAULT_MAX_QUEUE,
                      heartbeat_interval: DEFAULT_HEARTBEAT_INTERVAL)
         @engine = engine
@@ -65,8 +65,7 @@ module Samagotchi
         @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 } }
+        @frame_provider = frame_provider || -> { { snapshot: { event_seq: @engine.event_count }, session_state_snapshot: {} } }
         @join_with_snapshot = join_with_snapshot
         @bridge = bridge
         @max_queue = max_queue
@@ -78,8 +77,6 @@ module Samagotchi
         @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
@@ -99,16 +96,15 @@ module Samagotchi
       # 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
+            frame = @engine.synchronize_events do
               @handle = @engine.subscribe(observer: self)
               take_snapshot
             end
-            write_snapshot_frame(io, :snapshot, snapshot)
+            write_snapshot_frame(io, :snapshot, frame)
           else
             # (1) subscribe the live queue FIRST.
             @handle = @engine.subscribe(observer: self)
@@ -122,7 +118,6 @@ module Samagotchi
         rescue Errno::EPIPE, Errno::ECONNRESET, IOError
           # Client hung up; nothing to do.
         ensure
-          @serving = false
           @engine.unsubscribe(handle: @handle) if @handle
         end
       end
@@ -222,23 +217,22 @@ module Samagotchi
         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.
+      # With the event log held: the snapshot frame's content (the snapshot
+      # and the session state, both as of one event_seq), and the high-water
+      # mark moved to that 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))
+        frame = @frame_provider.call
+        seq = frame[:snapshot][:event_seq].to_i
+        @high_water = seq
+        id = EventId.format(seq, @epoch)
+        { snapshot: frame[:snapshot].merge(event_id: id),
+          session_state_snapshot: frame[:session_state_snapshot].merge(event_seq: seq, event_id: id) }
       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 }
+      def write_snapshot_frame(io, type, frame)
+        write_frame(io, seq: frame[:snapshot][:event_seq], data: { type: type, **frame })
       end
     end
   end

data/lib/samagotchi/bridge/turn_accumulator.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../events"
 require_relative "../kernel_loop"
 require_relative "../steer"
 require_relative "turn_notice"
@@ -15,12 +16,15 @@ module Samagotchi
     # 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)
+      # @param clock [#call] monotonic seconds: a tool call's duration
+      def initialize(max_output_chars: KernelLoop::DEFAULT_MAX_TOOL_OUTPUT_CHARS,
+                     clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
         @max_output_chars = max_output_chars
+        @clock = clock
         @mutex = Mutex.new
         @turn = nil
+        # When each running tool call started, by [iteration, call_index].
+        @tool_started_at = {}
         @queued = []
         @merged_origins = []
         @recap = nil
@@ -36,7 +40,8 @@ module Samagotchi
       # @return [Hash, nil] a copy of the turn in progress: prompt, origin,
       #   continue, ordered parts (thinking / text / tool / input / steer /
       #   reminder / notice), pending_question and the last event_seq folded
-      #   in. A notice part holds the event of one of the turn's rows
+      #   in. A finished tool part keeps the live row's action and duration_ms
+      #   too. A notice part holds the event of one of the turn's rows
       #   (TurnNotice: a hook's notice, an empty-answer retry, a question and
       #   its answer), which a UI replays through its live handler.
       def current_turn
@@ -81,6 +86,80 @@ module Samagotchi
         messages
       end
 
+      # The turn in progress (#current_turn's shape, symbol keys) as the live
+      # events that would have drawn it, in order, as turn_events.js
+      # snapshotEvents replays it for the web (spec/shared/turn_snapshot.json
+      # pins both): a generation_chunk per thinking or text part (a
+      # generation_completed closes text before the next step's), a tool's
+      # tool_call_started and, once finished, its tool_call_completed (with
+      # the live activity: action, tool, params, status), a merged_input
+      # (the one synthetic type) per merged prompt, a steer-only
+      # pending_input_merged per steer, a reminder_injected, and a notice
+      # part's own event.
+      # @param started_at [String, nil] the turn's start, on turn_started
+      # @return [Array<Hash>] symbol keys and types; [] with no turn
+      def self.replay_events(turn, started_at: nil)
+        return [] unless turn
+
+        started = { type: :turn_started, prompt: turn[:prompt], origin: turn[:origin], continue: !!turn[:continue] }
+        started[:started_at] = started_at if started_at
+        events = [with_images(started, turn[:images])]
+        text_iteration = nil # a text part is open for this iteration
+        close_text = lambda do
+          events << { type: :generation_completed } unless text_iteration.nil?
+          text_iteration = nil
+        end
+        Array(turn[:parts]).each do |part|
+          case part[:kind]
+          when "thinking" then events << { type: :generation_chunk, text: "", thinking: part[:text], iteration: part[:iteration] }
+          when "text"
+            close_text.call if !text_iteration.nil? && text_iteration != part[:iteration]
+            text_iteration = part[:iteration]
+            events << { type: :generation_chunk, text: part[:text], thinking: "", iteration: part[:iteration] }
+          when "tool"
+            close_text.call
+            events.concat(tool_replay_events(part))
+          when "input"
+            close_text.call
+            events << { type: :merged_input, content: part[:text], origins: part[:origins] || [] }
+          when "reminder"
+            close_text.call
+            events << { type: :reminder_injected, reminders: part[:reminders] || [] }
+          when "notice"
+            close_text.call
+            notice = part[:event]
+            events << notice.merge(type: notice[:type].to_sym) if notice.is_a?(Hash) && notice[:type]
+          when "steer"
+            close_text.call
+            events << { type: :pending_input_merged, count: 0, content: nil, steers: [{ source: part[:source], text: part[:text] }] }
+          end
+        end
+        events
+      end
+
+      def self.tool_replay_events(part)
+        call = { iteration: part[:iteration], call_index: part[:call_index], tool: part[:tool] }
+        call[:label] = part[:label] if part[:label]
+        title = part[:title] ? { title: part[:title] } : {}
+        events = [{ type: :tool_call_started, **call, params: part[:params], **title }]
+        return events if part[:status] == "running"
+
+        activity = { tool: part[:tool], status: part[:status], params: part[:params], **title }
+        activity[:action] = part[:action] if part[:action]
+        completed = { type: :tool_call_completed, **call, output: part[:output], output_truncated: !!part[:output_truncated],
+                      activity: activity }
+        completed[:duration_ms] = part[:duration_ms] unless part[:duration_ms].nil?
+        completed[:diff] = part[:diff] if part[:diff]
+        events << with_images(completed, part[:images])
+      end
+      private_class_method :tool_replay_events
+
+      # +event+ with images: when there are any.
+      def self.with_images(event, images)
+        Array(images).empty? ? event : event.merge(images: images)
+      end
+      private_class_method :with_images
+
       # @return [String, nil] the last idle recap, until a turn makes it stale
       def recap
         @mutex.synchronize { @recap }
@@ -119,6 +198,7 @@ module Samagotchi
           dequeue([event[:origin]])
           @turn = { prompt: event[:prompt], origin: event[:origin], continue: !!event[:continue],
                     parts: [], pending_question: nil }
+          @tool_started_at = {}
           @turn[:images] = event[:images] if event[:images]
         when :input_merged
           @merged_origins = Array(event[:origins])
@@ -127,7 +207,7 @@ module Samagotchi
         return unless @turn
 
         fold_turn_event(event)
-        if TERMINAL_EVENTS.include?(type)
+        if Events::TURN_END.include?(type)
           @turn = nil
           @merged_origins = []
         else
@@ -152,6 +232,7 @@ module Samagotchi
           part[:label] = event[:label] if event[:label]
           part[:title] = event[:title] if event[:title]
           parts << part
+          @tool_started_at[[event[:iteration], event[:call_index]]] = @clock.call
         when :tool_call_completed
           tool = parts.reverse_each.find do |part|
             part[:kind] == "tool" && part[:iteration] == event[:iteration] && part[:call_index] == event[:call_index]
@@ -165,6 +246,12 @@ module Samagotchi
           tool[:output_truncated] = capped || !!event[:output_truncated]
           tool[:images] = event[:images] if event[:images]
           tool[:diff] = event[:diff] if event[:diff]
+          action = event.dig(:activity, :action)
+          tool[:action] = action.to_s if action
+          # As the live row times it (EventRenderer): from tool_call_started,
+          # less an approval wait.
+          started_at = @tool_started_at.delete([event[:iteration], event[:call_index]])
+          tool[:duration_ms] = [((@clock.call - started_at) * 1000) - event[:waited_ms].to_f, 0].max.round if started_at
         when :pending_input_merged
           # A steer-only merge (count 0) has no user part: the origins stay
           # for the user lines' own merge.

data/lib/samagotchi/bridge.rb

@@ -51,7 +51,6 @@ module Samagotchi
     REQUEST_GRACE_SECONDS = 1.0
     # The largest request body read (images travel as refs, never bytes).
     MAX_BODY_BYTES = 1_000_000
-    MAX_TURN_IMAGES = 20
     # A request's deadline (see #handle_post_turn) that isn't epoch seconds.
     BAD_DEADLINE = [{ "Allow" => "POST" }, 400, { error: "bad_deadline", detail: "deadline must be epoch seconds" }].freeze
 
@@ -227,6 +226,18 @@ module Samagotchi
       end
     end
 
+    # The snapshot and the session state (status, pending question, ...) as
+    # one step of the event log, both as of the same event_seq: what a
+    # snapshot or reset frame (SSEWriter) and GET snapshot carry.
+    # @return [Hash] {snapshot:, session_state_snapshot:}
+    def snapshot_frame
+      @engine.synchronize_events do
+        snap = snapshot
+        state = @engine.session_state_snapshot.merge(event_seq: snap[:event_seq], event_id: snap[:event_id])
+        { snapshot: snap, session_state_snapshot: state }
+      end
+    end
+
     private
 
     # The Engine's commands: the built-ins and its plugins'.
@@ -320,7 +331,7 @@ module Samagotchi
                                     client_id: stream_client_id(request[:query]))
           break # SSE owns the connection until the client disconnects.
         else
-          payload, status, body = send(route.first, route.last, request[:body])
+          payload, status, body = dispatch(route.first, route.last, request[:body])
           write_json(io, status, payload, body)
         end
 
@@ -356,8 +367,7 @@ module Samagotchi
         session_id: @session_id,
         last_event_id: last_event_id,
         epoch: @epoch,
-        snapshot_provider: -> { @engine.session_state_snapshot },
-        turn_snapshot_provider: -> { self.snapshot },
+        frame_provider: -> { snapshot_frame },
         # A reconnect (with a cursor) replays; only a fresh join snapshots.
         join_with_snapshot: snapshot && last_event_id.nil?,
         bridge: self,
@@ -430,28 +440,33 @@ module Samagotchi
       [handler, m[1]]
     end
 
+    # Every route but the stream: only this bridge's own session (see
+    # #own_session?), and a handler that raises answers 500 bridge_error,
+    # logged (the connection thread doesn't report).
+    # @return [Array(Hash, Integer, Hash)] headers, status, body
+    def dispatch(handler, session_id, body)
+      return [{}, 404, { error: "unknown_session" }] unless own_session?(session_id)
+
+      send(handler, session_id, body)
+    rescue StandardError => e
+      Log.exception(:bridge, "handler_failed", e)
+      [{}, 500, { error: "bridge_error", detail: e.message }]
+    end
+
     # /recap in an attached TUI: the saved recap, and a new one asked for at
     # once (it arrives as :recap_ready). Answers mid-turn too.
     # 200 {enabled:, saved:, request:, min_user_turns:}. Returns [headers, status, body].
     def handle_recap(session_id, _body = nil)
-      return [{}, 404, { error: "unknown_session" }] unless own_session?(session_id)
-
       recap = @engine.recap
       return [{}, 200, { enabled: false }] unless recap
 
       saved = @engine.saved_recap
       [{}, 200, { enabled: true, saved: saved, request: @engine.request_recap.to_s, min_user_turns: recap.min_user_turns }]
-    rescue StandardError => e
-      [{}, 500, { error: "bridge_error", detail: e.message }]
     end
 
     # Cancel the active turn on this session's engine, if any.
     # Returns [headers, status, body].
     def handle_cancel(session_id, body)
-      unless own_session?(session_id)
-        return [{}, 404, { error: "unknown_session" }]
-      end
-
       # Optional reason from JSON body
       reason = :manual
       if body && !body.strip.empty?
@@ -468,31 +483,19 @@ module Samagotchi
       else
         [{}, 409, { error: "not_running", detail: "no active turn to cancel", session_id: @session_id }]
       end
-    rescue StandardError => e
-      [{}, 500, { error: "bridge_error", detail: e.message }]
     end
 
     # Answer the pending question. A past +deadline+ (see #handle_post_turn):
     # 408 deadline_passed, and the question stays open. An answer takes no
     # event hold, so it is checked right before it is recorded.
     def handle_answer(session_id, body)
-      unless own_session?(session_id)
-        return [{}, 404, { error: "unknown_session" }]
-      end
       parsed = parse_json(body)
       unless parsed.is_a?(Hash)
         return [{ "Allow" => "POST" }, 400, { error: "invalid_json" }]
       end
-      qid = fetched(parsed, "id") || fetched(parsed, "question_id")
-      selected = fetched(parsed, "selected") || fetched(parsed, "selection")
-      freeform = fetched(parsed, "freeform") || fetched(parsed, "other")
-      # Support nested answer
-      if parsed["answer"].is_a?(Hash)
-        ans = parsed["answer"]
-        qid ||= fetched(ans, "id")
-        selected ||= fetched(ans, "selected")
-        freeform ||= fetched(ans, "freeform")
-      end
+      qid = fetched(parsed, "id")
+      selected = fetched(parsed, "selected")
+      freeform = fetched(parsed, "freeform")
       if qid.to_s.strip.empty?
         return [{ "Allow" => "POST" }, 400, { error: "missing_fields", detail: "id required" }]
       end
@@ -508,8 +511,6 @@ module Samagotchi
         [{}, 409, { error: "question_not_pending", detail: e.message }]
       rescue ArgumentError => e
         [{}, 400, { error: "invalid_answer", detail: e.message }]
-      rescue StandardError => e
-        [{}, 500, { error: "bridge_error", detail: e.message }]
       end
     end
 
@@ -520,8 +521,6 @@ module Samagotchi
     # +deadline+ (dismissing an approval denies it): 408, as for an answer.
     # Returns [headers, status, body].
     def handle_dismiss_question(session_id, body)
-      return [{}, 404, { error: "unknown_session" }] unless own_session?(session_id)
-
       parsed = parse_json(body)
       return [{ "Allow" => "POST" }, 400, { error: "invalid_json" }] unless parsed.is_a?(Hash)
 
@@ -536,8 +535,6 @@ module Samagotchi
       return [{}, 409, { error: "question_not_pending", detail: "no pending question #{qid}" }] unless dismissed
 
       [{}, 200, { status: "dismissed", id: qid, session_id: @session_id }]
-    rescue StandardError => e
-      [{}, 500, { error: "bridge_error", detail: e.message }]
     end
 
     # Queue a session command (/model, /models, !rollback, !cmd, /continue)
@@ -550,7 +547,6 @@ module Samagotchi
     # read-only ones (/models) too: its client said it didn't run.
     # Returns [headers, status, body].
     def handle_command(session_id, body)
-      return [{}, 404, { error: "unknown_session" }] unless own_session?(session_id)
       return [{}, 501, { error: "commands_unavailable" }] unless @on_command
 
       parsed = parse_json(body)
@@ -584,8 +580,6 @@ module Samagotchi
       return deadline_passed("command") unless queued
 
       [{}, 202, { status: "accepted", command_id: command[:command_id], session_id: @session_id }]
-    rescue StandardError => e
-      [{}, 500, { error: "bridge_error", detail: e.message }]
     end
 
     # A client asks the worker to exit now (`/exit` in the attached TUI). The
@@ -594,7 +588,6 @@ module Samagotchi
     # 200 {status: "exiting", discard?: the session is empty and goes}, or 409 {status: "held", reason:} naming what
     # keeps it up. Returns [headers, status, body].
     def handle_exit_request(session_id, body)
-      return [{}, 404, { error: "unknown_session" }] unless own_session?(session_id)
       return [{}, 501, { error: "exit_unavailable" }] unless @on_exit_request
 
       parsed = parse_json(body)
@@ -610,11 +603,12 @@ module Samagotchi
       end
 
       [{}, 409, { status: "held", reason: reason.to_s, session_id: @session_id }]
-    rescue StandardError => e
-      [{}, 500, { error: "bridge_error", detail: e.message }]
     end
 
-    # Create a turn via file IPC (fire-and-forget). Returns [headers, status, body].
+    # Queue a turn for this session through its file IPC (the worker polls
+    # its input dir). Returns [headers, status, body]. Only this bridge's own
+    # session: another id, in the path or the body, is refused as on every
+    # other route.
     #
     # A +deadline+ (wall-clock epoch seconds; the client shares this machine's
     # clock) is when the client stops waiting (BridgeClient#post_turn): a turn
@@ -638,56 +632,40 @@ module Samagotchi
         return [{ "Allow" => "POST" }, 400,
                 { error: "missing_fields", detail: "session_id and prompt are required" }]
       end
-      # Checked before the id names a folder: "../x" would write outside the
-      # sessions dir (turn_images and enqueue_turn build paths from it).
-      return [{}, 400, { error: "invalid_session_id" }] unless Session.valid_id?(sid)
+      return [{}, 404, { error: "unknown_session" }] unless own_session?(sid)
 
-      images = turn_images(sid, fetched(parsed, "images"))
+      images = ImageStore.check_refs(session_dir, fetched(parsed, "images"))
       return [{}, 400, { error: "bad_images", detail: images }] if images.is_a?(String)
 
       deadline = fetched(parsed, "deadline")
       return BAD_DEADLINE unless deadline_valid?(deadline)
 
       enqueued_id = SecureRandom.uuid
-      enqueued =
-        if own_session?(sid)
-          # Write and announce with the event log held: the worker can't
-          # emit this turn's :turn_started (or merge it mid-turn) before
-          # :turn_enqueued, and a failed write announces nothing.
-          @engine.synchronize_events do
-            next :expired if expired?("turn_expired", deadline, sid: sid, client_id: client_id)
-
-            enqueue_turn(session_id: sid, prompt: prompt, client_id: client_id, enqueued_id: enqueued_id,
-                         no_interrupt: no_interrupt, images: images).tap do |ok|
-              next unless ok
-
-              enqueued_event = { type: :turn_enqueued, enqueued_id: enqueued_id, client_id: client_id, prompt: prompt.to_s }
-              enqueued_event[:images] = images unless images.empty?
-              @engine.announce(enqueued_event)
-              @on_input&.call
-            end
-          end
-        elsif expired?("turn_expired", deadline, sid: sid, client_id: client_id)
-          :expired
-        else
-          enqueue_turn(session_id: sid, prompt: prompt, client_id: client_id, enqueued_id: enqueued_id,
-                       no_interrupt: no_interrupt, images: images)
+      # Write and announce with the event log held: the worker can't emit
+      # this turn's :turn_started (or merge it mid-turn) before
+      # :turn_enqueued, and a failed write announces nothing.
+      enqueued = @engine.synchronize_events do
+        next :expired if expired?("turn_expired", deadline, sid: sid, client_id: client_id)
+
+        enqueue_turn(prompt: prompt, client_id: client_id, enqueued_id: enqueued_id,
+                     no_interrupt: no_interrupt, images: images).tap do |ok|
+          next unless ok
+
+          enqueued_event = { type: :turn_enqueued, enqueued_id: enqueued_id, client_id: client_id, prompt: prompt.to_s }
+          enqueued_event[:images] = images unless images.empty?
+          @engine.announce(enqueued_event)
+          @on_input&.call
         end
+      end
       return deadline_passed("turn") if enqueued == :expired
       return [{}, 500, { error: "enqueue_failed", detail: "could not write turn input" }] unless enqueued
 
-      [{}, 202, { status: "accepted", enqueued_id: enqueued_id, session_id: sid }]
-    rescue StandardError => e
-      [{}, 500, { error: "bridge_error", detail: e.message }]
+      [{}, 202, { status: "accepted", enqueued_id: enqueued_id, session_id: @session_id }]
     end
 
     # Read-only snapshot surface. AC #4: too-old reconnects re-derive state
     # from here.
     def handle_state(session_id, _body = nil)
-      unless own_session?(session_id)
-        return [{}, 404, { error: "unknown_session" }]
-      end
-
       state = @engine.session_state_snapshot
       [{}, 200, { session_id: @session_id, session_state_snapshot: state.merge(event_id: event_id(state[:event_seq])) }]
     end
@@ -696,8 +674,6 @@ module Samagotchi
     # profile asked from the server when no turn has reported them yet (so,
     # unlike /state, it may wait on one short /props GET).
     def handle_stats(session_id, _body = nil)
-      return [{}, 404, { error: "unknown_session" }] unless own_session?(session_id)
-
       [{}, 200, { session_id: @session_id, metrics: @engine.stats_snapshot }]
     end
 
@@ -706,14 +682,7 @@ module Samagotchi
     # streams from the snapshot's event_seq, and the ring replays what came
     # after (or the stream resets). Returns [headers, status, body].
     def handle_snapshot(session_id, _body = nil)
-      return [{}, 404, { error: "unknown_session" }] unless own_session?(session_id)
-
-      body = @engine.synchronize_events do
-        snap = snapshot
-        state = @engine.session_state_snapshot.merge(event_seq: snap[:event_seq], event_id: snap[:event_id])
-        { snapshot: snap, session_state_snapshot: state }
-      end
-      [{}, 200, body]
+      [{}, 200, snapshot_frame]
     end
 
     # The stream cursor for +seq+ in this worker.
@@ -722,10 +691,9 @@ module Samagotchi
     end
 
     # A per-session bridge only ever owns one Engine (for @session_id). The
-    # stream and state surfaces must serve that session and nothing else —
-    # serving a different id's data (or closing with no response) would be a
-    # cross-session leak. POST/turn enqueue stays lenient (fire-and-forget to
-    # another worker's input dir) through SessionInbox.write_input.
+    # stream, state and turn surfaces must serve that session and nothing
+    # else — serving a different id's data (or writing into another
+    # session's input dir) would be a cross-session leak.
     def own_session?(session_id)
       session_id.to_s == @session_id.to_s
     end
@@ -751,34 +719,13 @@ module Samagotchi
       [{}, 408, { error: "deadline_passed", detail: "the #{what} arrived after its client stopped waiting; not run" }]
     end
 
-    # Write a turn into the target session's input dir, reusing the file IPC
-    # the worker polls. Never calls run_turn across the boundary.
-    def enqueue_turn(session_id:, prompt:, client_id: nil, enqueued_id: nil, no_interrupt: false, images: [])
-      session_dir = Session.session_dir(session_id, state_dir: @state_dir || Session.default_state_dir)
+    # Write a turn into this session's input dir, reusing the file IPC the
+    # worker polls. Never calls run_turn across the boundary.
+    def enqueue_turn(prompt:, client_id: nil, enqueued_id: nil, no_interrupt: false, images: [])
       SessionInbox.write_input(session_dir, prompt: prompt, client_id: client_id, enqueued_id: enqueued_id,
                                             no_interrupt: no_interrupt, images: images)
     end
 
-    # A turn's images as [{file:, name:}], or a String saying what's wrong.
-    # Only refs to files already in that session's images/ pass (a web
-    # upload): never a path, so no client can make the worker read a file.
-    def turn_images(session_id, raw)
-      return [] if raw.nil?
-      return "images must be a list" unless raw.is_a?(Array)
-      return "at most #{MAX_TURN_IMAGES} images" if raw.size > MAX_TURN_IMAGES
-
-      session_dir = Session.session_dir(session_id, state_dir: @state_dir || Session.default_state_dir)
-      raw.map do |image|
-        return "each image must be {file:, name:}" unless image.is_a?(Hash)
-
-        ref = ImageStore.symbolize(image)
-        return "images are refs to uploaded files, not paths" if ref.key?(:path)
-        return "unknown image #{ref[:file].to_s[0, 80]}" unless ImageStore.valid_ref?(session_dir, ref)
-
-        { file: ref[:file].to_s, name: File.basename(ref[:name].to_s)[0, 120] }
-      end
-    end
-
     # ── HTTP plumbing ────────────────────────────────────────────────────────
 
     def read_request(io)