samagotchi 0.121.1 → 0.122.0

data/lib/samagotchi/toolkit_report_command.rb

@@ -0,0 +1,318 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+require_relative "cli/command"
+require_relative "cli/exit"
+require_relative "cli/flags"
+require_relative "config"
+require_relative "session"
+require_relative "system_one/log"
+require_relative "toolkit"
+require_relative "tool_response"
+require_relative "toolkit_suggest"
+
+module Samagotchi
+  # `chi toolkit report`: compare the toolkit on mode would have run (the
+  # suggestion when it would have been applied, else the default) with the
+  # tools the session called from that turn on, against every kit's rules
+  # the ask logged (ToolkitSuggest.rules).
+  class ToolkitReportCommand
+    include CLI::Command
+
+    USAGE = <<~TEXT
+      Usage: chi toolkit report [--days N]
+        Grade the kit each audit suggestion would have run (the suggested
+        kit when on mode would have applied it, else the default) against
+        the tools the session called from that turn on, call_tool targets
+        included: covers, short of a tool (named), wider than needed (a
+        narrower offered kit would also cover), or ungradable. Then a
+        per-kit tally with what on mode would have done. Includes archived
+        sessions; the report is limited to 14 days and 500 sessions.
+    TEXT
+
+    MAX_DAYS = 14
+    MAX_SESSIONS = 500
+    FLAGS = CLI::Flags.new(args: false) { |flags| flags.value "--days" }.freeze
+    ToolUse = Data.define(:name, :group, :label)
+
+    # @param argv [Array<String>] arguments after "toolkit"
+    # @param sessions_dir [String, nil] sessions location (a spec seam)
+    # @param log [SystemOne::Log, nil] suggestion log (a spec seam)
+    # @param now [Time] the report's clock (a spec seam)
+    def initialize(argv, stdout: $stdout, stderr: $stderr, sessions_dir: nil, log: nil, now: Time.now)
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+      @sessions_dir = sessions_dir || Session.default_state_dir
+      @log = log
+      @now = now
+    end
+
+    def run
+      @sub = @argv.first
+      if @sub.nil? || HELP_WORDS.include?(@sub)
+        @stdout.puts(USAGE)
+        return CLI::Exit::OK
+      end
+      return usage_error("unknown subcommand #{@sub}") unless @sub == "report"
+
+      parsed = parse_flags(FLAGS, @argv[1..])
+      return parsed if parsed.is_a?(Integer)
+      return usage_error("--days takes a positive whole number") if parsed.options[:days] &&
+                                                                    !parsed.options[:days].to_s.match?(/\A[1-9]\d*\z/)
+
+      report(parsed.options[:days] ? Integer(parsed.options[:days], 10) : MAX_DAYS)
+    end
+
+    private
+
+    def command_name = "chi toolkit report"
+
+    def report(requested_days)
+      days = effective_days(requested_days)
+      cutoff = @now - (days * 86_400)
+      max_sessions = [MAX_SESSIONS, positive_config("session.max_count", MAX_SESSIONS)].min
+      sessions = Session.list(state_dir: @sessions_dir, sort: "updated_at", order: "desc",
+                              limit: max_sessions, include_archived: true)
+      session_summaries = sessions.to_h { |session| [session.id, session] }
+      records = log.records.filter_map do |entry|
+        next unless entry["kind"] == "suggestion" && session_summaries.key?(entry["session_id"])
+        next unless timestamp(entry["at"])&.>= cutoff
+
+        entry
+      end
+      if records.empty?
+        @stdout.puts("No toolkit suggestions in the last #{days} days.")
+        return CLI::Exit::OK
+      end
+
+      loaded = {}
+      tallies = Hash.new { |hash, kit| hash[kit] = Hash.new(0) }
+      @stdout.puts("Toolkit suggestions · last #{days} days · up to #{max_sessions} sessions")
+      records.sort_by { |entry| timestamp(entry["at"]) }.each do |entry|
+        id = entry["session_id"]
+        session = loaded[id] ||= Session.load(id, state_dir: @sessions_dir)
+        uses, window = window_uses(session, entry["turn_number"].to_i)
+        kit = graded_kit(entry)
+        grade, detail = grade(entry, kit, uses)
+        tallies[kit][grade] += 1
+        tallies[kit]["would:#{entry["would"] || "unknown"}"] += 1
+        confidence = entry["confidence"].nil? ? "n/a" : format("%.2f", entry["confidence"])
+        @stdout.puts("#{timestamp(entry["at"]).iso8601} #{id[0, 8]} turn #{entry["turn_number"]}: " \
+                     "#{entry["raw"] || "no judgment"} (p=#{confidence}, would #{entry["would"] || "unknown"}) " \
+                     "→ #{kit}: #{grade}#{detail}#{window}")
+        labels = uses.is_a?(Array) ? uses.map(&:label).uniq : []
+        @stdout.puts("  tools: #{labels.join(", ")}") unless labels.empty?
+      rescue StandardError => e
+        @stderr.puts("chi toolkit report: session #{id}: #{e.class}: #{e.message}; skipped")
+      end
+      print_tallies(tallies)
+      CLI::Exit::OK
+    end
+
+    def log
+      @log ||= SystemOne::Log.new(
+        dir: File.dirname(ToolkitSuggest.log_path(@sessions_dir)),
+        file: ToolkitSuggest::FILE,
+        warn: ->(reason) { @stderr.puts("chi toolkit report: #{reason}") }
+      )
+    end
+
+    def effective_days(requested)
+      retention = Config.get("session.retention_days").to_i
+      cap = retention.positive? ? [retention, MAX_DAYS].min : MAX_DAYS
+      [requested, cap].min
+    end
+
+    def positive_config(key, fallback)
+      value = Config.get(key).to_i
+      value.positive? ? value : fallback
+    end
+
+    def timestamp(value)
+      Time.iso8601(value.to_s)
+    rescue ArgumentError
+      nil
+    end
+
+    # The tools the session called from the suggestion's turn on: to the
+    # session's end, or only that turn when the toolkit was chosen since
+    # (/toolkit, ctx.use_toolkit: no message marks when, and a change
+    # applies from the next turn's start, so the asked turn ran on it).
+    # @return [Array(Array<ToolUse>|Symbol, String)] the uses (:ungradable
+    #   when a turn's tools can't be read back) and a note on the window
+    def window_uses(session, turn_number)
+      by_turn = tool_uses_by_turn(session.messages)
+      changed = session.toolkit_origin == "chosen"
+      turns = by_turn.keys.select { |number| changed ? number == turn_number : number >= turn_number }
+      uses = turns.sort.flat_map { |number| by_turn[number] }
+      note = changed ? " (its turn only: the toolkit was chosen later)" : ""
+      [turns.empty? || uses.include?(:ungradable) ? :ungradable : uses, note]
+    end
+
+    # Tool uses grouped by the user's own prompt number; steers and merged
+    # input lines remain part of that turn rather than starting another.
+    # The chat loop saves its calls on the model's message (tool_calls);
+    # the raw-prompt loop saves only the model's text, so its calls are
+    # read back from the batch's tool_response entry (#joined_uses).
+    def tool_uses_by_turn(messages)
+      number = 0
+      current = nil
+      uses = Hash.new { |hash, key| hash[key] = [] }
+      Array(messages).each do |message|
+        case field(message, :role).to_s
+        when "user"
+          if ToolkitSuggest.owner_prompt?(message)
+            number += 1
+            current = number
+            uses[current]
+          elsif Steer.participant_author?(field(message, :author))
+            current = nil
+          end
+        when "model"
+          Array(field(message, :tool_calls)).each { |call| uses[current] << tool_use(call) } if current
+        when "tool_response"
+          uses[current].concat(joined_uses(message)) if current && !field(message, :tool_call_id)
+        end
+      end
+      uses.transform_values(&:compact)
+    end
+
+    # A ran-as line (ToolRunner, a corrected call) may precede a run's lead.
+    RUN_LEAD = /\A(?:ran as: [^\n]*\n)?\[([^\]\s]+)\](?:\n| |\z)/
+
+    # A raw-prompt batch's tools: each run's "[name]" lead (ToolResponse),
+    # a call_tool's target from its saved params line ("group/tool …").
+    # When the leads don't match the batch's run count, :ungradable.
+    def joined_uses(message)
+      parts = field(message, :content).to_s.split(ToolResponse::SEPARATOR, -1)
+      names = parts.filter_map { |part| part[RUN_LEAD, 1] }
+      ids = field(message, :tool_ids)
+      return [:ungradable] if names.empty? || (ids.is_a?(Array) && ids.size != names.size)
+
+      params = field(message, :tool_params)
+      names.each_with_index.map do |name, index|
+        next ToolUse.new(name: name, group: nil, label: name) unless name == "call_tool"
+
+        line = params.is_a?(Array) ? params[index] : nil
+        target = line.to_s.split(" ", 2).first.to_s
+        next :ungradable unless target.include?("/")
+
+        group, tool = target.split("/", 2)
+        ToolUse.new(name: tool, group: group, label: "call_tool→#{target}")
+      end
+    end
+
+    def tool_use(call)
+      return unless call.is_a?(Hash)
+
+      function = field(call, :function)
+      name = (field(call, :name) || field(function, :name)).to_s
+      arguments = field(call, :arguments) || field(function, :arguments) || field(call, :args)
+      arguments = JSON.parse(arguments) if arguments.is_a?(String) && !arguments.empty?
+      return ToolUse.new(name: name, group: nil, label: name) unless name == "call_tool"
+
+      target = arguments.is_a?(Hash) ? (field(arguments, :tool) || field(arguments, :name)) : nil
+      return :ungradable unless target
+
+      parts = target.to_s.split("/", 2)
+      group, tool = parts.size == 2 ? parts : [nil, parts.first]
+      ToolUse.new(name: tool, group: group, label: "call_tool→#{target}")
+    rescue JSON::ParserError
+      name == "call_tool" ? :ungradable : ToolUse.new(name: name, group: nil, label: name)
+    end
+
+    # The kit on mode would have run: the suggestion only when it would
+    # have been applied, else the session's default.
+    def graded_kit(entry)
+      name = entry["would"] == "suggested" ? entry["kit"] : entry["default_kit"]
+      name || "(unknown)"
+    end
+
+    # covers: the kit declares every tool the window used (pick ⊇ need);
+    # wider than needed: it covers, and so would a narrower logged kit;
+    # short of a tool: names what it leaves out. ungradable when the
+    # window's calls or the kit's rules can't be read.
+    def grade(entry, kit, uses)
+      kits = entry["kits"].is_a?(Hash) ? entry["kits"] : {}
+      rules = kits[kit]
+      core_tools = Array(entry["core_tools"])
+      return ["ungradable", " (no rules logged for #{kit})"] unless rules.is_a?(Hash)
+      return ["ungradable", " (tool calls not readable)"] if uses == :ungradable
+
+      missing = uses.reject { |use| covers?(rules, core_tools, use) }
+      return ["short of a tool", " (#{missing.map(&:name).uniq.join(", ")})"] unless missing.empty?
+
+      narrower = kits.filter_map do |name, other|
+        next if name == kit || !other.is_a?(Hash) || !narrower?(other, rules, core_tools)
+
+        name if uses.all? { |use| covers?(other, core_tools, use) }
+      end
+      return ["wider than needed", " (#{narrower.sort.join(", ")} would also cover)"] unless narrower.empty?
+
+      ["covers", ""]
+    end
+
+    # Whether a kit's rules declare +use+ (Toolkit::Resolved#declares?): a
+    # tool-index group by the kit's groups; a built-in by its core list;
+    # any other tool (a plugin's) unless the kit removes it.
+    def covers?(rules, core_tools, use)
+      return group_reached?(rules["groups"], use.group) if use.group && use.group != "chi"
+
+      removed = Array(rules["removed"])
+      return false if removed.include?(use.name)
+      return true unless core_tools.include?(use.name)
+
+      rules["all_core"] || Array(rules["core"]).include?(use.name) || Array(rules["added"]).include?(use.name)
+    end
+
+    def core_set(rules, core_tools)
+      declared = rules["all_core"] ? core_tools : Array(rules["core"]) + Array(rules["added"])
+      (declared & core_tools) - Array(rules["removed"])
+    end
+
+    # +other+ declares no more built-ins and reaches no more groups than
+    # +rules+, and less of one of them.
+    def narrower?(other, rules, core_tools)
+      mine = core_set(rules, core_tools)
+      theirs = core_set(other, core_tools)
+      return false unless (theirs - mine).empty?
+
+      groups_mine = rules["groups"]
+      groups_theirs = other["groups"]
+      groups_within = groups_mine == "all" || (groups_theirs != "all" && (Array(groups_theirs) - Array(groups_mine)).empty?)
+      return false unless groups_within
+
+      theirs.size < mine.size || (groups_mine == "all" && groups_theirs != "all") ||
+        (groups_theirs != "all" && Array(groups_theirs).size < Array(groups_mine).size)
+    end
+
+    def group_reached?(groups, group)
+      return true if ["all", :all].include?(groups)
+
+      Array(groups).any? { |selector| Toolkit.group_matches?([selector], group) }
+    end
+
+    GRADES = ["covers", "short of a tool", "wider than needed", "ungradable"].freeze
+
+    # Per graded kit: the grades, then what on mode would have done.
+    def print_tallies(tallies)
+      @stdout.puts("\nPer-kit")
+      @stdout.puts("kit | suggestions | #{GRADES.join(" | ")} | would")
+      tallies.sort.each do |kit, counts|
+        would = counts.select { |key, _| key.start_with?("would:") }.sort
+                      .map { |key, count| "#{key.delete_prefix("would:")} #{count}" }
+        @stdout.puts("#{kit} | #{GRADES.sum { |grade| counts[grade] }} | " \
+                     "#{GRADES.map { |grade| counts[grade] }.join(" | ")} | #{would.join(", ")}")
+      end
+    end
+
+    def field(hash, key)
+      return nil unless hash.is_a?(Hash)
+
+      hash.key?(key) ? hash[key] : hash[key.to_s]
+    end
+  end
+end

data/lib/samagotchi/toolkit_suggest.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "message_time"
+require_relative "steer"
+require_relative "system_one/question"
+
+module Samagotchi
+  # The first-prompt toolkit classifier and its append-only audit record.
+  # The Engine prepares a Snapshot on its turn thread; #ask only sees that
+  # copy, so the question cannot change the running session or tool registry.
+  class ToolkitSuggest
+    FILE = "toolkit_suggestions.jsonl"
+    QUESTION_ID = "toolkit"
+    PROMPT_MAX = 1500
+    CHARS_PER_TOKEN = 4.0
+    INSTRUCTIONS = "A user is starting a session of a coding agent with the prompt in the state. " \
+                   "Which toolkit should the session start on? Pick the smallest toolkit whose tools the work will need."
+
+    # A kit as the ask saw it: its name, classifier description and #rules.
+    Candidate = Data.define(:name, :description, :rules)
+    # +default+ is a Candidate (no description needed); +core_tools+ the
+    # built-ins registered when the ask started.
+    Snapshot = Data.define(:session_id, :turn_number, :default, :candidates, :core_tools, :state)
+    Suggestion = Data.define(:kit, :raw, :confidence, :decided)
+
+    # The candidates with classifier descriptions, excluding the configured
+    # default, the participants' review boundary, the defer sentinel, and a
+    # kit that doesn't resolve (a missing base, a cycle): it is left out,
+    # not the whole ask, and the ≥ 2 clause counts what is left.
+    def self.candidates(kits, default_name:)
+      kits.values.filter_map do |kit|
+        next if [default_name.to_s, Toolkit::REVIEW, "undecided"].include?(kit.name)
+        next if kit.description.to_s.empty?
+        next unless resolves?(kit.name, kits)
+
+        kit
+      end
+    end
+
+    def self.resolves?(name, kits)
+      Toolkit.resolve_kit(name, kits)
+      true
+    rescue Toolkit::Unresolved
+      false
+    end
+
+    # A System 1 choice and the small, bounded state it classifies.
+    def self.question(default:, kits:, project:, prompt:)
+      candidates = candidates(kits, default_name: default.name)
+      criteria = candidates.to_h { |kit| ["kit:#{kit.name}", "#{kit.name}: #{kit.description}"] }
+      criteria["default"] = "none of the other toolkits fits: the user's everyday default"
+      criteria["undecided"] = "There is no task yet; defer this choice"
+      question = SystemOne::Question.new(id: QUESTION_ID, type: :choice, instructions: INSTRUCTIONS, criteria: criteria)
+      [question, { project: project.to_s, prompt: prompt.to_s[0, PROMPT_MAX] }]
+    end
+
+    # The single turn eligibility predicate shared by audit and future on
+    # mode. A later prompt is eligible only inside an undecided defer window.
+    # +candidate_count+ and +last_suggestion+ may be callables: they are
+    # read only once the session's own clauses pass (the kits read memory
+    # files; the suggestion log is read whole), the log only on the defer
+    # path, when the session already has a model reply.
+    def self.eligible?(session:, prompt:, author:, candidate_count:, last_suggestion:, defer_turns:, defer_tokens:)
+      return false unless session&.toolkit_origin == "default"
+      return false if session.delegate? || session.review?
+      return false if Steer.participant_author?(author)
+      return false unless prompt.is_a?(String) && !prompt.strip.empty?
+      return false if value(candidate_count).to_i < 2
+
+      messages = Array(session.messages)
+      return true unless messages.any? { |message| field(message, :role).to_s == "model" }
+      return false unless field(value(last_suggestion), :raw) == "undecided"
+
+      current_turn_number = turn_number(messages)
+      current_turn_number <= defer_turns.to_i && conversation_chars(messages) / CHARS_PER_TOKEN < defer_tokens.to_i
+    end
+
+    # The conversation's size for the defer window: its messages' text and
+    # tool calls, summed (no JSON: a byte that isn't UTF-8 can't break it).
+    def self.conversation_chars(messages)
+      Array(messages).sum do |message|
+        field(message, :content).to_s.length + field(message, :tool_calls).to_s.length
+      end
+    end
+
+    def self.turn_number(messages) = user_prompt_count(Array(messages)) + 1
+
+    # The owner's own prompt: a user line the Engine kept for a turn (it
+    # carries the turn's id), or TurnCheckpoint's line for a turn killed
+    # before its first boundary (stamped, no id). A !command's output, a
+    # declined continue's reason and KernelLoop's recovery prompt are
+    # neither; steers, notes and reminders carry their kind.
+    def self.owner_prompt?(message)
+      field(message, :role).to_s == "user" &&
+        !Steer.participant_author?(field(message, :author)) &&
+        !%w[input steer note reminder].include?(field(message, :kind).to_s) &&
+        !field(message, :preserve_literals) &&
+        !(field(message, :turn_id) || field(message, MessageTime::KEY)).nil?
+    end
+
+    # The prior logged suggestion for this session; the log, not process
+    # memory, keeps a deferred choice alive across a worker respawn.
+    def self.last_suggestion(log, session_id)
+      log.records.reverse_each.find do |entry|
+        entry["kind"] == "suggestion" && entry["session_id"] == session_id
+      end
+    end
+
+    # Runs one already-prepared ask, then appends its raw pick, what on mode
+    # would have done, and every offered kit's #rules (the default's too),
+    # so the report can tell a narrower kit that would also have covered
+    # the turn. A missing judgment is recorded too.
+    def self.ask(client:, log:, snapshot:, threshold:)
+      question, = question(default: Toolkit.new(name: snapshot.default.name),
+                           kits: snapshot.candidates.to_h { |candidate| [candidate.name, kit_for(candidate)] },
+                           project: snapshot.state.fetch(:project), prompt: snapshot.state.fetch(:prompt))
+      answer = client.ask(state: snapshot.state, questions: { QUESTION_ID => question })&.fetch(QUESTION_ID, nil)
+      raw = answer&.choice
+      candidate_name = raw.to_s.delete_prefix("kit:")
+      candidate = snapshot.candidates.find { |item| item.name == candidate_name } if raw.to_s.start_with?("kit:")
+      selected = if raw == "default"
+                   snapshot.default.name
+                 elsif candidate
+                   candidate.name
+                 end
+      confidence = answer&.confidence
+      decided = raw == "default" || (candidate && confidence && confidence >= threshold.to_f)
+      would = if answer.nil?
+                "no_judgment"
+              elsif raw == "undecided"
+                "defer"
+              elsif raw == "default"
+                "default"
+              elsif candidate.nil?
+                "invalid"
+              elsif confidence.nil? || confidence < threshold.to_f
+                "below_threshold"
+              else
+                "suggested"
+              end
+      log.entry("suggestion", {
+        session_id: snapshot.session_id,
+        turn_number: snapshot.turn_number,
+        default_kit: snapshot.default.name,
+        raw: raw,
+        kit: selected,
+        confidence: confidence,
+        decided: !!decided,
+        would: would,
+        core_tools: snapshot.core_tools,
+        kits: [snapshot.default, *snapshot.candidates].to_h { |kit| [kit.name, kit.rules] }
+      })
+      Suggestion.new(kit: selected, raw: raw, confidence: confidence, decided: !!decided)
+    end
+
+    # A resolved kit (Toolkit::Resolved) as frozen, JSON-ready rules, not
+    # a tool list: plugin and MCP tools may still be loading when the ask
+    # starts, and every kit declares a non-core tool anyway
+    # (Resolved#declares?), so the report expands these against the tools
+    # a turn really called (ToolkitReportCommand).
+    # @return [Hash{String => Object}]
+    def self.rules(resolved)
+      {
+        "all_core" => resolved.all_core,
+        "core" => resolved.core.map { |name| name.to_s.dup.freeze }.freeze,
+        "added" => resolved.added.map { |name| name.to_s.dup.freeze }.freeze,
+        "removed" => resolved.removed.map { |name| name.to_s.dup.freeze }.freeze,
+        "groups" => resolved.groups == :all ? "all" : resolved.groups.map { |name| name.to_s.dup.freeze }.freeze
+      }.freeze
+    end
+
+    def self.log_path(sessions_dir)
+      File.join(File.dirname(sessions_dir), FILE)
+    end
+
+    def self.warn(error)
+      Log.warn(:toolkit, "toolkit_suggest_failed",
+               echo: "[samagotchi:toolkit] toolkit suggestion: #{error.class}: #{error.message}",
+               error: error.class.name, msg: error.message.to_s[0, 200])
+    end
+
+    class << self
+      private
+
+      def value(given) = given.respond_to?(:call) ? given.call : given
+
+      def field(hash, key)
+        return nil unless hash.is_a?(Hash)
+
+        hash.key?(key) ? hash[key] : hash[key.to_s]
+      end
+
+      def user_prompt_count(messages)
+        prompts = messages.filter_map do |message|
+          next unless owner_prompt?(message)
+
+          field(message, :turn_id) || message.object_id
+        end
+        prompts.uniq.size
+      end
+
+      # Reconstitute only the candidate metadata needed to build the question;
+      # names, descriptions and groups are copied from the Snapshot.
+      def kit_for(candidate)
+        Toolkit::Kit.new(name: candidate.name, description: candidate.description)
+      end
+    end
+  end
+end

data/lib/samagotchi/tools/memory.rb

@@ -95,7 +95,7 @@ module Samagotchi
       # "\nHint: …" when this project's memory folder looks orphaned
       # (MemoryOrphans), else "".
       def self.orphan_hint
-        message = MemoryOrphans.message
+        message = MemoryOrphans.model_message
         message ? "\nHint: #{message}" : ""
       end
 

data/lib/samagotchi/version.rb

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

data/lib/samagotchi/web/app.rb

@@ -1225,7 +1225,7 @@ module Samagotchi
       # (?full=1: as the list's).
       def handle_context_show(req, id, name)
         session = @session_class.load(id, state_dir: default_state_dir)
-        attached = find_context(session, name) or return error_response(404, "not_found", "no source #{name[0, 40]}")
+        attached = find_context(session, name) or return error_response(404, "context_missing", "no source #{name[0, 40]}")
         own = ContextSources.session_location(id, state_dir: default_state_dir)
         row = context_row(attached, own, own.subscriptions, full: truthy_param?(req.params["full"]))
         json_response(200, row.merge(text: attached.snapshot.text))
@@ -1305,7 +1305,7 @@ module Samagotchi
         return context_remove_own(id, name) if truthy_param?(req.params["own"])
 
         session = @session_class.load(id, state_dir: default_state_dir)
-        attached = find_context(session, name) or return error_response(404, "not_found", "no source #{name[0, 40]}")
+        attached = find_context(session, name) or return error_response(404, "context_missing", "no source #{name[0, 40]}")
         if attached.location.session?
           attached.location.remove(attached.name)
           json_response(200, { status: "detached", name: attached.name })
@@ -1320,10 +1320,10 @@ module Samagotchi
         when :removed then json_response(200, { status: "detached", name: name })
         when :project
           error_response(409, "project_source", ContextCommand.project_source_message(name))
-        else error_response(404, "not_found", "no source #{name[0, 40]}")
+        else error_response(404, "context_missing", "no source #{name[0, 40]}")
         end
       rescue ContextSources::Invalid
-        error_response(404, "not_found", "no source #{name[0, 40]}")
+        error_response(404, "context_missing", "no source #{name[0, 40]}")
       end
 
       def attached_context(session, shadowed: false)
@@ -1530,7 +1530,7 @@ module Samagotchi
       end
 
       def stream_open_error(id, outcome)
-        return error_response(503, "not_live", WorkerLink.not_live(id)) if outcome.is_a?(BridgeClient::StreamOpen::Unreachable)
+        return error_response(503, "not_live", WorkerLink.unanswered(id)) if outcome.is_a?(BridgeClient::StreamOpen::Unreachable)
         return error_response(503, "not_live", WorkerLink.not_live(id)) if outcome.reason == :unknown_session
         return error_response(502, "bridge_secret", BridgeSecret.refused(id)) if outcome.reason == :bridge_secret
 

data/lib/samagotchi/web/participant_access.rb

@@ -420,7 +420,10 @@ module Samagotchi
         result = session_access.wait_reply(id, **options, poll_interval: @wait_poll_interval,
                                                cancelled: -> { !@server_running.call || !@grants.active?(grant.id) })
         if result.status == :canceled
-          ended = @grants.find(grant.id)&.state(@grants.now)
+          current = @grants.find(grant.id)
+          return error_response(401, *ENDED.fetch(:revoked)) unless current
+
+          ended = current.state(@grants.now)
           return error_response(401, *ENDED.fetch(ended)) if ENDED.key?(ended)
 
           return error_response(503, "server_stopping", "chi web is stopping; wait again")

data/lib/samagotchi/web/participant_review.rb

@@ -6,6 +6,7 @@ require_relative "participant_exposure"
 require_relative "../session_metrics"
 require_relative "../review_start"
 require_relative "../guardrails/review_paths"
+require_relative "../participant_mode"
 
 module Samagotchi
   module Web
@@ -49,6 +50,7 @@ module Samagotchi
       #   current_turn, waiting_for_owner, queued: {mine, others}, last_event_id}
       def handle_review(req, id)
         session = @session_class.load(id, state_dir: default_state_dir)
+        mode = ParticipantMode.of(session).to_s
         viewer = participant_viewer(req, session)
         live = bridge_get_json(id, "snapshot")
         turn_snapshot = live && live["snapshot"]
@@ -63,7 +65,7 @@ module Samagotchi
         status = displayed_status(session, state)
         status = Session::STATUS_IDLE if status == Session::STATUS_RUNNING && current.nil?
         json_response(200, {
-          viewer: review_viewer(req, id, session: session, state: state, queued: queued, viewer: viewer),
+          viewer: review_viewer(req, id, session: session, state: state, queued: queued, viewer: viewer, mode: mode),
           session: { id: session.id, title: participant_title(session), status: status },
           subjects: review_subjects(session, viewer),
           participants: participant_names(id).map { |entry| entry.slice(:id, :name, :kind) },
@@ -149,12 +151,12 @@ module Samagotchi
       # participant view (no composer, no usage: the owner has /stats).
       # +state+ the live worker's session state (nil without one), +queued+
       # its queue.
-      def review_viewer(req, id, session:, state:, queued:, viewer:)
-        return { kind: "owner", can_comment: false } if principal(req).owner?
+      def review_viewer(req, id, session:, state:, queued:, viewer:, mode:)
+        return { kind: "owner", can_comment: false, mode: mode } if principal(req).owner?
 
         grant = principal(req).grant
         capped = !participant_cap_refusal(grant).nil?
-        { kind: "participant", id: grant.id, name: grant.name, participant_kind: grant.kind, can_comment: !capped,
+        { kind: "participant", id: grant.id, name: grant.name, participant_kind: grant.kind, mode: mode, can_comment: !capped,
           cap_reached: capped, session_id: id,
           usage: review_usage(grant, session: session, state: state, queued: queued, viewer: viewer) }
       end

data/lib/samagotchi/web/principal.rb

@@ -2,14 +2,13 @@
 
 module Samagotchi
   module Web
-    # Who a chi web request is (App#principal_for). Today there is one
-    # kind: the owner, a peer on this machine or a request with the
-    # Web::Token access token. The routes' permission column
+    # Who a chi web request is (App#principal_for): the owner or a
+    # participant admitted by a grant. The routes' permission column
     # (App::ROUTES, :owner or :participant) is checked against it, and a
     # turn's author comes from it, never from the request body. See
     # docs/internals/remote-sessions.md (Trust model).
     #
-    # +kind+ :owner; +grant+ what a non-owner principal was admitted by
+    # +kind+ :owner or :participant; +grant+ what admitted a participant
     # (nil for the owner).
     Principal = Data.define(:kind, :grant) do
       def owner? = kind == :owner