samagotchi 0.104.0 → 0.106.0

data/lib/samagotchi/testing/host.rb

@@ -51,7 +51,8 @@ module Samagotchi
           load_tools: ->(names, bundle) { recorder.load_tools(names, bundle) },
           cancel_controller: ->(handler: false) { recorder[:cancelled] ? stopped : nil },
           cost: -> { cost(recorder[:cost]) },
-          usage: -> { usage(recorder[:usage]) }
+          usage: -> { usage(recorder[:usage]) },
+          turn_author: -> { recorder[:turn_author] }
         )
       end
 
@@ -119,7 +120,8 @@ module Samagotchi
           ask_user: ->(question) { recorder.ask_user(question) },
           stop_turn: ->(reason:, hook:) { recorder.stop(:turn, reason, hook) },
           steer: ->(text:, hook:) { recorder.steer(text, hook) },
-          stop_generation: ->(reason:, hook:) { recorder.stop(:generation, reason, hook) }
+          stop_generation: ->(reason:, hook:) { recorder.stop(:generation, reason, hook) },
+          turn_author: -> { recorder[:turn_author] }
         )
       end
     end

data/lib/samagotchi/testing/recorder.rb

@@ -41,7 +41,9 @@ module Samagotchi
         # ctx.usage: nil (zero), a Hash of the parts (turns:, tool_calls:,
         # tool_calls_by_tool:, steps:, active_ms:, tool_ms_by_tool:) or a
         # callable giving one.
-        usage: nil
+        usage: nil,
+        # ctx.turn_author and the hooks' author: (a participant's "p:<id>"), nil for the owner.
+        turn_author: nil
       }.freeze
 
       attr_reader :notices, :cards, :steers, :stops, :questions, :model_requests, :toolkit_uses, :tool_loads, :answers,

data/lib/samagotchi/toolkit.rb

@@ -62,6 +62,9 @@ module Samagotchi
     FULL = "full"
     LEAN = "lean"
     CHILD = "child"
+    # A participant's turn (Guardrails::ReviewBoundary): the name is
+    # reserved, so config and plugins can't redefine the boundary.
+    REVIEW = "review"
 
     # A name that can't be resolved (unknown, a cycle).
     class Unresolved < StandardError; end
@@ -140,13 +143,20 @@ module Samagotchi
       ask_user_question web_fetch context_read
     ].freeze
 
+    # The built-ins a participant's turn may call (REVIEW): reads only.
+    # ReviewBoundary denies everything else, whatever the session declares
+    # (D3: the declared tools stay the session's), the forget layer's
+    # forget_outputs too (a layer tool, declared with every kit).
+    REVIEW_TOOLS = %w[read memory_read].freeze
+
     BUILTIN_KITS = [
       Kit.new(name: FULL, tools: :all),
       Kit.new(name: LEAN, tools: LEAN_TOOLS),
       # A delegate child: it reports to its parent (send_note; the
       # delegated-by line names it) and leaves memory writes to it, and
       # starts no children of its own (removed: not even through call_tool).
-      Kit.new(name: CHILD, base: LEAN, add: %w[send_note], remove: %w[memory_write delegate delegate_result])
+      Kit.new(name: CHILD, base: LEAN, add: %w[send_note], remove: %w[memory_write delegate delegate_result]),
+      Kit.new(name: REVIEW, tools: REVIEW_TOOLS)
     ].to_h { |kit| [kit.name, kit] }.freeze
 
     # What a toolkit declares, the Registry's filter: every built-in
@@ -256,12 +266,18 @@ module Samagotchi
       base.changed(add: kit.add, remove: kit.remove).with(name: name, prompt: prompt.to_s.empty? ? nil : prompt)
     end
 
+    # config.yml's toolkit.kits.review, refused: the review kit is the
+    # participants' boundary, which config may not widen.
+    RESERVED_REVIEW = "toolkit.kits.review: review is reserved for participants' turns (chi share); " \
+                      "name your kit something else"
+
     # The keys a config kit entry takes.
     KIT_KEYS = %w[base add remove prompt].freeze
 
     # The kits known: the built-ins, then config's toolkit.kits, then the
     # plugins' (chi.toolkit). A config kit with a built-in's name is left
-    # out (one it can't redefine) with a line in +errors+, and so is one
+    # out (one it can't redefine; review, the participants' boundary, is
+    # reserved) with a line in +errors+, and so is one
     # that isn't a {base:, add:, remove:, prompt:} map. One with another key
     # (a typo, a tools: list) still loads, with a line naming the key, and
     # so does one whose prompt isn't text or is over PROMPT_MAX characters:
@@ -274,7 +290,9 @@ module Samagotchi
       kits = BUILTIN_KITS.dup
       (config.is_a?(Hash) ? config : {}).each do |name, spec|
         name = name.to_s
-        if kits.key?(name)
+        if name == REVIEW
+          errors << RESERVED_REVIEW
+        elsif kits.key?(name)
           errors << "toolkit.kits.#{name}: #{name} is a built-in toolkit"
         elsif !spec.is_a?(Hash)
           errors << "toolkit.kits.#{name}: expected {base:, add:, remove:, prompt:}"

data/lib/samagotchi/turn_checkpoint.rb

@@ -159,13 +159,16 @@ module Samagotchi
     # Every mark of the turn carries +enqueued_id+ (InterruptedTurn's).
     # @param prompt [String, nil]
     # @param enqueued_id [String, nil] the input the turn runs
-    def begin_turn(prompt: nil, enqueued_id: nil)
+    # @param author [Hash] a participant's prompt's author fields
+    #   (Engine#author_fields), so a kill before the first boundary leaves
+    #   it theirs; {} for the owner's
+    def begin_turn(prompt: nil, enqueued_id: nil, author: {})
       @boundaries = 0
       @enqueued_id = enqueued_id.to_s.empty? ? nil : enqueued_id.to_s
       @written_at = nil
       @started_at = Time.now.iso8601(3)
       messages = Array(@session.messages).dup
-      messages << { role: "user", content: prompt } unless prompt.to_s.empty?
+      messages << { role: "user", content: prompt, **author } unless prompt.to_s.empty?
       @session.turn_checkpoint = { messages: messages, marker: InterruptedTurn.new(started_at: @started_at, at: @started_at, iteration: 0,
                                                                                    enqueued_id: @enqueued_id) }
     end

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.104.0"
+  VERSION = "0.106.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end

data/lib/samagotchi/web/app.rb

@@ -55,6 +55,7 @@ require_relative "session_summary"
 require_relative "session_access_routes"
 require_relative "principal"
 require_relative "participant_access"
+require_relative "participant_review"
 require_relative "../log"
 require_relative "../paths"
 require_relative "../redacted_inspect"
@@ -73,6 +74,7 @@ module Samagotchi
       include RedactedInspect
       include SessionAccessRoutes
       include ParticipantAccess
+      include ParticipantReview
 
       DEFAULT_HOST = BridgeClient::HOST
       BRIDGE_WAIT_TIMEOUT = 10.0
@@ -191,25 +193,26 @@ module Samagotchi
         ["GET", %r{\A/(?:index\.html)?\z}, :serve_index, :participant],
         ["GET", %r{\A/api/sessions\z}, :handle_list, :owner],
         ["POST", %r{\A/api/sessions\z}, :handle_create, :owner],
-        ["GET", %r{\A/api/sessions/resolve\z}, :handle_resolve, :owner],
+        ["GET", %r{\A/api/sessions/resolve\z}, :handle_resolve, :participant],
         ["GET", %r{\A/api/sessions/summaries\z}, :handle_summaries, :owner],
         ["GET", %r{\A/api/info\z}, :handle_info, :participant],
         ["GET", %r{\A/api/models\z}, :handle_models, :owner],
         ["GET", %r{\A/api/history\z}, :handle_history, :owner],
         ["GET", %r{\A/api/events\z}, :handle_events, :owner],
         ["POST", %r{\A/api/render\z}, :handle_render, :owner],
-        ["GET", %r{\A/api/sessions/([^/]+)/stream\z}, :handle_stream, :owner],
+        ["GET", %r{\A/api/sessions/([^/]+)/stream\z}, :handle_stream, :participant],
+        ["GET", %r{\A/api/sessions/([^/]+)/review\z}, :handle_review, :participant, :session],
         ["GET", %r{\A/api/sessions/([^/]+)/output\z}, :handle_output, :owner, :session],
         ["POST", %r{\A/api/sessions/([^/]+)/cancel\z}, :handle_cancel, :owner, :session],
         ["POST", %r{\A/api/sessions/([^/]+)/tasks/([^/]+)/stop\z}, :handle_task_stop, :owner, :session],
-        ["POST", %r{\A/api/sessions/([^/]+)/turn/([^/]+)/dequeue\z}, :handle_dequeue_turn, :owner, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/turn/([^/]+)/dequeue\z}, :handle_dequeue_turn, :participant, :session],
         ["POST", %r{\A/api/sessions/([^/]+)/stop\z}, :handle_stop, :owner, :session],
         ["POST", %r{\A/api/sessions/([^/]+)/restart\z}, :handle_restart, :owner, :session],
         ["POST", %r{\A/api/sessions/([^/]+)/archive\z}, :handle_archive, :owner, :session],
         ["POST", %r{\A/api/sessions/([^/]+)/unarchive\z}, :handle_unarchive, :owner, :session],
-        ["POST", %r{\A/api/sessions/([^/]+)/turn\z}, :handle_turn, :owner, :session],
-        ["POST", %r{\A/api/sessions/([^/]+)/wait/prepare\z}, :handle_wait_prepare, :owner, :session],
-        ["POST", %r{\A/api/sessions/([^/]+)/wait\z}, :handle_wait, :owner, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/turn\z}, :handle_turn, :participant, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/wait/prepare\z}, :handle_wait_prepare, :participant, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/wait\z}, :handle_wait, :participant, :session],
         ["POST", %r{\A/api/sessions/([^/]+)/notes\z}, :handle_notes, :owner, :session],
         ["POST", %r{\A/api/sessions/([^/]+)/wake\z}, :handle_wake, :owner, :session],
         ["GET", %r{\A/api/sessions/([^/]+)/worker\z}, :handle_worker, :owner, :session],
@@ -232,6 +235,7 @@ module Samagotchi
         ["GET", %r{\A/api/sessions/([^/]+)/participants\z}, :handle_participants_list, :owner, :session],
         ["POST", %r{\A/api/sessions/([^/]+)/participants\z}, :handle_participants_invite, :owner, :session],
         ["DELETE", %r{\A/api/sessions/([^/]+)/participants\z}, :handle_participants_revoke, :owner, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/participants/([^/]+)/cap\z}, :handle_participants_cap, :owner, :session],
         ["GET", %r{\A/api/participants\z}, :handle_participants_list, :owner],
         ["DELETE", %r{\A/api/participants\z}, :handle_participants_revoke, :owner],
         ["GET", %r{\A/api/sessions/([^/]+)\z}, :handle_show, :participant, :session],
@@ -262,7 +266,7 @@ module Samagotchi
             return error_response(404, "not_found", "Session not found: #{m.captures.first.to_s[0, 80]}")
           end
 
-          return session_route { send(handler, req, *m.captures) } if kind == :session
+          return session_route(principal) { send(handler, req, *m.captures) } if kind == :session
 
           return send(handler, req, *m.captures)
         end
@@ -271,17 +275,24 @@ module Samagotchi
         serve_static(req)
       rescue StandardError => e
         Log.exception(:web, "request_failed", e, method: env["REQUEST_METHOD"], path: env["PATH_INFO"])
-        error_response(500, "internal_error", e.message)
+        # A participant never reads an exception's words (they may name a
+        # host path): the log has them.
+        error_response(500, "internal_error", owner_env?(env) ? e.message : "chi web failed on this request")
       end
 
+      # Whether the request's principal is the owner (none yet: the gate
+      # didn't pass, so not a participant either).
+      def owner_env?(env) = env[PRINCIPAL_ENV].nil? || env[PRINCIPAL_ENV].owner?
+
       # A :session route's handler: the ArgumentError its session lookup
       # raises (Session.load, the manager's find) is a 404 not_found with
       # its message. Only these routes: elsewhere an ArgumentError is a bug,
       # #route's 500. A handler's own rescues run first.
-      def session_route
+      def session_route(principal = nil)
         yield
       rescue ArgumentError => e
-        error_response(404, "not_found", e.message)
+        # A participant's 404 never carries the lookup's words (a path).
+        error_response(404, "not_found", principal.nil? || principal.owner? ? e.message : "Session not found")
       end
 
       # API requests at debug level (not the page and its assets): method,
@@ -1517,6 +1528,9 @@ module Samagotchi
         unless body.is_a?(Hash)
           return error_response(400, "invalid_json", "invalid JSON body")
         end
+        # A participant's review turn: its own path, which takes from the
+        # body only the prompt (ParticipantAccess#handle_participant_turn).
+        return handle_participant_turn(req, id, body) unless principal(req).owner?
 
         prompt = body["prompt"] || body[:prompt]
         client_id = body["client_id"] || body[:client_id]
@@ -1698,6 +1712,13 @@ module Samagotchi
         @session_class.load(id, state_dir: default_state_dir)
         parsed = parse_json(request_body(req))
         client_id = (parsed["client_id"] if parsed.is_a?(Hash))
+        # A participant takes back only their own queued turns, by chi web's
+        # record of who sent each (never a body's client id).
+        unless (who = principal(req)).owner?
+          return not_permitted_for(req, who) unless own_turn?(who.grant, id, enqueued_id)
+
+          client_id = ClientId.review(who.grant.id)
+        end
 
         request = ->(client) { client.dequeue(enqueued_id: enqueued_id, client_id: client_id) }
         relay(id, bridge_client(id), request, what: "the message was not removed", cant: "remove queued messages") do |reply|
@@ -2037,18 +2058,20 @@ module Samagotchi
       # the session's Bridge stream, through the request principal's frame
       # filter (#stream_filter).
       def proxy_stream_body(id, req, port)
-        ProxyStreamBody.new(host: DEFAULT_HOST, port: port, session_id: id, query: stream_query(req), headers: req.env,
-                            server_running: stream_running(principal(req)), filter: stream_filter(principal(req)))
+        query = participant_view?(req) ? participant_stream_query(req) : stream_query(req)
+        ProxyStreamBody.new(host: DEFAULT_HOST, port: port, session_id: id, query: query, headers: req.env,
+                            server_running: stream_running(principal(req)), filter: stream_filter(req, id))
       end
 
-      # What a principal's stream goes through on its way from the Bridge:
-      # nil, the raw bytes unchanged, for the owner (the only principal
-      # today). A filter is anything with #call(chunk) -> String (nil or
-      # "" sends nothing); see ProxyStreamBody.
-      def stream_filter(principal)
-        return nil if principal.owner?
+      # What a request's stream goes through on its way from the Bridge:
+      # nil, the raw bytes unchanged, for the owner; a participant's (and
+      # the owner's ?as=participant, the participant view) goes through
+      # ParticipantStreamFilter. A filter is anything with #call(chunk) ->
+      # String (nil or "" sends nothing); see ProxyStreamBody.
+      def stream_filter(req, id)
+        return nil unless participant_view?(req)
 
-        raise ArgumentError, "no stream filter for a #{principal.kind} principal"
+        participant_stream_filter(req, id)
       end
 
       # GET /api/events: the session list as one SSE stream per tab. The
@@ -2169,7 +2192,7 @@ module Samagotchi
       end
 
       def serve_index(req)
-        return participant_page(principal(req)) unless principal(req).owner?
+        return participant_shell(req) if participant_view?(req)
 
         path = File.join(@public_dir, "index.html")
         if File.file?(path)
@@ -2467,6 +2490,8 @@ module Samagotchi
           # record by this, not by its place.
           turn_id = m[:turn_id] || m["turn_id"]
           message[:turn_id] = turn_id.to_s if norm_role == "user" && turn_id
+          # A participant's message names them (the page's author badge).
+          message.merge!(Samagotchi::Steer.author_fields(m[:author] || m["author"], m[:author_name] || m["author_name"])) if norm_role == "user"
           images = m[:images] || m["images"]
           message[:images] = Array(images).map { |ref| ImageStore.symbolize(ref).slice(:file, :name, :width, :height) } if norm_role == "user" && images.is_a?(Array) && !images.empty?
           if norm_role == "assistant"

data/lib/samagotchi/web/grants.rb

@@ -7,6 +7,8 @@ require "securerandom"
 require "time"
 require "rack/utils"
 require_relative "../atomic_file"
+require_relative "../config"
+require_relative "../participant_name"
 require_relative "../session"
 require_relative "../redacted_inspect"
 
@@ -48,8 +50,19 @@ module Samagotchi
       KINDS = %w[human agent].freeze
       # The only role in v1: a reviewer reads and (P3) comments.
       ROLES = %w[reviewer].freeze
-      NAME_MAX = 64
+      NAME_MAX = ParticipantName::MAX
       ID_RE = /\Ap_[0-9a-f]{8}\z/
+      # D7: what a participant's turns (and the side calls they cause) may
+      # cost the owner, in dollars, unless chi share --cap says otherwise
+      # (config web.participants.cap); at most MAX_CAP.
+      DEFAULT_CAP = 2.0
+      MAX_CAP = 1000.0
+      # How many of a participant's turns may wait behind their running one
+      # (config web.participants.queue); at most MAX_QUEUE.
+      DEFAULT_QUEUE = 3
+      MAX_QUEUE = 20
+      # chi share --expires and config web.participants.expires: Nh or Nd.
+      EXPIRES_RE = /\A(\d+)([hd])\z/
 
       # The store's folder or file can be read by others (chi web refuses to
       # start), or a grant can't be made from what was given.
@@ -62,12 +75,23 @@ module Samagotchi
       # participant too: a turn they send is authored "p:<id>" (P3).
       # +revoked_by+ why it was revoked: "owner", "archive", "delete",
       # "gone" (the session was pruned).
+      # +cap+ (dollars) and +queue+ (turns waiting) as issued; nil in a
+      # grant from before them, which takes the config's (#spend_cap,
+      # #queue_limit).
       Grant = Data.define(:id, :session_id, :digest, :kind, :name, :role, :created_at, :expires_at, :revoked_at,
-                          :revoked_by, :last_used_at) do
+                          :revoked_by, :last_used_at, :cap, :queue) do
+        def initialize(cap: nil, queue: nil, **) = super
+
         def self.from_h(hash)
           new(**members.to_h { |key| [key, hash[key.to_s]] })
         end
 
+        # The dollars this participant may cost the owner.
+        def spend_cap = cap.is_a?(Numeric) ? cap.to_f : Grants.default_cap
+
+        # How many of their turns may wait behind their running one.
+        def queue_limit = queue.is_a?(Integer) ? queue : Grants.default_queue
+
         # The author a participant's turn carries (Principal#author).
         def author = "p:#{id}"
 
@@ -93,7 +117,7 @@ module Samagotchi
         def public_h(now)
           { id: id, session_id: session_id, kind: kind, name: name, role: role, created_at: created_at,
             expires_at: expires_at, revoked_at: revoked_at, revoked_by: revoked_by, last_used_at: last_used_at,
-            state: state(now).to_s }
+            state: state(now).to_s, cap: spend_cap, queue: queue_limit }
         end
 
         def to_store = to_h.transform_keys(&:to_s)
@@ -117,13 +141,45 @@ module Samagotchi
 
       def self.digest(token) = Digest::SHA256.hexdigest(token.to_s)
 
+      # Seconds for +words+ (Nh or Nd, 1 hour to MAX_TTL), nil for none,
+      # false for words that aren't that.
+      def self.parse_ttl(words)
+        return nil if words.nil?
+
+        match = EXPIRES_RE.match(words.to_s.strip) or return false
+        seconds = match[1].to_i * (match[2] == "h" ? 3600 : DAY)
+        seconds.between?(3600, MAX_TTL) ? seconds : false
+      end
+
+      # A new grant's lifetime: config web.participants.expires, else
+      # DEFAULT_TTL (a value that isn't Nh/Nd in range too).
+      def self.default_ttl
+        parse_ttl(Config.get("web.participants.expires")) || DEFAULT_TTL
+      end
+
+      # A grant's cap without its own: config web.participants.cap, else
+      # DEFAULT_CAP (a value out of range too).
+      def self.default_cap
+        value = Config.get("web.participants.cap")
+        cap?(value) ? value.to_f : DEFAULT_CAP
+      end
+
+      # A grant's queue limit without its own: config
+      # web.participants.queue, else DEFAULT_QUEUE.
+      def self.default_queue
+        value = Config.get("web.participants.queue")
+        value.is_a?(Integer) && value.between?(0, MAX_QUEUE) ? value : DEFAULT_QUEUE
+      end
+
+      def self.cap?(value) = value.is_a?(Numeric) && value.to_f.finite? && value.to_f.between?(0, MAX_CAP)
+
       def self.token?(value) = value.is_a?(String) && value.start_with?(PREFIX)
 
       # One line, at most NAME_MAX characters, no brackets (a name can't
-      # forge P3's "[Review contribution from …]" header).
+      # forge the "[Review contribution from …]" header; ParticipantName).
       # @raise [Invalid] nothing left
       def self.clean_name(name)
-        clean = name.to_s.gsub(/[[:cntrl:]\[\]]/, " ").squeeze(" ").strip[0, NAME_MAX].to_s.strip
+        clean = ParticipantName.clean(name)
         raise Invalid, "a participant needs a name" if clean.empty?
 
         clean
@@ -161,14 +217,18 @@ module Samagotchi
       def now = @clock.call
 
       # A new grant for +session_id+, written before the token is handed out.
-      # @param ttl [Integer] seconds (DEFAULT_TTL; at most MAX_TTL)
+      # @param ttl [Integer, nil] seconds (nil: Grants.default_ttl; at most MAX_TTL)
+      # @param cap [Numeric, nil] dollars (nil: Grants.default_cap)
       # @return [Issued]
       # @raise [Invalid]
-      def issue(session_id:, name:, kind: "human", role: "reviewer", ttl: DEFAULT_TTL)
+      def issue(session_id:, name:, kind: "human", role: "reviewer", ttl: nil, cap: nil)
         Session.check_id!(session_id)
+        ttl ||= Grants.default_ttl
+        cap = Grants.default_cap if cap.nil?
         raise Invalid, "kind is human or agent, not #{kind}" unless KINDS.include?(kind)
         raise Invalid, "role is reviewer, not #{role}" unless ROLES.include?(role)
         raise Invalid, "a grant lasts 1 hour to 30 days" unless ttl.is_a?(Integer) && ttl.between?(3600, MAX_TTL)
+        raise Invalid, CAP_RANGE unless Grants.cap?(cap)
 
         clean = Grants.clean_name(name)
         token = "#{PREFIX}#{SecureRandom.urlsafe_base64(BYTES)}"
@@ -177,7 +237,7 @@ module Samagotchi
           id = fresh_id(grants)
           grant = Grant.new(id: id, session_id: session_id, digest: Grants.digest(token), kind: kind, name: clean,
                             role: role, created_at: stamp(issued), expires_at: stamp(issued + ttl), revoked_at: nil,
-                            revoked_by: nil, last_used_at: nil)
+                            revoked_by: nil, last_used_at: nil, cap: cap.to_f, queue: Grants.default_queue)
           [grants + [grant], Issued.new(grant: grant, token: token)]
         end
       end
@@ -230,6 +290,27 @@ module Samagotchi
         end
       end
 
+      CAP_RANGE = "a cap is $0 to $#{MAX_CAP.to_i}".freeze
+
+      # Sets the active grant +id+'s cap to +cap+ dollars.
+      # @return [Grant, nil] the changed grant; nil when +id+ isn't an
+      #   active grant (of +session_id+, when given)
+      # @raise [Invalid] a cap out of range
+      def set_cap(id, cap, session_id: nil)
+        raise Invalid, CAP_RANGE unless Grants.cap?(cap)
+
+        at = now
+        update do |grants|
+          changed = nil
+          grants = grants.map do |grant|
+            next grant unless grant.id == id && grant.active?(at) && (session_id.nil? || grant.session_id == session_id)
+
+            changed = grant.with(cap: cap.to_f)
+          end
+          [grants, changed]
+        end
+      end
+
       # Records a use of grant +id+, at most once per TOUCH_INTERVAL.
       def touch(id)
         at = now