samagotchi 0.107.0 → 0.108.0

data/lib/samagotchi/web/participant_access.rb

@@ -4,15 +4,12 @@ require "json"
 require_relative "grants"
 require_relative "principal"
 require_relative "participant_view"
-require_relative "qr"
 require_relative "../archive_store"
 require_relative "../client_id"
 require_relative "../delivery"
 require_relative "../session_inbox"
 require_relative "../session_metrics"
 require_relative "../parent_report"
-require_relative "../review_start"
-require_relative "../review_apply"
 require_relative "../participant_messages"
 require_relative "../participants"
 require_relative "../session"
@@ -22,10 +19,12 @@ module Samagotchi
   module Web
     # What a participant (a Web::Grants token) may do in chi web, mixed into
     # App: the gate's lookup of their grant, the refusals that are theirs
-    # (token_revoked, token_expired, another session's 404, not_permitted
-    # by role), the trimmed answers of the :participant routes, their turns,
-    # and the running check that ends their streams when the grant does
-    # (what they read is ParticipantReview's). See
+    # (token_revoked, token_expired with its ended page, another session's
+    # 404, not_permitted by role), the trimmed answers of their own routes
+    # (info, the session, resolve, a wait on their turn), their turns, and
+    # the running check that ends their streams when the grant does. What
+    # they read is ParticipantReview's; the owner's routes for them (invite,
+    # list, revoke, cap, Apply) are ParticipantsAdmin's. See
     # docs/internals/participants.md.
     module ParticipantAccess
       # A participant's refused routes are audited at most this often per
@@ -376,115 +375,6 @@ module Samagotchi
         -> { @server_running.call && @grants.active?(id) }
       end
 
-      # ── The owner's routes ─────────────────────────────────────────────
-
-      # GET /api/sessions/:id/participants, GET /api/participants: the
-      # grants (one session's, or every one), in every state, never a token
-      # or digest. One session's also carries +warning+: the share warning
-      # for a session that isn't a review session (ReviewStart.share_warning,
-      # null for one), which the panel shows before its Invite.
-      def handle_participants_list(_req, id = nil)
-        now = @grants.now
-        grants = @grants.list(session_id: id).map { |grant| grant.public_h(now) }
-        return json_response(200, { participants: grants }) unless id
-
-        warning = ReviewStart.share_warning(Session.load(id, state_dir: default_state_dir))
-        json_response(200, { participants: with_spend(id, grants), warning: warning })
-      end
-
-      # One session's grants with what each spent and how many turns they
-      # ran (its saved analytics: SessionMetrics.saved_by_author), for the
-      # owner's participants panel.
-      def with_spend(id, grants)
-        rows = SessionMetrics.saved_by_author(Session.session_dir(id, state_dir: default_state_dir))
-        grants.map do |grant|
-          row = rows["p:#{grant[:id]}"] || { turns: 0, cost: 0.0 }
-          grant.merge(spend: row[:cost].round(4), turns: row[:turns])
-        end
-      end
-
-      # POST /api/sessions/:id/participants {name, kind?, ttl? (seconds),
-      # cap? (dollars)}: a new grant. The answer carries the token and the
-      # link once (chi keeps only its digest), and +warning+ for a session
-      # that isn't a review session (ReviewStart.share_warning; null for one).
-      def handle_participants_invite(req, id)
-        body = body_hash(req) or return error_response(400, "invalid_json", "invalid JSON body")
-        ttl = body["ttl"]
-        return error_response(400, "invalid_participant", "ttl is a number of seconds") unless ttl.nil? || ttl.is_a?(Integer)
-
-        cap = body["cap"]
-        return error_response(400, "invalid_participant", Grants::CAP_RANGE) unless cap.nil? || Grants.cap?(cap)
-
-        issued = Participants.invite(@grants, session_id: id, name: body["name"], kind: (body["kind"] || "human").to_s,
-                                              ttl: ttl, cap: cap, state_dir: default_state_dir)
-        link = participant_link(req, id, issued.token)
-        warning = ReviewStart.share_warning(Session.load(id, state_dir: default_state_dir))
-        json_response(201, { participant: issued.grant.public_h(@grants.now), token: issued.token,
-                             link: link, lan: !@lan.nil?, qr_svg: QR.svg(link), warning: warning })
-      rescue Grants::Invalid => e
-        error_response(400, "invalid_participant", e.message)
-      end
-
-      # GET /api/sessions/:id/apply[?turn=T] (owner): the owner's turn that
-      # applies review turn T's proposal (ReviewApply: the reply quoted
-      # under one line of the owner's), for the composer: never sent from
-      # here. Without turn, the latest review turn with a reply. Read from
-      # the live worker's messages, else the saved ones.
-      # @return 200 {text, turn_id, author, author_name}; 404 not_found (no
-      #   such turn, or no review turn); 400 not_review_turn; 409 no_reply
-      def handle_apply(req, id)
-        session = @session_class.load(id, state_dir: default_state_dir)
-        live = bridge_get_json(id, "snapshot")
-        messages = live_or_saved(live && live["snapshot"], "messages") { session.messages }
-        proposal = ReviewApply.find(messages, req.params["turn"])
-        json_response(200, { text: ReviewApply.compose(proposal), turn_id: proposal.turn_id, author: proposal.author,
-                             author_name: proposal.author_name })
-      rescue ReviewApply::Refused => e
-        status = { not_found: 404, not_review_turn: 400, no_reply: 409 }.fetch(e.code)
-        error_response(status, e.code.to_s, e.message)
-      end
-
-      # DELETE /api/sessions/:id/participants[?id=p_…], DELETE
-      # /api/participants: revokes one participant, a session's or every
-      # one's; their open streams end within a poll.
-      def handle_participants_revoke(req, id = nil)
-        grant_id = req.params["id"]
-        if grant_id && !Grants::ID_RE.match?(grant_id.to_s)
-          return error_response(400, "invalid_participant", "not a participant id: #{grant_id.to_s[0, 40]}")
-        end
-
-        revoked = Participants.revoke(@grants, session_id: id, id: grant_id, by: "owner", state_dir: default_state_dir)
-        now = @grants.now
-        json_response(200, { revoked: revoked.map { |grant| grant.public_h(now) } })
-      end
-
-      # POST /api/sessions/:id/participants/:participant/cap {cap}: the
-      # active participant's new spending cap (dollars), from their next
-      # turn on. 200 {participant}; 400 invalid_participant.
-      def handle_participants_cap(req, id, grant_id)
-        body = body_hash(req) or return error_response(400, "invalid_json", "invalid JSON body")
-        unless Grants::ID_RE.match?(grant_id.to_s)
-          return error_response(400, "invalid_participant", "not a participant id: #{grant_id.to_s[0, 40]}")
-        end
-
-        grant = Participants.set_cap(@grants, session_id: id, id: grant_id, cap: body["cap"], state_dir: default_state_dir)
-        return error_response(400, "invalid_participant", Participants.no_participant(grant_id, id)) unless grant
-
-        json_response(200, { participant: grant.public_h(@grants.now) })
-      rescue Grants::Invalid => e
-        error_response(400, "invalid_participant", e.message)
-      end
-
-      # The link a participant opens: this chi web's LAN address when it has
-      # one (the owner may be asking on loopback), else the Host asked; the
-      # token traded for the cookie, the session in the fragment.
-      def participant_link(req, id, token)
-        host = req.get_header("HTTP_HOST").to_s
-        port = host[/:(\d+)\z/, 1] || req.port.to_s
-        name = @lan ? @lan[:ip] : host.sub(/:\d*\z/, "")
-        "http://#{name}:#{port}/?token=#{token}#s=#{id}"
-      end
-
       def html_response(status, body)
         [status, { "Content-Type" => "text/html; charset=utf-8", "Content-Length" => body.bytesize.to_s,
                    "Cache-Control" => "no-store" }, [body]]

data/lib/samagotchi/web/participant_view.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require_relative "../client_id"
 require_relative "../output_formatter"
 require_relative "../steer"
+require_relative "../turn_origin"
 
 module Samagotchi
   module Web
@@ -102,17 +102,18 @@ module Samagotchi
 
       # A turn's start: who wrote it, and its prompt when a person sent it
       # (an automatic turn's prompt, a reminder's or a task's, is not
-      # shown). +mine+ when the viewer queued it.
+      # shown: a person is the owner's web or TUI, chi send, a participant,
+      # or no origin, an in-process turn: the owner's; TurnOrigin#human?).
+      # +mine+ when the viewer queued it.
       def turn_started(event, viewer)
-        origin = field(event, :origin)
-        origin = {} unless origin.is_a?(Hash)
-        author = field(event, :author) || field(origin, :author)
+        origin = TurnOrigin.of(field(event, :origin))
+        author = field(event, :author) || origin.author
         out = { "type" => "turn_started", **id_fields(event) }
         out.merge!(author_fields(author, field(event, :author_name), viewer))
         prompt = field(event, :prompt)
         if field(event, :continue)
           out["continue"] = true
-        elsif person_turn?(origin)
+        elsif origin.human?
           out["prompt"] = prompt.to_s unless prompt.nil?
         else
           out["automatic"] = true
@@ -286,13 +287,6 @@ module Samagotchi
         out
       end
 
-      # Sent by a person (the owner's web or TUI, chi send, a participant),
-      # or with no origin (an in-process turn: the owner's).
-      def person_turn?(origin)
-        client_id = field(origin, :client_id)
-        client_id.nil? || ClientId.human?(client_id)
-      end
-
       def id_fields(event)
         out = seq(event)
         turn_id = field(event, :turn_id)

data/lib/samagotchi/web/participants_admin.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative "grants"
+require_relative "qr"
+require_relative "../review_start"
+require_relative "../review_apply"
+require_relative "../session_metrics"
+require_relative "../participants"
+require_relative "../session"
+
+module Samagotchi
+  module Web
+    # The owner's routes for a session's participants, mixed into App:
+    # invite, list, revoke, a participant's cap, and the review Apply (the
+    # owner's turn quoting a review turn's proposal). What a participant
+    # may do themselves is ParticipantAccess's. See
+    # docs/internals/participants.md.
+    module ParticipantsAdmin
+      private
+
+      # GET /api/sessions/:id/participants, GET /api/participants: the
+      # grants (one session's, or every one), in every state, never a token
+      # or digest. One session's also carries +warning+: the share warning
+      # for a session that isn't a review session (ReviewStart.share_warning,
+      # null for one), which the panel shows before its Invite.
+      def handle_participants_list(_req, id = nil)
+        now = @grants.now
+        grants = @grants.list(session_id: id).map { |grant| grant.public_h(now) }
+        return json_response(200, { participants: grants }) unless id
+
+        warning = ReviewStart.share_warning(Session.load(id, state_dir: default_state_dir))
+        json_response(200, { participants: with_spend(id, grants), warning: warning })
+      end
+
+      # One session's grants with what each spent and how many turns they
+      # ran (its saved analytics: SessionMetrics.saved_by_author), for the
+      # owner's participants panel.
+      def with_spend(id, grants)
+        rows = SessionMetrics.saved_by_author(Session.session_dir(id, state_dir: default_state_dir))
+        grants.map do |grant|
+          row = rows[Steer.author_for(grant[:id])] || { turns: 0, cost: 0.0 }
+          grant.merge(spend: row[:cost].round(4), turns: row[:turns])
+        end
+      end
+
+      # POST /api/sessions/:id/participants {name, kind?, ttl? (seconds),
+      # cap? (dollars)}: a new grant. The answer carries the token and the
+      # link once (chi keeps only its digest), and +warning+ for a session
+      # that isn't a review session (ReviewStart.share_warning; null for one).
+      def handle_participants_invite(req, id)
+        body = body_hash(req) or return error_response(400, "invalid_json", "invalid JSON body")
+        ttl = body["ttl"]
+        return error_response(400, "invalid_participant", "ttl is a number of seconds") unless ttl.nil? || ttl.is_a?(Integer)
+
+        cap = body["cap"]
+        return error_response(400, "invalid_participant", Grants::CAP_RANGE) unless cap.nil? || Grants.cap?(cap)
+
+        issued = Participants.invite(@grants, session_id: id, name: body["name"], kind: (body["kind"] || "human").to_s,
+                                              ttl: ttl, cap: cap, state_dir: default_state_dir)
+        link = participant_link(req, id, issued.token)
+        warning = ReviewStart.share_warning(Session.load(id, state_dir: default_state_dir))
+        json_response(201, { participant: issued.grant.public_h(@grants.now), token: issued.token,
+                             link: link, lan: !@lan.nil?, qr_svg: QR.svg(link), warning: warning })
+      rescue Grants::Invalid => e
+        error_response(400, "invalid_participant", e.message)
+      end
+
+      # GET /api/sessions/:id/apply[?turn=T] (owner): the owner's turn that
+      # applies review turn T's proposal (ReviewApply: the reply quoted
+      # under one line of the owner's), for the composer: never sent from
+      # here. Without turn, the latest review turn with a reply. Read from
+      # the live worker's messages, else the saved ones.
+      # @return 200 {text, turn_id, author, author_name}; 404 not_found (no
+      #   such turn, or no review turn); 400 not_review_turn; 409 no_reply
+      def handle_apply(req, id)
+        session = @session_class.load(id, state_dir: default_state_dir)
+        live = bridge_get_json(id, "snapshot")
+        messages = live_or_saved(live && live["snapshot"], "messages") { session.messages }
+        proposal = ReviewApply.find(messages, req.params["turn"])
+        json_response(200, { text: ReviewApply.compose(proposal), turn_id: proposal.turn_id, author: proposal.author,
+                             author_name: proposal.author_name })
+      rescue ReviewApply::Refused => e
+        status = { not_found: 404, not_review_turn: 400, no_reply: 409 }.fetch(e.code)
+        error_response(status, e.code.to_s, e.message)
+      end
+
+      # DELETE /api/sessions/:id/participants[?id=p_…], DELETE
+      # /api/participants: revokes one participant, a session's or every
+      # one's; their open streams end within a poll.
+      def handle_participants_revoke(req, id = nil)
+        grant_id = req.params["id"]
+        if grant_id && !Grants::ID_RE.match?(grant_id.to_s)
+          return error_response(400, "invalid_participant", "not a participant id: #{grant_id.to_s[0, 40]}")
+        end
+
+        revoked = Participants.revoke(@grants, session_id: id, id: grant_id, by: "owner", state_dir: default_state_dir)
+        now = @grants.now
+        json_response(200, { revoked: revoked.map { |grant| grant.public_h(now) } })
+      end
+
+      # POST /api/sessions/:id/participants/:participant/cap {cap}: the
+      # active participant's new spending cap (dollars), from their next
+      # turn on. 200 {participant}; 400 invalid_participant.
+      def handle_participants_cap(req, id, grant_id)
+        body = body_hash(req) or return error_response(400, "invalid_json", "invalid JSON body")
+        unless Grants::ID_RE.match?(grant_id.to_s)
+          return error_response(400, "invalid_participant", "not a participant id: #{grant_id.to_s[0, 40]}")
+        end
+
+        grant = Participants.set_cap(@grants, session_id: id, id: grant_id, cap: body["cap"], state_dir: default_state_dir)
+        return error_response(400, "invalid_participant", Participants.no_participant(grant_id, id)) unless grant
+
+        json_response(200, { participant: grant.public_h(@grants.now) })
+      rescue Grants::Invalid => e
+        error_response(400, "invalid_participant", e.message)
+      end
+
+      # The link a participant opens: this chi web's LAN address when it has
+      # one (the owner may be asking on loopback), else the Host asked; the
+      # token traded for the cookie, the session in the fragment.
+      def participant_link(req, id, token)
+        host = req.get_header("HTTP_HOST").to_s
+        port = host[/:(\d+)\z/, 1] || req.port.to_s
+        name = @lan ? @lan[:ip] : host.sub(/:\d*\z/, "")
+        "http://#{name}:#{port}/?token=#{token}#s=#{id}"
+      end
+    end
+  end
+end

data/lib/samagotchi/web/public/participant.js

@@ -6,7 +6,7 @@
 // progress from the stream in between. A participant's comment is
 // POST …/turn (text only); their queued ones come back with Dequeue.
 import {
-  authorColor, authorLabel, toolLine, toolsSummary, refusalText, dequeueText, endedText, streamURL, reloads, endsLiveTurn, liveFrom, applyLive,
+  authorColor, participantAuthor, authorLabel, toolLine, toolsSummary, refusalText, dequeueText, endedText, streamURL, reloads, endsLiveTurn, liveFrom, applyLive,
   liveText, withToolSteps, pickSubject, subjectBody, subjectsKey, narrowView, retryDelay, retries,
 } from "./participant_model.js";
 
@@ -160,7 +160,7 @@ function render() {
   status.className = `p-status ${waiting ? "waiting" : session.status === "running" ? "running" : ""}`;
   $("people").replaceChildren(...(data.participants || []).map((p) => {
     const chip = el("span", "p-person");
-    chip.style.setProperty("--author-color", authorColor(`p:${p.id}`));
+    chip.style.setProperty("--author-color", authorColor(participantAuthor(p.id)));
     chip.append(el("span", "p-dot"), `${p.name}${p.kind === "agent" ? " (agent)" : ""}`);
     return chip;
   }));

data/lib/samagotchi/web/public/participant_model.js

@@ -3,6 +3,11 @@
 // refusal in words, the stream's URL, and the live turn as filtered events
 // build it (ParticipantView on the server decides what arrives at all).
 
+// A participant's author: "p:" and its grant id, as the server writes it
+// (Steer.author_for / PARTICIPANT_PREFIX): the one place the web spells it.
+export const PARTICIPANT_PREFIX = "p:";
+export const participantAuthor = (id) => `${PARTICIPANT_PREFIX}${id}`;
+
 // Six author colours (tokens.css --author-1..6), one per participant id,
 // the same on every page that shows them (the owner's badges too).
 export const AUTHOR_SLOTS = 6;

data/lib/samagotchi/web/public/participant_names.js

@@ -4,7 +4,7 @@
 // prompt's own author_name (a saved message, turn_started) comes first; a
 // badge drawn before the list came, with neither, says UNNAMED until
 // nameUnnamedBadges names it.
-import { authorColor } from "./participant_model.js";
+import { authorColor, participantAuthor } from "./participant_model.js";
 
 export const UNNAMED = "a participant";
 
@@ -13,7 +13,7 @@ let names = new Map();
 // @return whether the names changed (the panel then names the badges drawn
 // without them)
 export function setParticipantNames(grants) {
-  const next = new Map((grants || []).filter((g) => g?.id).map((g) => [`p:${g.id}`, String(g.name || "")]));
+  const next = new Map((grants || []).filter((g) => g?.id).map((g) => [participantAuthor(g.id), String(g.name || "")]));
   const changed = next.size !== names.size || [...next].some(([author, name]) => names.get(author) !== name);
   names = next;
   return changed;

data/lib/samagotchi/web/public/participants_panel.js

@@ -14,7 +14,7 @@
 
 import { html, nothing, render } from "./vendor/lit-html.js";
 import { createChipPopover } from "./chip_popover.js";
-import { authorColor } from "./participant_model.js";
+import { authorColor, participantAuthor } from "./participant_model.js";
 import { setParticipantNames } from "./participant_names.js";
 
 // Seen this recently: here now (the chip's dot). The gate writes
@@ -63,7 +63,7 @@ export function rowModel(grant, now) {
     kind: grant.kind,
     active,
     present,
-    color: authorColor(`p:${grant.id}`),
+    color: authorColor(participantAuthor(grant.id)),
     state: active ? (present ? "here now" : `seen ${agoText(grant.last_used_at, now)}`)
       : grant.state === "expired" ? "expired" : `revoked${grant.revoked_by ? ` (${grant.revoked_by})` : ""}`,
     expires: active ? `expires ${untilText(grant.expires_at, now)}` : "",

data/lib/samagotchi/worker.rb

@@ -11,6 +11,7 @@ require_relative "session"
 require_relative "session_inbox"
 require_relative "turn_note"
 require_relative "steer"
+require_relative "turn_origin"
 require_relative "worker_idle_exit"
 require_relative "worker_wakes"
 require_relative "worker_inbound"
@@ -145,7 +146,7 @@ module Samagotchi
       @discard = false
       # The exit asked for is a restart (POST /exit restart: true).
       @exit_restart = false
-      # The lines the running turn's drain merged ([prompt, origin]), for a
+      # The lines the running turn's drain merged ([prompt, TurnOrigin]), for a
       # failed prompt turn to hand back; reset as each turn begins.
       @merged_this_turn = []
       # A delegate child's side (ChildRing): whether the running turn is
@@ -624,7 +625,7 @@ module Samagotchi
       # A participant's turn queued before their link ended or their cap was
       # reached doesn't start (chi web refuses new ones; this is the
       # worker's check).
-      if (reason = participant_refusal(origin&.dig(:author)))
+      if (reason = participant_refusal(origin.author))
         return refuse_participant_turn(origin, reason)
       end
 
@@ -632,7 +633,7 @@ module Samagotchi
       # background tasks that finished since the last look.
       absorb_context(before_turn: true)
       @task_wakes.absorb
-      user_input(origin&.dig(:client_id))
+      user_input(origin.client_id)
       @continue_offer.drop(origin)
       @turn_flow.before_prompt_turn
       run_engine_turn(prompt.text, origin: origin, max_iterations: max_iterations(prompt.no_interrupt),
@@ -644,7 +645,7 @@ module Samagotchi
           @continue_offer.after_turn(result, no_interrupt: prompt.no_interrupt)
         end
       end
-      participant_refusal(origin&.dig(:author))
+      participant_refusal(origin.author)
     end
 
     # Why the participant +author+ ("p:<id>") may run no more turns, nil
@@ -656,7 +657,7 @@ module Samagotchi
     def participant_refusal(author)
       author = Steer.sender_author(author) or return nil
 
-      entry = Participants.read(@session_id, state_dir: @state_dir).find { |e| "p:#{e.id}" == author }
+      entry = Participants.read(@session_id, state_dir: @state_dir).find { |e| Steer.author_for(e.id) == author }
       return "revoked" unless entry&.active?(Time.now)
 
       cap = entry.cap.is_a?(Numeric) ? entry.cap.to_f : Web::Grants.default_cap
@@ -673,7 +674,7 @@ module Samagotchi
       return if (@cap_noticed ||= Set.new).include?(key)
 
       @cap_noticed << key
-      id = author.delete_prefix("p:")
+      id = Steer.participant_id(author)
       who = ParticipantName.clean(name)
       @engine.announce(type: :hook_notice, hook: "participants", level: :warn, between_turns: true,
                        text: format(CAP_NOTICE, name: who.empty? ? id : who, cap: cap, session: @session_id[0, 8], id: id))
@@ -686,11 +687,12 @@ module Samagotchi
     # taken off the queue (:turn_dequeued, so every UI drops its bubble)
     # and audited; it never runs. Its settled record (canceled, the reason)
     # ends the sender's wait on it (chi send --wait, chi web's /wait).
+    # @param origin [TurnOrigin] a participant's
     def refuse_participant_turn(origin, reason)
-      TurnCheckpoint.record_refused(@session_dir, origin[:enqueued_id], reason: reason)
-      Participants.log(@session_id, :turn, state_dir: @state_dir, participant: origin[:author].delete_prefix("p:"),
-                                           enqueued_id: origin[:enqueued_id], status: "refused", reason: reason)
-      @engine.announce(type: :turn_dequeued, enqueued_id: origin[:enqueued_id], client_id: origin[:client_id])
+      TurnCheckpoint.record_refused(@session_dir, origin.enqueued_id, reason: reason)
+      Participants.log(@session_id, :turn, state_dir: @state_dir, participant: origin.participant_id,
+                                           enqueued_id: origin.enqueued_id, status: "refused", reason: reason)
+      @engine.announce(type: :turn_dequeued, enqueued_id: origin.enqueued_id, client_id: origin.client_id)
       nil
     end
 
@@ -705,15 +707,18 @@ module Samagotchi
       @engine.clear_due_reminder_names!
       return false unless @engine.reminders_due?
 
-      @continue_offer.drop({ client_id: ClientId::REMINDER })
+      @continue_offer.drop(REMINDER_ORIGIN)
       # A failure has no prompt to hand back (the Engine announced
       # :turn_failed). The offer went before the turn
       # (ContinueOffer#drop); either way the rollback window closes.
-      run_engine_turn(nil, continue: true, origin: { client_id: ClientId::REMINDER },
+      run_engine_turn(nil, continue: true, origin: REMINDER_ORIGIN,
                            max_iterations: IterationLimit.for) { @turn_flow.after_reminder_turn }
       true
     end
 
+    # A reminder turn's origin: chi's own (system:reminder).
+    REMINDER_ORIGIN = TurnOrigin.new(client_id: ClientId::REMINDER)
+
     # :due when an idle parent should run a turn for its delegate
     # children's reports now (session.delegate_reports: wake): rings wait,
     # no continue offer does (they merge into its turn), wakes aren't paused
@@ -1107,13 +1112,13 @@ module Samagotchi
       # Every kind of turn merges steering (a reminder turn too, which may be
       # a fresh worker's first), so the list is this turn's from the start.
       @merged_this_turn = []
-      @reporting_turn = reports_to_parent?(turn_args[:origin])
+      origin = TurnOrigin.of(turn_args[:origin])
+      @reporting_turn = reports_to_parent?(origin)
       # A participant's review turn merges no input (#pending_input_drain).
-      @participant_turn = Steer.participant_author?(turn_args[:origin]&.dig(:author))
+      @participant_turn = origin.participant?
       restores = @turn_flow.restores
       begin
-        @checkpoint.begin_turn(prompt: prompt, enqueued_id: turn_args[:origin]&.dig(:enqueued_id),
-                               author: turn_author_fields(turn_args[:origin]))
+        @checkpoint.begin_turn(prompt: prompt, enqueued_id: origin.enqueued_id, author: turn_author_fields(origin))
         @session.status = Session::STATUS_RUNNING
         # A continue that moved this session to the chain's new link wrote
         # the new parent beside it (Session::PARENT_FILE): this turn's
@@ -1128,7 +1133,7 @@ module Samagotchi
         # (ReplyWait) tells a turn's end by last_turn.
         if @session.status == Session::STATUS_RUNNING
           @session.status = Session::STATUS_IDLE
-          @engine.record_last_turn(@session, "failed", 0, turn_args[:origin], { type: :turn_failed })
+          @engine.record_last_turn(@session, "failed", 0, origin, { type: :turn_failed })
           Log.warn(:worker, "turn_not_begun", error: e.class.name, msg: e.message)
         end
       ensure
@@ -1142,7 +1147,7 @@ module Samagotchi
       # no reply: its text is what came before its last tool calls, and a
       # wait (chi send --wait) gets the question instead.
       unless response.nil? || response.strip.empty? || @continue_offer.awaiting?
-        SessionInbox.write_output(@session_dir, response, enqueued_id: turn_args[:origin]&.dig(:enqueued_id))
+        SessionInbox.write_output(@session_dir, response, enqueued_id: origin.enqueued_id)
       end
       save_or_log(:turn) { save_session }
       # The reports the turn merged were read unless its end took the turn
@@ -1200,7 +1205,7 @@ module Samagotchi
     def reports_to_parent?(origin)
       return false unless @session.delegate?
 
-      @initial_turn || @owes_parent || !ClientId.human?(origin&.dig(:client_id))
+      @initial_turn || @owes_parent || !ClientId.human?(origin.client_id)
     end
 
     # The Engine published a question (after the question desk saved it).
@@ -1235,7 +1240,7 @@ module Samagotchi
     # or the restored ones, never the one without the other. A turn that
     # got somewhere stays instead (TurnFlow#prompt_turn_failed), with the
     # prompts it took: nothing goes back.
-    # @param prompts [Array<Array(String, Hash|nil, Array|nil)>] [prompt,
+    # @param prompts [Array<Array(String, TurnOrigin|nil, Array|nil)>] [prompt,
     #   origin, images] (a web client gets its image chips back)
     # @param error [Exception, nil] what failed: its one line stays in the
     #   conversation as a turn note
@@ -1245,7 +1250,7 @@ module Samagotchi
         next if @turn_flow.prompt_turn_failed(error: error) == :kept
 
         prompts.each do |prompt, origin, images|
-          restored = { type: :prompt_restored, prompt: prompt, origin: origin }
+          restored = { type: :prompt_restored, prompt: prompt, origin: origin.wire }
           restored[:images] = images unless Array(images).empty?
           @engine.announce(restored)
         end
@@ -1290,13 +1295,13 @@ module Samagotchi
             FileUtils.rm_f(claimed_file)
           end
         end
-        merged.each { |_prompt, origin| user_input(origin&.dig(:client_id)) }
+        merged.each { |_prompt, origin| user_input(origin.client_id) }
         # Delegate children's reports: never handed back on a failure
         # (their rings stay for the next turn), so not in @merged_this_turn.
         reports, mark = take_child_reports
         unless merged.empty? && reports.empty?
           @engine.announce(type: :input_merged, count: merged.size + reports.size,
-                           origins: merged.filter_map(&:last) + reports.map(&:origin))
+                           origins: (merged.map(&:last) + reports.map(&:origin)).filter_map(&:wire))
           @merged_this_turn.concat(merged)
         end
         # Each line keeps its sender (Steer.source_for_client): a chi send or
@@ -1315,12 +1320,12 @@ module Samagotchi
 
     # A participant's author fields (Engine#author_fields), {} for the owner.
     def turn_author_fields(origin)
-      Steer.participant_author?(origin&.dig(:author)) ? @engine.author_fields(origin[:author], session: @session) : {}
+      origin.participant? ? @engine.author_fields(origin.author, session: @session) : {}
     end
 
     def merged_line(prompt, origin)
       author = turn_author_fields(origin)
-      Steer::Line.new(text: prompt, source: Steer.source_for_client(origin&.dig(:client_id)),
+      Steer::Line.new(text: prompt, source: Steer.source_for_client(origin.client_id),
                       author: author[:author], author_name: author[:author_name])
     end
 

data/lib/samagotchi/worker_inbound.rb

@@ -12,6 +12,7 @@ require_relative "log"
 require_relative "session"
 require_relative "session_inbox"
 require_relative "steer"
+require_relative "turn_origin"
 require_relative "participants"
 require_relative "tools/task_record"
 require_relative "worker_wakes"
@@ -38,9 +39,11 @@ module Samagotchi
     # +no_interrupt+: an offer its turn makes keeps it for its continue
     # turn; +images+: its image refs ({file:, name:}); +delivery+: the wire
     # value the sender asked for ("queue", or nil for the default
-    # next_step).
+    # next_step); +origin+: a TurnOrigin (a Hash is read as one).
     Prompt = Data.define(:text, :origin, :no_interrupt, :images, :delivery) do
-      def initialize(text:, origin: nil, no_interrupt: false, images: [], delivery: nil) = super
+      def initialize(text:, origin: nil, no_interrupt: false, images: [], delivery: nil)
+        super(text:, origin: TurnOrigin.of(origin), no_interrupt:, images:, delivery:)
+      end
     end
 
     # A context wake turn to run: the ContextAbsorber::Delivery that woke
@@ -53,7 +56,7 @@ module Samagotchi
       # Whether the wake counts toward context.peer_turns: a peer's answer
       # that agrees closes the round and counts toward session.max_wakes only.
       def peer_turn? = peer? && !delivery.agreed
-      def origin = { client_id: "#{ClientId::CONTEXT_PREFIX}#{name}" }
+      def origin = TurnOrigin.new(client_id: "#{ClientId::CONTEXT_PREFIX}#{name}")
       # The plain note #unmark_wake puts back.
       def note = delivery.note
     end
@@ -65,7 +68,7 @@ module Samagotchi
     # finished task it runs for (the others finished with it are plain notes).
     TaskWake = Data.define(:id, :turn_id, :plain_note) do
       def name = "task #{Tools::TaskRecord.short_id(id)}"
-      def origin = { client_id: "#{ClientId::TASK_PREFIX}#{id}" }
+      def origin = TurnOrigin.new(client_id: "#{ClientId::TASK_PREFIX}#{id}")
       def note = plain_note
     end
 
@@ -192,7 +195,7 @@ module Samagotchi
     # running for a turn that won't run.
     # @return [Boolean] whether it was one
     def initial_command?(prompt)
-      return false unless queue_as_command(prompt, nil)
+      return false unless queue_as_command(prompt, TurnOrigin::NONE)
 
       @session.status = Session::STATUS_IDLE
       save(:initial_command, unless_stopped: true)
@@ -246,14 +249,14 @@ module Samagotchi
     def queue_as_command(text, origin, after_file = nil)
       return false unless @engine.command_registry.command?(text.to_s)
 
-      if (author = Steer.sender_author(origin&.dig(:author)))
-        Log.warn(:worker, "participant_command_refused", participant: author)
-        Participants.log(@session.id, :refused, state_dir: @state_dir, participant: author.delete_prefix("p:"),
+      if origin.participant?
+        Log.warn(:worker, "participant_command_refused", participant: origin.participant_author)
+        Participants.log(@session.id, :refused, state_dir: @state_dir, participant: origin.participant_id,
                                                 what: "command", reason: "not_permitted")
         return true
       end
 
-      @queue_command.call(text, origin&.dig(:client_id), after_file, origin&.dig(:enqueued_id))
+      @queue_command.call(text, origin.client_id, after_file, origin.enqueued_id)
       true
     end