samagotchi 0.103.0 → 0.104.0

data/lib/samagotchi/web/session_access_routes.rb

@@ -10,6 +10,9 @@ require_relative "../context_command"
 require_relative "../send_command"
 require_relative "../launch_mode"
 require_relative "../model_profile"
+require_relative "../client_id"
+require_relative "../children_status"
+require_relative "../session_metrics"
 
 module Samagotchi
   module Web
@@ -234,7 +237,9 @@ module Samagotchi
       # waited for up to +wait+ seconds (WAKE_MAX_WAIT, also the most). 200
       # {session_id, woke, worker: {epoch, started_at, version, features},
       # model_name, default_model (this machine's config, for the TUI's
-      # status row), parent_strategy, installed (the newest chi here)}; 409
+      # status row), parent_strategy, installed (the newest chi here)}. A
+      # worker still leaving is waited for first (Local#wake: its recap's
+      # timeout and a margin, on top of +wait+); 409
       # owned_by_tui (a chi REPL has it), 409 scratch (a leftover scratch
       # session, as chi --attach here says); 504 worker_timeout (its Bridge
       # didn't come in time); 404 not_found.
@@ -262,13 +267,20 @@ module Samagotchi
 
       # GET /api/sessions/:id/worker: the session's worker now, never
       # started (SessionAccess::Local#worker): a remote attach's
-      # rediscovery and its features after a restart. 200 {session_id,
-      # live, stopped, owner: worker|tui|null, worker: {epoch, started_at,
-      # version, features}|null, parent_strategy}; 404 not_found.
+      # rediscovery and its features after a restart, and before its wake
+      # whether the worker is leaving (its recap on leave: the wake waits
+      # for it, so the client says so). 200 {session_id, live, stopped,
+      # owner: worker|tui|null, leaving, leave_seconds (its leave's budget
+      # left, nil unless leaving), worker: {epoch, started_at, version,
+      # features}|null, default_model (this machine's config, as the
+      # wake's), parent_strategy}; 404 not_found.
       def handle_worker(_req, id)
         state = session_access.worker(id)
+        leaving = state.leaving?
         json_response(200, { session_id: id, live: state.live?, stopped: state.stopped, owner: state.owner&.kind,
+                             leaving: leaving, leave_seconds: (state.owner.leave_left.round(1) if leaving),
                              worker: state.sidecar && worker_json(state.sidecar),
+                             default_model: ModelProfile.default_model_name,
                              parent_strategy: strategy_json(session_access.parent_strategy(id)) })
       end
 
@@ -278,6 +290,110 @@ module Samagotchi
         { epoch: sidecar.epoch, started_at: sidecar.started_at, version: sidecar.version, features: sidecar.features }
       end
 
+      # POST /api/sessions/:id/exit {client_id, delete}: a remote attached
+      # TUI's /exit (and the worker's half of /exit --delete and /archive),
+      # relayed to the live worker's exit (BridgeClient#request_exit; never
+      # wakes one). client_id is passed on only when it is an attached TUI's
+      # (tui:…): any other is dropped, and then every stream counts as a UI,
+      # which only keeps the worker up. 200 the Bridge's {status: exiting,
+      # session_id, discard}; 409 held with its {status, reason, tasks,
+      # hint}; 503 not_live, 501 not_supported (an older worker), 504
+      # worker_timeout.
+      def handle_exit(req, id)
+        body = body_hash(req) or return refusal(400, "invalid_json", "invalid JSON body")
+        @session_class.load(id, state_dir: default_state_dir)
+        client_id = body["client_id"] if body["client_id"].is_a?(String) && body["client_id"].start_with?(ClientId::TUI_PREFIX)
+        delete = body["delete"] == true
+
+        request = ->(client) { client.request_exit(client_id: client_id, delete: delete) }
+        with_message(relay(id, bridge_client(id), request, what: "the worker was not asked to exit", cant: "exit from here") do |reply|
+          case reply.status
+          when 200 then json_response(200, reply.json || { status: "exiting", session_id: id })
+          when 409
+            held = reply.json || {}
+            words = "the session's worker stays up (#{held["reason"] || "held"})"
+            json_response(409, held.merge("error" => "held", "detail" => words, "message" => words, "session_id" => id))
+          end
+        end)
+      end
+
+      # POST /api/sessions/:id/recap: the saved recap, and a new one asked for
+      # (BridgeClient#request_recap; it arrives on the stream as
+      # :recap_ready). 200 the Bridge's {enabled, saved, request,
+      # min_user_turns, session_off}; 503, 501, 504 as every relay.
+      def handle_recap(_req, id)
+        @session_class.load(id, state_dir: default_state_dir)
+        request = lambda(&:request_recap)
+        with_message(relay(id, bridge_client(id), request, what: "no recap was read", cant: "recap") do |reply|
+          json_response(200, reply.json || {}) if reply.status == 200
+        end)
+      end
+
+      # GET /api/sessions/:id/stats: the live worker's metrics for /stats
+      # (its stats route; a worker from before it answers only its state's
+      # metrics). 200 {session_id, metrics}; 503 not_live, 504
+      # worker_timeout, 502 bridge_error.
+      def handle_stats(_req, id)
+        @session_class.load(id, state_dir: default_state_dir)
+        client = bridge_client(id) or return with_message(not_live(id))
+
+        status, json = client.get("stats")
+        metrics = json["metrics"] if status == 200 && json.is_a?(Hash)
+        if status == 404 && !(json.is_a?(Hash) && json["error"] == "unknown_session")
+          status, json = client.get("state")
+          metrics = json.dig("session_state_snapshot", "metrics") if status == 200 && json.is_a?(Hash)
+        end
+        return json_response(200, { session_id: id, metrics: metrics }) if status == 200
+        return with_message(worker_timeout("the stats were not read")) if status.nil?
+        return with_message(not_live(id)) if status == 404
+
+        with_message(error_response(502, "bridge_error", "the stats were not read: the session's worker answered #{status}"))
+      end
+
+      # GET /api/sessions/:id/children/counts: the session's delegates'
+      # counts (ChildrenStatus.counts, from their files here), a remote
+      # TUI's status row segment. 200 {running, waiting, unreported}; 404.
+      def handle_children_counts(_req, id)
+        @session_class.load(id, state_dir: default_state_dir)
+        json_response(200, ChildrenStatus.counts(id, state_dir: default_state_dir).to_h)
+      end
+
+      # A turn id as a session's prompts carry it (a uuid; any word-ish id).
+      TURN_ID = /\A[\w.:-]{1,128}\z/
+
+      # GET /api/sessions/:id/turns/:turn_id/records: a turn's saved tool
+      # records and turn record (SessionMetrics, from analytics.json here),
+      # as saved: what a remote TUI's join draws the steps' durations and a
+      # failed turn's line from. 200 {tool_records: […], turn_record: {…} |
+      # null}; 400 invalid_turn_id; 404 not_found.
+      def handle_turn_records(_req, id, turn_id)
+        return refusal(400, "invalid_turn_id", "not a turn id: #{turn_id.to_s[0, 80]}") unless TURN_ID.match?(turn_id)
+
+        @session_class.load(id, state_dir: default_state_dir)
+        dir = Session.session_dir(id, state_dir: default_state_dir)
+        json_response(200, { tool_records: SessionMetrics.saved_tool_records(dir, turn_id),
+                             turn_record: SessionMetrics.saved_turn_record(dir, turn_id) })
+      end
+
+      # {error, detail, message}: the words a remote client raises with.
+      def refusal(status, code, words, **fields)
+        json_response(status, { error: code, detail: words, message: words, **fields })
+      end
+
+      # A relay's error answer (#relay's {error, detail}) with its message
+      # too, as a remote attach's routes answer every refusal.
+      def with_message(response)
+        status, _headers, chunks = response
+        return response if status < 400
+
+        body = JSON.parse(chunks.join)
+        return response unless body.is_a?(Hash) && body["error"] && !body.key?("message")
+
+        json_response(status, body.merge("message" => body["detail"]))
+      rescue JSON::ParserError
+        response
+      end
+
       # POST /api/sessions/:id/notes {text, source}: a context note for the
       # session (NoteDelivery, as chi note; source: where it came from,
       # "cli" by default, never "broadcast"). 200 {status: "queued" (a

data/lib/samagotchi/worker.rb

@@ -122,9 +122,14 @@ module Samagotchi
     #   trapped signals (SessionManager.run_session_loop); none by default
     # @param signal_grace [Array(Numeric, Numeric, Numeric)] the grace, the
     #   short grace and the hard exit's delay (specs shorten them)
+    # @param owner_lock [OwnerLock, nil] the session's, which this process
+    #   holds (SessionManager.run_session_loop): marked leaving as the Bridge
+    #   stops, so an attach waits for the recap on leave (OwnerLock.await_release)
     def initialize(session_id:, state_dir:, session_dir:, idle_exit_minutes: nil, poll_interval: nil,
-                   signals: WorkerSignals::NONE, signal_grace: [SIGNAL_GRACE, SIGNAL_SHORT_GRACE, SIGNAL_HARD_EXIT])
+                   signals: WorkerSignals::NONE, signal_grace: [SIGNAL_GRACE, SIGNAL_SHORT_GRACE, SIGNAL_HARD_EXIT],
+                   owner_lock: nil)
       @session_id = session_id
+      @owner_lock = owner_lock
       @state_dir = state_dir
       @session_dir = session_dir
       @idle_exit_minutes = idle_exit_minutes
@@ -1245,7 +1250,8 @@ module Samagotchi
           next false unless @idle_exit.due?
 
           @bridge&.close_intake
-          @engine.stop_idle
+          # Not joined: a recap tick's emit waits for the event log held here.
+          @engine.stop_idle(join: false)
           log_idle_exit
           true
         end
@@ -1255,14 +1261,28 @@ module Samagotchi
     # The Bridge stops once the block (which closed its intake with the
     # event log held) answers true, outside the log: Bridge#stop waits for
     # the requests it is answering, and one waiting on the log would hold
-    # it for the whole grace before being killed.
+    # it for the whole grace before being killed. The owner lock says it is
+    # leaving first, so a client that finds no Bridge from here on waits
+    # for the lock (OwnerLock.await_release) instead of giving up.
     # @return [Boolean] what the block answered
     def stop_bridge_after
       leaving = yield
-      @bridge&.stop if leaving
+      if leaving
+        mark_leaving
+        @bridge&.stop
+      end
       leaving
     end
 
+    # How long the lock stays held after the Bridge: the recap on leave's
+    # timeout (#left), none for a restart (#left writes none). A delete
+    # writes none either, but the bound only has to be an upper one.
+    def mark_leaving
+      @owner_lock&.mark_leaving(wait: @exit_restart ? 0 : @engine.recap_timeout.to_f)
+    rescue StandardError => e
+      Log.warn(:worker, "mark_leaving_failed", error: e.class.name, msg: e.message)
+    end
+
     # Bridge POST /exit, on a Bridge thread with the event log held.
     # +delete+: the session is deleted after (/exit --delete), so no recap.
     # +restart+: a new worker takes over (on the newest chi installed), so
@@ -1313,7 +1333,8 @@ module Samagotchi
           end
 
           @bridge&.close_intake
-          @engine.stop_idle
+          # Not joined: a recap tick's emit waits for the event log held here.
+          @engine.stop_idle(join: false)
           Log.info(:worker, @exit_restart ? "restart_requested" : "exit_requested", by: @exit_requested_by || "a client")
           true
         end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: samagotchi
 version: !ruby/object:Gem::Version
-  version: 0.103.0
+  version: 0.104.0
 platform: ruby
 authors:
 - Dmitry Dedov
@@ -160,6 +160,7 @@ files:
 - docs/internals/llm-context-bench.md
 - docs/internals/llm-context-forget.md
 - docs/internals/llm-context-live.md
+- docs/internals/participants.md
 - docs/internals/prompt-caching.md
 - docs/internals/remote-sessions.md
 - docs/internals/tool-guardrails.md
@@ -462,6 +463,7 @@ files:
 - lib/samagotchi/owner_lock.rb
 - lib/samagotchi/parent_answers_command.rb
 - lib/samagotchi/parent_report.rb
+- lib/samagotchi/participants.rb
 - lib/samagotchi/paths.rb
 - lib/samagotchi/peer_sources.rb
 - lib/samagotchi/pending_input_queue.rb
@@ -506,6 +508,7 @@ files:
 - lib/samagotchi/relay_watcher.rb
 - lib/samagotchi/reminder_queue.rb
 - lib/samagotchi/reminder_store.rb
+- lib/samagotchi/remote_attach_command.rb
 - lib/samagotchi/remote_command.rb
 - lib/samagotchi/remotes.rb
 - lib/samagotchi/reply_wait.rb
@@ -549,6 +552,7 @@ files:
 - lib/samagotchi/session_setup.rb
 - lib/samagotchi/sessions_command.rb
 - lib/samagotchi/setting_explained.rb
+- lib/samagotchi/share_command.rb
 - lib/samagotchi/side_usage.rb
 - lib/samagotchi/steer.rb
 - lib/samagotchi/steer_cut.rb
@@ -576,6 +580,8 @@ files:
 - lib/samagotchi/terminal_ui/question_slot.rb
 - lib/samagotchi/terminal_ui/reline_history_hook.rb
 - lib/samagotchi/terminal_ui/reline_seam.rb
+- lib/samagotchi/terminal_ui/remote_connector.rb
+- lib/samagotchi/terminal_ui/remote_link.rb
 - lib/samagotchi/terminal_ui/repl_input.rb
 - lib/samagotchi/terminal_ui/screen.rb
 - lib/samagotchi/terminal_ui/status_row.rb
@@ -675,9 +681,12 @@ files:
 - lib/samagotchi/web/app.rb
 - lib/samagotchi/web/capabilities.rb
 - lib/samagotchi/web/editor.rb
+- lib/samagotchi/web/grants.rb
 - lib/samagotchi/web/info_probe.rb
 - lib/samagotchi/web/lan.rb
 - lib/samagotchi/web/markdown_renderer.rb
+- lib/samagotchi/web/participant_access.rb
+- lib/samagotchi/web/principal.rb
 - lib/samagotchi/web/public/activity.js
 - lib/samagotchi/web/public/annotate_actions.js
 - lib/samagotchi/web/public/annotate_bar.js