samagotchi 0.103.0 → 0.105.0

data/lib/samagotchi/session_access/contract.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../config"
+
 module Samagotchi
   module SessionAccess
     # Which session commands and flags run against another machine's
@@ -7,13 +9,16 @@ module Samagotchi
     # and which run on this machine only (refused under a remote, exit 2:
     # "chi <cmd> runs on this machine only: run it on <remote>"). The v1 scope is the remote-sessions plan's
     # D3: send, answer, note, a session's context (add, push, ls, show, rm)
-    # and sessions list/stop/restart/archive/unarchive/delete; the rest
+    # and sessions list/stop/restart/archive/unarchive/delete, and chi share
+    # (the shared-sessions plan's P2); the rest
     # stays local. bin/chi's subcommands that act on the machine, not on
-    # sessions, are MACHINE. The run flags (--attach, -p, --resume) are not
-    # subcommands and not in this table (remote attach is its own phase).
+    # sessions, are MACHINE. The run flags (chi --attach, -p, --resume: a
+    # session in this terminal, a remote attach there) are RUN's.
     #
     # spec/session_access_contract_spec.rb fails when a subcommand, one of
-    # its subcommands or one of a supported one's flags is in neither.
+    # its subcommands or one of a supported one's flags is in neither, or
+    # a run flag (RunOptions.switches) is in neither RUN list and isn't a
+    # config registry flag.
     module Contract
       SUPPORTED = :supported
       LOCAL_ONLY = :local_only
@@ -111,11 +116,44 @@ module Samagotchi
         "sessions clean" => LOCAL_ONLY,
         "sessions stats" => LOCAL_ONLY,
 
+        # Participants (docs/internals/participants.md): the remote's link,
+        # through its chi web's participants routes.
+        "share" => SUPPORTED,
+        "share --name" => SUPPORTED,
+        "share --agent" => SUPPORTED,
+        "share --expires" => SUPPORTED,
+        "share ls" => SUPPORTED,
+        "share ls --format" => SUPPORTED,
+        "share revoke" => SUPPORTED,
+        "share revoke --all" => SUPPORTED,
+
         "broadcast" => LOCAL_ONLY
       }.freeze
 
+      # bin/chi's run flags under a remote (chi --remote NAME --attach ID,
+      # RemoteAttachCommand): what a remote attach takes, and what runs
+      # this machine's REPL or reads this machine's files (P4-D2..D4). A
+      # config registry flag (--recap-base-url …) is this machine's
+      # config: LOCAL_ONLY without being listed.
+      RUN = {
+        SUPPORTED => %w[--attach --resume -p --prompt --shared --model --thinking --llm-context --llm-context-apply
+                        --llm-context-budget --toolkit --tool --no-tool --set --parent-answers --no-interrupt
+                        --no-default-input --dir --version -h --help],
+        LOCAL_ONLY => %w[--no-shared --non-interactive -v --verbose --append-system-prompt --memory --mute --profile
+                         --port --open --new-token --scope --web-markdown --no-web-markdown]
+      }.freeze
+      # A short run flag's name in a refusal.
+      RUN_WORDS = { "-v" => "--verbose" }.freeze
+
       module_function
 
+      # @param flag [String] a run flag as RunOptions.switches lists it
+      # @return [Symbol, nil] SUPPORTED or LOCAL_ONLY; nil: not a run flag
+      def run_status(flag)
+        RUN.each { |status, flags| return status if flags.include?(flag) }
+        LOCAL_ONLY if Config.cli_entries.any? { |entry| [entry.cli_flag, entry.cli_flag.sub("--", "--no-")].include?(flag) }
+      end
+
       # @param words [Array<String>] a command, maybe its subcommand, maybe
       #   a flag's long name: status("context", "add", "--cmd")
       # @return [Symbol, nil] SUPPORTED, LOCAL_ONLY, or nil when not listed

data/lib/samagotchi/session_access/dispatch.rb

@@ -21,10 +21,8 @@ module Samagotchi
       # bin/chi's own words besides its SUBCOMMANDS (a refusal names them).
       OWN_WORDS = %w[web scratch self].freeze
       HELP = %w[--version -h --help].freeze
-      # The run flags (not subcommands) a refusal names: remote attach is
-      # its own phase (P4).
-      RUN_FLAGS = { "--attach" => "--attach", "--resume" => "--resume", "-p" => "-p", "--prompt" => "-p",
-                    "--shared" => "--shared", "--no-shared" => "--no-shared" }.freeze
+      # --non-interactive's refusal: what runs one turn there instead.
+      ONE_TURN = "(%s send --new --dir D -m TEXT --wait runs one turn there)"
 
       # A usage error in the flag itself (--remote with no name, a bad one).
       class Usage < StandardError; end
@@ -54,6 +52,14 @@ module Samagotchi
 
       def remote? = !@remote.nil?
 
+      # Whether the arguments are run flags, no subcommand: a session in
+      # this terminal (bin/chi's RunOptions parse them; under a remote,
+      # RemoteAttachCommand runs them).
+      def run_flags?
+        command = @argv.first
+        command.nil? || command.start_with?("-")
+      end
+
       # Whether the arguments run here as they would without a remote: chi
       # remote, --version, --help.
       def here?
@@ -67,7 +73,8 @@ module Samagotchi
       def refusal
         words = local_words or return nil
 
-        "chi #{words} runs on this machine only: run it on #{@remote}"
+        line = "chi #{words} runs on this machine only: run it on #{@remote}"
+        words == "--non-interactive" ? "#{line} #{format(ONE_TURN, "chi --remote #{@remote}")}" : line
       end
 
       # The session command against the remote: refused (exit 2), or run
@@ -101,11 +108,11 @@ module Samagotchi
       private
 
       # The words that run here only: the command (and its subcommand, a
-      # flag) the Contract lists local_only, a machine command, or the run
-      # flags (a session in this terminal, attach). nil: supported.
+      # flag) the Contract lists local_only, a machine command, or a run
+      # flag Contract::RUN lists local_only. nil: supported.
       def local_words
         command = @argv.first
-        return run_words if command.nil? || command.start_with?("-")
+        return run_words if run_flags?
         return command if Contract::MACHINE.include?(command) || Contract.status(command).nil?
         return command if Contract.status(command) == Contract::LOCAL_ONLY
 
@@ -124,9 +131,21 @@ module Samagotchi
         @argv.drop(1).take_while { |arg| arg != "--" }.select { |arg| arg.start_with?("--") }.map { |arg| arg.split("=", 2).first }
       end
 
+      # The first local-only run flag, a value (-p TEXT, --model NAME)
+      # never read as one. An unknown flag is the parser's to refuse.
       def run_words
-        flag = @argv.take_while { |arg| arg != "--" }.map { |arg| arg.split("=", 2).first }.find { |arg| RUN_FLAGS.key?(arg) }
-        flag ? RUN_FLAGS[flag] : "(a session in this terminal)"
+        require_relative "../run_options"
+        values = RunOptions.value_switches
+        words = @argv.take_while { |arg| arg != "--" }
+        index = 0
+        while index < words.size
+          arg = words[index]
+          flag = arg.start_with?("--") ? arg.split("=", 2).first : arg[0, 2]
+          return Contract::RUN_WORDS.fetch(flag, flag) if arg.start_with?("-") && Contract.run_status(flag) == Contract::LOCAL_ONLY
+
+          index += values.include?(arg) ? 2 : 1
+        end
+        nil
       end
     end
   end

data/lib/samagotchi/session_access/local.rb

@@ -4,6 +4,7 @@ require_relative "../session"
 require_relative "../session_access"
 require_relative "../reply_wait"
 require_relative "../bridge_client"
+require_relative "../owner_lock"
 require_relative "../parent_report"
 require_relative "../note_delivery"
 require_relative "../image_store"
@@ -12,6 +13,10 @@ require_relative "../send_command/busy"
 require_relative "../chi_invocation"
 require_relative "../worker_sidecar"
 require_relative "../launch_mode"
+require_relative "../participants"
+require_relative "../config"
+require_relative "../web/grants"
+require_relative "../web/info_probe"
 
 module Samagotchi
   # Loaded on first use: SessionManager and its ~80 files only when a
@@ -69,7 +74,10 @@ module Samagotchi
 
       # The session's worker for an attach: the live one as is, else
       # resumed and waited for up to +wait+ seconds (chi --attach on this
-      # machine; chi web's POST …/wake for a remote one).
+      # machine; chi web's POST …/wake for a remote one). A worker still
+      # leaving (its Bridge closed, its recap on leave being written) is
+      # waited for first (OwnerLock.await_release: its recap's timeout and
+      # a margin), so the resume finds the session free.
       # @return [Woken] its sidecar nil when the Bridge didn't come in time
       # @raise [ArgumentError] no such session
       # @raise [Refused] code scratch: a leftover chi scratch session
@@ -81,6 +89,7 @@ module Samagotchi
         live = WorkerSidecar.live(session_dir(id), unlink: true)
         return Woken.new(woke: false, sidecar: live) if live
 
+        OwnerLock.await_release(session_dir(id))
         SessionManager.resume_session(id, **dir)
         found = BridgeClient.wait_for(id, session_dir: session_dir(id), timeout: wait)
         Woken.new(woke: true, sidecar: found && WorkerSidecar.read(session_dir(id)))
@@ -322,8 +331,50 @@ module Samagotchi
         end
       end
 
+      # --- participants (chi share)
+
+      # Remote's: through this machine's grants store, as chi web would.
+      # @return [Array<ParticipantView>]
+      def participants(id = nil)
+        grants.list(session_id: id).map { |grant| ParticipantView.from_h(grant.public_h(grants.now)) }
+      end
+
+      # The link names this machine's chi web: its LAN address when one
+      # runs on the LAN (web.port), else 127.0.0.1 (+lan+ false).
+      # @return [Invitation]
+      # @raise [ArgumentError] no such session
+      # @raise [BadRequest] a bad name, kind or ttl, an archived session
+      def invite(id, name:, kind:, ttl: nil)
+        issued = Participants.invite(grants, session_id: id, name: name, kind: kind, ttl: ttl, state_dir: state_dir!)
+        ip, port = local_web
+        Invitation.new(participant: ParticipantView.from_h(issued.grant.public_h(grants.now)), token: issued.token,
+                       link: "http://#{ip || "127.0.0.1"}:#{port}/?token=#{issued.token}#s=#{id}", lan: !ip.nil?)
+      rescue Web::Grants::Invalid => e
+        raise BadRequest.new(e.message, code: "invalid_participant")
+      end
+
+      # @return [Array<ParticipantView>] the ones it revoked
+      def revoke_participants(id = nil, participant: nil)
+        Participants.revoke(grants, session_id: id, id: participant, state_dir: state_dir!)
+                    .map { |grant| ParticipantView.from_h(grant.public_h(grants.now)) }
+      end
+
       private
 
+      def grants = @grants ||= Web::Grants.new(Web::Grants.path(state_dir: state_dir!))
+
+      # Web::Server::DEFAULT_PORT, without loading chi web.
+      WEB_PORT = 4567
+      LOCAL_PROBE_TIMEOUT = 1.0
+
+      # [LAN ip or nil, port] of this machine's chi web (GET /api/info).
+      def local_web
+        port = Config.get("web.port").to_s.to_i
+        port = WEB_PORT unless port.positive?
+        info = Web::InfoProbe.call("127.0.0.1", port, timeout: LOCAL_PROBE_TIMEOUT)
+        [info.is_a?(Hash) ? info["lan"] : nil, port]
+      end
+
       def dir = @state_dir ? { state_dir: @state_dir } : {}
       def state_dir! = @state_dir || Session.default_state_dir
       def session_dir(id) = Session.session_dir(id, state_dir: state_dir!)

data/lib/samagotchi/session_access/remote.rb

@@ -74,8 +74,8 @@ module Samagotchi
       # add checks the same).
       # @return [RemoteFailed, nil]
       def self.info_problem(entry, reply)
-        failure = auth_failure(entry, reply)
-        return RemoteFailed.new(failure) if failure
+        refused = access_error(entry, reply)
+        return refused if refused
         unless reply.status == 200 && reply.json.is_a?(Hash) && reply.json["app"] == "chi-web"
           return RemoteFailed.new("#{entry.label}: not chi web (GET /api/info answered #{reply.status})")
         end
@@ -91,20 +91,31 @@ module Samagotchi
           "update chi there (chi update)"
       end
 
-      # The words for a 401 or a 403 forbidden from +entry+'s chi web, nil
-      # for any other answer (chi remote add says the same).
-      def self.auth_failure(entry, reply)
+      # The errors any route of +entry+'s chi web can answer, each its one
+      # message: the token refused (401 unauthorized) or ended (401
+      # token_revoked / token_expired), the LAN IP only (403 forbidden), a
+      # participant's token on an owner's route (403 not_permitted) or over
+      # its limits (429 too_many_turns / cap_reached). nil for any other
+      # answer (chi remote add says the same).
+      # @return [RemoteFailed, nil]
+      def self.access_error(entry, reply)
+        error = reply.error
+        known = ACCESS_ERRORS.find { |klass| error == klass::CODE }
+        return known.new(entry.label) if known
+
         case reply.status
-        when 401 then "#{entry.label}: the token was refused (chi web's LAN link carries the current one: " \
-                      "chi remote add #{entry.name} #{entry.url} --token-file FILE)"
+        when 401 then AuthRefused.new("#{entry.label}: the token was refused (chi web's LAN link carries the current one: " \
+                                      "chi remote add #{entry.name} #{entry.url} --token-file FILE)")
         when 403
-          return nil unless reply.error == "forbidden"
+          return nil unless error == "forbidden"
 
           ip = reply.json["detail"].to_s[/ and (\S+) are answered/, 1]
-          "#{entry.label}: chi web answers its LAN IP only: use the LAN IP#{" #{ip}" if ip}, not a hostname"
+          AuthRefused.new("#{entry.label}: chi web answers its LAN IP only: use the LAN IP#{" #{ip}" if ip}, not a hostname")
         end
       end
 
+      ACCESS_ERRORS = [TokenRevoked, TokenExpired, NotPermitted, TooManyTurns, CapReached].freeze
+
       # --- ids and sessions
 
       # @raise [Session::AmbiguousId]
@@ -220,6 +231,40 @@ module Samagotchi
 
       # @return [NoteDelivery::Result]
       # @raise [SessionInbox::NoteRejected]
+      # --- participants (chi share)
+
+      # @param id [String, nil] one session's, or every session's
+      # @return [Array<ParticipantView>]
+      def participants(id = nil)
+        reply = request(:get, id ? "#{session_path(id)}/participants" : "/api/participants")
+        raise_refusal(reply) unless reply.status == 200
+
+        Array(reply.json["participants"]).map { |row| ParticipantView.from_h(row) }
+      end
+
+      # @param ttl [Integer, nil] seconds; nil: the grant's default
+      # @return [Invitation]
+      # @raise [BadRequest] a bad name, kind or ttl, an archived session
+      def invite(id, name:, kind:, ttl: nil)
+        reply = request(:post, "#{session_path(id)}/participants", body: { name: name, kind: kind, ttl: ttl }.compact)
+        raise_refusal(reply) unless reply.status == 201
+
+        json = reply.json
+        Invitation.new(participant: ParticipantView.from_h(json.fetch("participant")), token: json.fetch("token"),
+                       link: json.fetch("link"), lan: json["lan"] == true)
+      end
+
+      # Revokes one participant (+participant+), a session's, or with no
+      # +id+ every session's.
+      # @return [Array<ParticipantView>] the ones it revoked
+      def revoke_participants(id = nil, participant: nil)
+        reply = request(:delete, id ? "#{session_path(id)}/participants" : "/api/participants",
+                        query: { id: participant }.compact)
+        raise_refusal(reply) unless reply.status == 200
+
+        Array(reply.json["revoked"]).map { |row| ParticipantView.from_h(row) }
+      end
+
       def note(id, text:, source:)
         reply = request(:post, "#{session_path(id)}/notes", body: { text: text, source: source })
         json = reply.json.is_a?(Hash) ? reply.json : {}
@@ -317,13 +362,13 @@ module Samagotchi
 
       # --- sessions
 
-      # chi web stops it and waits its own bounded time (Web::App::
-      # STOP_WAIT_SECONDS, not +wait+).
+      # chi web stops it and waits up to +wait+ seconds (capped there at
+      # SessionManager::STOP_WAIT; a chi web before the field waits its
+      # Web::App::STOP_WAIT_SECONDS).
       # @return [Boolean] whether the worker had released it by then, as
       #   chi web's released says (absent: true)
       def stop(id, wait:)
-        _ = wait
-        reply = request(:post, "#{session_path(id)}/stop")
+        reply = request(:post, "#{session_path(id)}/stop", body: { wait: wait })
         raise_refusal(reply) unless reply.status == 200
 
         reply.json["released"] != false
@@ -454,6 +499,50 @@ module Samagotchi
         WebBridgeClient.new(remote: self, session_id: id, worker_key: worker["epoch"] || worker["started_at"])
       end
 
+      # This chi web has +feature+ (GET /api/info's), else RemoteTooOld in
+      # Remote.too_old_message's words.
+      # @raise [RemoteFailed]
+      def require_feature!(feature)
+        check_server!
+        raise RemoteTooOld, too_old(@version) unless Array(@features).include?(feature)
+      end
+
+      # POST …/wake: the session's live worker for a remote attach, started
+      # when none runs, waited for up to +wait+ seconds there (a leaving
+      # worker first: +read_timeout+ covers that wait too).
+      # @return [WakeReply]
+      # @raise [SessionManager::OwnedByTUI] a chi REPL has it there
+      # @raise [Refused] a leftover scratch session (code scratch), or its
+      #   Bridge didn't come in time (code worker_timeout): chi web's words,
+      #   LaunchMode's constants
+      # @raise [ArgumentError] no such session
+      def attach_wake(id, wait:, read_timeout: nil)
+        reply = request(:post, "#{session_path(id)}/wake", body: { wait: wait }, read_timeout: read_timeout)
+        if reply.status != 200 && %w[scratch worker_timeout].include?(reply.error)
+          raise Refused.new((reply.json["message"] || reply.json["detail"]).to_s, code: reply.error)
+        end
+
+        raise_refusal(reply) unless reply.status == 200
+
+        json = reply.json
+        WakeReply.new(woke: json["woke"] == true, worker: json["worker"], default_model: json["default_model"],
+                      strategy: strategy_or_hard(json["parent_strategy"]), installed: json["installed"])
+      end
+
+      # GET …/worker: the session's worker now (never started).
+      # @return [WorkerReply]
+      # @raise [ArgumentError] no such session
+      def attach_worker(id)
+        reply = request(:get, "#{session_path(id)}/worker")
+        raise_refusal(reply) unless reply.status == 200
+
+        json = reply.json
+        seconds = json["leave_seconds"]
+        WorkerReply.new(live: json["live"] == true, stopped: json["stopped"] == true, worker: json["worker"],
+                        strategy: strategy_or_hard(json["parent_strategy"]), default_model: json["default_model"],
+                        leaving: json["leaving"] == true, leave_seconds: (seconds.to_f if seconds.is_a?(Numeric)))
+      end
+
       # One request to a route, as the session commands make them (the
       # server check first; a refused token or a missing route raise
       # RemoteFailed): WebBridgeClient's, which maps the reply itself.
@@ -476,7 +565,8 @@ module Samagotchi
       def request(method, path, **)
         check_server!
         reply = @transport.call(method, path, **)
-        raise RemoteFailed, Remote.auth_failure(@entry, reply) if Remote.auth_failure(@entry, reply)
+        refused = Remote.access_error(@entry, reply)
+        raise refused if refused
         raise RemoteTooOld, too_old(@version) if missing_route?(reply)
 
         reply
@@ -486,7 +576,10 @@ module Samagotchi
         return if @checked
 
         reply = @transport.call(:get, "/api/info")
-        @version = reply.json["version"] if reply.json.is_a?(Hash)
+        if reply.json.is_a?(Hash)
+          @version = reply.json["version"]
+          @features = Array(reply.json["features"])
+        end
         problem = Remote.info_problem(@entry, reply)
         raise problem if problem
 
@@ -495,6 +588,8 @@ module Samagotchi
 
       def too_old(version) = Remote.too_old_message(@entry, version)
 
+      def strategy_or_hard(json) = strategy_of(json) || Guardrails::ParentPolicy.strategy(Guardrails::ParentPolicy::HARD)
+
       # chi web's 404 for a path no route takes (#serve_static's), not a
       # route's own "no such session".
       def missing_route?(reply)
@@ -527,6 +622,7 @@ module Samagotchi
         # spawn_session raises here (chi send: could not start a session).
         when "invalid_model" then raise ModelProfile::MissingModel, message.to_s
         when /\Ainvalid_/, "missing_fields", "bad_images"
+          # invalid_participant: chi share's name, kind or ttl, an archived session
           raise BadRequest.new(message.to_s, code: error)
         end
         raise RemoteFailed, "#{@entry.label} answered #{reply.status}#{" #{error}" unless error.empty?}" \
@@ -535,7 +631,7 @@ module Samagotchi
 
       def create_body(spec)
         body = { model: spec.model_name, client_id: spec.client_id, history: false }
-        if spec.preview
+        if spec.preview || spec.idle
           body.merge!(idle: true, preview: spec.preview)
         else
           body[:prompt] = spec.prompt

data/lib/samagotchi/session_access/web_bridge_client.rb

@@ -36,6 +36,9 @@ module Samagotchi
       # No byte for this long on the stream (the Bridge pings every 15 s): a
       # half-open connection (Wi-Fi gone, the laptop asleep), reconnected.
       STREAM_IDLE_TIMEOUT = 40.0
+      # A read a join waits on (a turn's saved records, the children
+      # counts): a slow chi web can't hold the join up for long (L9).
+      JOIN_READ_TIMEOUT = 5
       # chi web answers no live worker for the session (Mapping).
       NO_WORKER = "no live worker for session %s on %s"
 
@@ -44,7 +47,7 @@ module Samagotchi
         module_function
 
         # @param route [Symbol] :turn, :command, :answer, :dismiss,
-        #   :dequeue, :cancel
+        #   :dequeue, :cancel, :exit, :recap, :stats, :children, :records
         # @param reply [HTTPTransport::Reply]
         # @param session_id [String]
         # @param remote [String] the remote's name
@@ -89,9 +92,11 @@ module Samagotchi
       def port = nil
 
       # POST …/turn. history: false (chi web's prompt history is that
-      # machine's page's).
+      # machine's page's). +author+ is never sent: the remote chi web stamps
+      # a turn's author from the token this client holds (Web::Principal),
+      # never from the body.
       # @return [BridgeClient::Response]
-      def post_turn(prompt:, client_id: nil, no_interrupt: false, images: nil, delivery: nil)
+      def post_turn(prompt:, client_id: nil, no_interrupt: false, images: nil, delivery: nil, author: nil)
         body = { prompt: prompt, client_id: client_id, history: false }
         body[:no_interrupt] = true if no_interrupt
         body[:images] = images if images && !images.empty?
@@ -133,6 +138,51 @@ module Samagotchi
         post(:cancel, "cancel", { reason: reason })
       end
 
+      # POST …/exit: the worker asked to exit (chi web passes client_id on
+      # only when it is an attached TUI's).
+      # @return [BridgeClient::Response] 200 {status: exiting, discard}, 409
+      #   held {reason, tasks}, 408 late, 404 an older worker's
+      def request_exit(client_id:, delete: false)
+        body = { client_id: client_id }
+        body[:delete] = true if delete
+        post(:exit, "exit", body)
+      end
+
+      # POST …/recap: the saved recap, and a new one asked for.
+      # @return [BridgeClient::Response] 200 {enabled, saved, request, min_user_turns, session_off}
+      def request_recap = post(:recap, "recap", {})
+
+      # GET …/stats: the worker's metrics (its state's, for an older
+      # worker), nil when it didn't give them.
+      # @return [Hash, nil]
+      # @raise [Unreachable]
+      def stats
+        response = get(:stats, "stats", read_timeout: READ_TIMEOUT)
+        response.status == 200 ? response.json&.dig("metrics") : nil
+      end
+
+      # GET …/children/counts: the session's delegates' counts there.
+      # @return [Hash] {running, waiting, unreported}
+      # @raise [Unreachable] chi web couldn't answer (or the session is gone)
+      def children_counts
+        response = get(:children, "children/counts", read_timeout: JOIN_READ_TIMEOUT)
+        raise Unreachable, "children counts: chi web answered #{response.status}" unless response.status == 200
+
+        response.json
+      end
+
+      # GET …/turns/:turn_id/records: a turn's saved tool records and turn
+      # record there.
+      # @return [Hash] {tool_records: [...], turn_record: {...} | nil}
+      # @raise [Unreachable]
+      def turn_records(turn_id)
+        response = get(:records, "turns/#{URI.encode_www_form_component(turn_id.to_s)}/records",
+                       read_timeout: JOIN_READ_TIMEOUT)
+        raise Unreachable, "turn records: chi web answered #{response.status}" unless response.status == 200
+
+        response.json
+      end
+
       # Follow the session's events through chi web (see EventStream): with
       # epoch_watch, announce_retries and STREAM_IDLE_TIMEOUT.
       # @return [BridgeClient::EventStream] started
@@ -172,6 +222,13 @@ module Samagotchi
         raise Unreachable, e.message
       end
 
+      def get(route, path, read_timeout:)
+        reply = @remote.route_request(:get, "/api/sessions/#{@session_id}/#{path}", read_timeout: read_timeout)
+        Mapping.response(route, reply, session_id: @session_id, remote: @remote.name)
+      rescue RemoteFailed => e
+        raise Unreachable, e.message
+      end
+
       def refused(reason)
         Log.warn(:attached, "stream_refused", reason: reason, remote: @remote.name)
         nil

data/lib/samagotchi/session_access.rb

@@ -28,6 +28,47 @@ module Samagotchi
     # --remote: update chi there (chi update)").
     class RemoteTooOld < RemoteFailed; end
 
+    # A remote's chi web refused this machine's token (401), or answers its
+    # LAN IP only (403 forbidden): Remote.access_error's words.
+    class AuthRefused < RemoteFailed; end
+
+    # The errors a participant's token meets (docs/internals/participants.md),
+    # one message each, built from the remote's label ("remote studio
+    # (http://…)"). chi web's code for each is its CODE.
+
+    # 401 token_revoked: the owner revoked the grant, or archived or
+    # deleted its session.
+    class TokenRevoked < AuthRefused
+      CODE = "token_revoked"
+      def initialize(label) = super("#{label}: this review link was revoked by the session's owner")
+    end
+
+    # 401 token_expired: the grant's time ran out.
+    class TokenExpired < AuthRefused
+      CODE = "token_expired"
+      def initialize(label) = super("#{label}: this review link expired: ask the session's owner for a new one")
+    end
+
+    # 403 not_permitted: a participant's token on a route only the session's
+    # owner may use.
+    class NotPermitted < RemoteFailed
+      CODE = "not_permitted"
+      def initialize(label) = super("#{label}: this token is a participant's: only the session's owner can do that")
+    end
+
+    # 429 too_many_turns (P3b): the participant's turns already wait in the
+    # queue up to their limit.
+    class TooManyTurns < RemoteFailed
+      CODE = "too_many_turns"
+      def initialize(label) = super("#{label}: this participant has too many turns waiting: wait for one to finish")
+    end
+
+    # 429 cap_reached (P3b): the participant's grant spent its cap.
+    class CapReached < RemoteFailed
+      CODE = "cap_reached"
+      def initialize(label) = super("#{label}: this participant's spending cap is reached: ask the session's owner to raise it")
+    end
+
     # A remote's chi web refused a request for a reason this machine checks
     # itself before sending (a parent's /continue yes, a loosening
     # /parent-answers, images to a model that can't see them): +message+
@@ -47,11 +88,30 @@ module Samagotchi
     # exits 2 with its message.
     class BadRequest < Refused; end
 
+    # One participant's grant as chi share ls shows it
+    # (Web::Grants::Grant#public_h): never its token or digest. +state+
+    # "active", "revoked" or "expired".
+    ParticipantView = Data.define(:id, :session_id, :kind, :name, :role, :created_at, :expires_at, :revoked_at,
+                                  :revoked_by, :last_used_at, :state) do
+      def self.from_h(hash) = new(**members.to_h { |key| [key, hash[key] || hash[key.to_s]] })
+    end
+
+    # What chi share made: the participant, their token and the link that
+    # carries it (both shown this once: chi keeps only a digest), and
+    # whether that chi web listens on the LAN (+lan+ false: the link works
+    # on that machine only).
+    Invitation = Data.define(:participant, :token, :link, :lan) do
+      def inspect = "#<Invitation #{participant.id}>"
+      alias_method :to_s, :inspect
+    end
+
     # A session to create (chi send --new): a new one, or with +continues+
     # the next link of that session's chain (which brings its own folder,
     # LLM context, thinking, toolkit and settings: the rest is nil then).
     # +preview+ set: the session starts idle with it as its preview, and
-    # +prompt+ (nil) goes in later as a turn (images, a session command).
+    # +prompt+ (nil) goes in later as a turn (images, a session command);
+    # +idle+ alone: it starts idle with no preview (a remote attach's new
+    # session, whose -p goes in once attached).
     # +setup+ is a SessionSetup for Local, a SetupWords for Remote (the
     # flags as typed: the server checks them against its own config and
     # bundles). +client_id+ (chi send's, or chi answer's for a parent's
@@ -59,9 +119,9 @@ module Samagotchi
     # which checks the first line and the model as chi send checks them
     # here (Local checks before it creates).
     NewSession = Data.define(:prompt, :preview, :continues, :working_directory, :model_name, :setup, :client_id,
-                             :images) do
+                             :images, :idle) do
       def initialize(prompt:, preview: nil, continues: nil, working_directory: nil, model_name: nil, setup: nil,
-                     client_id: nil, images: false) = super
+                     client_id: nil, images: false, idle: false) = super
     end
 
     # chi send --new's setup flags as typed, for a Remote: +llm_context+
@@ -94,6 +154,10 @@ module Samagotchi
     # its OwnerLock::Owner (a worker, a chi REPL, nil).
     WorkerState = Data.define(:sidecar, :stopped, :owner) do
       def live? = !sidecar.nil?
+
+      # No Bridge, and the owner is a worker leaving (writing its recap on
+      # leave): a wake waits for it (Local#wake).
+      def leaving? = !live? && !!owner&.leaving?
     end
 
     # What a wake for an attach did (Local#wake, chi web's POST …/wake):
@@ -101,6 +165,24 @@ module Samagotchi
     # worker's (nil: its Bridge didn't come within the wait).
     Woken = Data.define(:woke, :sidecar)
 
+    # A remote attach's wake (Remote#attach_wake, chi web's POST …/wake):
+    # +worker+ the live worker as chi web names it ({"epoch", "started_at",
+    # "version", "features"}, string keys: Remote#attach_client's), and
+    # what the TUI reads of that machine: its config's +default_model+,
+    # the session's parent +strategy+ (Guardrails::ParentPolicy::Strategy),
+    # the newest chi +installed+ there.
+    WakeReply = Data.define(:woke, :worker, :default_model, :strategy, :installed)
+
+    # A remote session's worker now (Remote#attach_worker, chi web's GET
+    # …/worker): +live+, +stopped+ (its stop marker), +worker+ as in
+    # WakeReply (nil: none runs), the parent +strategy+ read now, and that
+    # machine's +default_model+ (nil from a chi web before it sent one).
+    # +leaving+: its worker is leaving (WorkerState#leaving?), for up to
+    # +leave_seconds+ more there (nil from a chi web before it sent them).
+    WorkerReply = Data.define(:live, :stopped, :worker, :strategy, :default_model, :leaving, :leave_seconds) do
+      def initialize(live:, stopped:, worker:, strategy:, default_model: nil, leaving: false, leave_seconds: nil) = super
+    end
+
     # What chi send --wait and chi answer read before anything is sent, so
     # neither an older reply nor a turn that ends before the first look is
     # taken for the answer (ReplyWait's cursor:, baseline:, turn:).