samagotchi 0.31.0 → 0.33.0

data/lib/samagotchi/tools/builtins.rb

@@ -18,6 +18,7 @@ require_relative "cancel_reminder"
 require_relative "list_reminders"
 require_relative "list_sessions"
 require_relative "send_note"
+require_relative "context_read"
 require_relative "delegate"
 require_relative "delegate_result"
 require_relative "ask_user_question"
@@ -50,6 +51,7 @@ module Samagotchi
         ListReminders,
         ListSessions,
         SendNote,
+        ContextRead,
         Delegate,
         DelegateResult,
         AskUserQuestion
@@ -92,6 +94,9 @@ module Samagotchi
         ListReminders::NAME => ->(call, kctx) { ListReminders.call(call[:content], reminder_store: kctx.reminder_store) },
         ListSessions::NAME => ->(call, kctx) { ListSessions.call(call[:content], peers: kctx.peers, cwd: call[:cwd]) },
         SendNote::NAME => ->(call, kctx) { SendNote.call(call[:content], session: call[:session], peers: kctx.peers) },
+        ContextRead::NAME => lambda do |call, kctx|
+          ContextRead.call(call[:content], offset: call[:offset], limit: call[:limit], peers: kctx.peers)
+        end,
         Delegate::NAME => lambda do |call, kctx|
           Delegate.call(call[:content], model: call[:model], session: call[:session], wait: call[:wait],
                                         timeout: call[:timeout], peers: kctx.peers)

data/lib/samagotchi/tools/context_read.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "../config"
+require_relative "../context_sources"
+require_relative "../project_scope"
+
+module Samagotchi
+  module Tools
+    # Read the session's attached context (ContextSources): without a name
+    # the list, with one its header and text, paged by lines when it is
+    # longer than max_tool_output_chars. It reads snapshots only (never
+    # runs a source's command) and records what was read, so the web can
+    # show a change the agent hasn't read.
+    class ContextRead
+      NAME = "context_read"
+      DEFAULT_MAX_CHARS = 10_000
+      # Room for the header and the paging line inside the cap.
+      HEADER_ROOM = 1_000
+
+      def self.name = NAME
+
+      # @param content [String] the source's name; blank for the list
+      # @param offset [Integer, String, nil] the first line (1-based)
+      # @param limit [Integer, String, nil] how many lines at most
+      # @param peers [Peers, nil] the session (id, cwd, state dir)
+      def self.call(content, offset: nil, limit: nil, peers: nil, max_chars: nil, now: Time.now)
+        return "Error: this session's id is not known here" unless peers&.session_id
+
+        new(peers, max_chars: max_chars || config_cap, now: now).run(content.to_s.strip, offset: offset, limit: limit)
+      rescue ContextSources::Invalid => e
+        "Error: #{e.message}"
+      end
+
+      def self.config_cap
+        value = Config.get("max_tool_output_chars").to_i
+        value.positive? ? value : DEFAULT_MAX_CHARS
+      end
+
+      def initialize(peers, max_chars:, now:)
+        @state_dir = peers.state_dir
+        @own = ContextSources.session_location(peers.session_id, state_dir: @state_dir)
+        # The Engine's PeerView knows the session's project; a plain Peers
+        # (specs, a bare kernel) has only its folder.
+        root = peers.respond_to?(:project_root) ? peers.project_root : ProjectScope.root_for(peers.cwd)
+        @attached = ContextSources.attached(peers.session_id, project_root: root, state_dir: @state_dir)
+        @max_chars = [max_chars.to_i, HEADER_ROOM * 2].max
+        @now = now
+      end
+
+      def run(name, offset:, limit:)
+        return list if name.empty?
+
+        ContextSources.check_name!(name)
+        attached = @attached.find { |a| a.name == name }
+        return "Error: no attached source #{name}; context_read without a name lists them" unless attached
+
+        read(attached, offset: offset, limit: limit)
+      end
+
+      private
+
+      # Muted sources are left out: this session ignores them.
+      def list
+        shown = @attached.reject { |a| @own.muted?(a.name) }
+        return "No attached context in this session." if shown.empty?
+
+        subs = @own.subscriptions
+        lines = shown.map do |a|
+          snapshot = a.snapshot
+          parts = ["- #{a.name}"]
+          parts << "why: #{a.source.why}" if a.source.why
+          hint = snapshot.hint || a.source.hint
+          parts << "hint: #{hint}" if hint
+          if snapshot.text?
+            parts << "fetched #{age(snapshot.fetched_at)}"
+            parts << "changed since you last read it: #{subs[a.name]&.read == snapshot.revision ? "no" : "yes"}"
+          else
+            parts << "no text yet"
+          end
+          parts << "last refresh failed: #{snapshot.error}" if snapshot.error
+          parts.join("; ")
+        end
+        "Attached context (#{shown.size}):\n#{lines.join("\n")}"
+      end
+
+      def read(attached, offset:, limit:)
+        snapshot = attached.snapshot
+        header = header_lines(attached, snapshot)
+        unless snapshot.text?
+          return "#{header.join("\n")}\nNo text yet#{": the last refresh failed" if snapshot.error}."
+        end
+
+        lines = snapshot.text.lines
+        first = positive(offset) || 1
+        return "#{header.join("\n")}\nThe text has #{lines.size} lines; offset #{first} is past its end." if first > lines.size
+
+        page = lines[(first - 1)..] || []
+        page = page.first(positive(limit)) if positive(limit)
+        page = fit(page)
+        last = first + page.size - 1
+        @own.update_subscription(attached.name) { |sub| sub.with(read: snapshot.revision) }
+
+        if first > 1 || last < lines.size
+          more = last < lines.size ? " Pass offset: #{last + 1} for more." : ""
+          header << "Lines #{first}-#{last} of #{lines.size}.#{more}"
+        end
+        "#{header.join("\n")}\n---\n#{page.join}"
+      end
+
+      def header_lines(attached, snapshot)
+        source = attached.source
+        hint = snapshot.hint || source.hint
+        header = ["#{source.name}#{" (#{hint})" if hint}"]
+        header << "Why: #{source.why}" if source.why
+        header << "Fetched: #{clock(snapshot.fetched_at)} (#{age(snapshot.fetched_at)})" if snapshot.fetched_at
+        header << "Summary: #{snapshot.summary}" if snapshot.summary
+        header << "Last refresh failed: #{snapshot.error}" if snapshot.error
+        header
+      end
+
+      # The lines that fit in the cap (at least one, cut when that one is
+      # longer than the cap).
+      def fit(lines)
+        budget = @max_chars - HEADER_ROOM
+        taken = []
+        used = 0
+        lines.each do |line|
+          break if used + line.length > budget && taken.any?
+
+          taken << (line.length > budget ? "#{line[0, budget]}…\n" : line)
+          used += line.length
+        end
+        taken
+      end
+
+      def positive(value)
+        number = Integer(value.to_s, 10, exception: false)
+        number&.positive? ? number : nil
+      end
+
+      def clock(iso)
+        Time.iso8601(iso).localtime.strftime("%Y-%m-%d %H:%M")
+      rescue ArgumentError
+        iso.to_s
+      end
+
+      def age(iso)
+        return "never" unless iso
+
+        seconds = (@now - Time.iso8601(iso)).to_i
+        if seconds < 60 then "just now"
+        elsif seconds < 3600 then "#{seconds / 60}m ago"
+        elsif seconds < 86_400 then "#{seconds / 3600}h ago"
+        else
+          "#{seconds / 86_400}d ago"
+        end
+      rescue ArgumentError
+        "at an unknown time"
+      end
+    end
+  end
+end

data/lib/samagotchi/tools/delegate.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../client_id"
 require_relative "../session"
 require_relative "../config"
 require_relative "../model_profile"
@@ -21,7 +22,6 @@ module Samagotchi
     # reply comes back (DelegateWait), never its trace.
     class Delegate
       NAME = "delegate"
-      CLIENT_PREFIX = "delegate"
       MAX_CHILDREN_KEY = "session.max_children"
       MAX_CHILDREN_DEFAULT = 4
       # A child spawned this many seconds ago counts as running even before
@@ -113,7 +113,7 @@ module Samagotchi
 
         # Only a reply after this delivery counts as the follow-up's.
         DelegateWait.mark_seen(parent.id, child, state_dir: state_dir)
-        delivered = SessionManager.deliver_turn(id, prompt: task, client_id: "#{CLIENT_PREFIX}:#{parent.id[0, 8]}",
+        delivered = SessionManager.deliver_turn(id, prompt: task, client_id: "#{ClientId::DELEGATE_PREFIX}#{parent.id[0, 8]}",
                                                     state_dir: state_dir)
         case delivered[:status]
         when :accepted then id

data/lib/samagotchi/tools/execute.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "open3"
+require_relative "../process_group"
 require_relative "output_guardrails"
 require_relative "shell"
 
@@ -95,7 +96,7 @@ module Samagotchi
 
         Open3.popen3(env || {}, *Shell.argv(command), chdir: cwd, pgroup: true) do |stdin, stdout, stderr, wait_thr|
           stdin.close
-          readers = [OutputReader.new(stdout), OutputReader.new(stderr)]
+          readers = [stdout, stderr].map { |io| ProcessGroup::PipeReader.new(io, chunk: READ_CHUNK_BYTES) }
 
           begin
             until wait_thr.join(WAIT_SLICE_SEC)
@@ -132,7 +133,7 @@ module Samagotchi
               stopped = stop_process_group(wait_thr.pid, readers)
               held_open = (stopped ? :stopped : :detached) if outcome == :grace && !stopping
             end
-            readers.each(&:finish)
+            readers.each { |reader| reader.finish(poll: STOP_POLL_INTERVAL_SEC, grace: STOP_GRACE_SEC) }
             stdout_text, stderr_text = readers.map(&:text)
           end
         end
@@ -162,95 +163,23 @@ module Samagotchi
       # has members holding the output: TERM the group, then KILL it. A process
       # that left the group (setsid) is out of reach; the pipes get closed.
       # True once the output was released, false if something still holds it.
+      # Only the group: the leader's pid is reaped, so it may name another process.
       def self.stop_process_group(pgid, readers)
-        signal_group(pgid, "TERM")
-        return true if await_readers(readers, until_time: monotonic_time + STOP_GRACE_SEC, deadline: nil,
-                                              cancelled: -> { false }) == :done
+        released = -> { readers.all?(&:done?) }
+        wait = ->(seconds) { readers.find { |r| !r.done? }&.wait(seconds) }
+        return true if ProcessGroup.stop(pgid, grace: STOP_GRACE_SEC, poll: STOP_POLL_INTERVAL_SEC, stopped: released, wait: wait)
 
-        signal_group(pgid, "KILL")
         await_readers(readers, until_time: monotonic_time + STOP_GRACE_SEC, deadline: nil, cancelled: -> { false }) == :done
       end
       private_class_method :stop_process_group
 
-      # Only the group: the leader's pid is reaped, so it may name another process.
-      def self.signal_group(pgid, signal)
-        Process.kill(signal, -pgid)
-      rescue Errno::ESRCH, Errno::EPERM
-        nil
-      end
-      private_class_method :signal_group
-
-      # Reads a pipe in chunks on its own thread, so the output read so far
-      # survives the pipe being closed under it.
-      class OutputReader
-        def initialize(io)
-          @io = io
-          @buffer = String.new(encoding: Encoding::BINARY)
-          @thread = Thread.new do
-            Thread.current.report_on_exception = false
-            loop { @buffer << io.readpartial(READ_CHUNK_BYTES) }
-          rescue IOError # EOFError is one
-            nil
-          end
-        end
-
-        def done? = !@thread.alive?
-
-        def wait(seconds) = @thread.join(seconds)
-
-        # Closes the pipe (a reader still blocked gets IOError) and ends the
-        # thread; the text is safe to read afterwards.
-        def finish
-          @thread.join(STOP_POLL_INTERVAL_SEC) unless done?
-          close_quietly
-          @thread.kill unless @thread.join(STOP_GRACE_SEC)
-        end
-
-        def text
-          @buffer.dup.force_encoding(@io.external_encoding || Encoding.default_external)
-        end
-
-        private
-
-        def close_quietly
-          @io.close unless @io.closed?
-        rescue IOError
-          nil
-        end
-      end
-      private_constant :OutputReader
-
+      # The shell still runs: TERM its group (or the shell alone, if it left
+      # the group), then KILL it once the grace is over.
       def self.terminate_process_tree(pid)
-        signal_process(pid, "TERM")
-
-        deadline = monotonic_time + STOP_GRACE_SEC
-        sleep(STOP_POLL_INTERVAL_SEC) while process_alive?(pid) && monotonic_time < deadline
-
-        signal_process(pid, "KILL") if process_alive?(pid)
+        ProcessGroup.stop(pid, grace: STOP_GRACE_SEC, poll: STOP_POLL_INTERVAL_SEC, leader: true)
       end
       private_class_method :terminate_process_tree
 
-      def self.signal_process(pid, signal)
-        Process.kill(signal, -pid)
-      rescue Errno::ESRCH, Errno::EPERM
-        begin
-          Process.kill(signal, pid)
-        rescue Errno::ESRCH, Errno::EPERM
-          nil
-        end
-      end
-      private_class_method :signal_process
-
-      def self.process_alive?(pid)
-        Process.kill(0, pid)
-        true
-      rescue Errno::ESRCH
-        false
-      rescue Errno::EPERM
-        true
-      end
-      private_class_method :process_alive?
-
       def self.monotonic_time
         Process.clock_gettime(Process::CLOCK_MONOTONIC)
       end

data/lib/samagotchi/tools/task_runtime.rb

@@ -6,6 +6,7 @@ require "securerandom"
 require "shellwords"
 require "time"
 require_relative "../atomic_file"
+require_relative "../process_group"
 require_relative "shell"
 
 module Samagotchi
@@ -24,6 +25,9 @@ module Samagotchi
       MARKER_ENV_KEYS = %w[SAMAGOTCHI_PARENT_SESSION SAMAGOTCHI_SESSION_MODEL].freeze
       # task_wait and task_get add it to a task the user stopped (the web's
       # stop-task button), so the model doesn't rerun the job.
+      # A record whose pid isn't a process group chi started (missing, 0, 1,
+      # not a number, or a pid another process reuses): nothing is signalled.
+      NOT_CHIS_PROCESS = "the task's process is gone or isn't the one chi started"
       USER_STOP_NOTE = "note: the user stopped this task; don't restart it unless they ask."
 
       module_function
@@ -54,13 +58,12 @@ module Samagotchi
 
         wrapped_command = wrapped_shell_command(normalized_command, exit_code_path)
         # Non-login, the shell Execute uses too (Shell).
-        pid = Process.spawn(
+        pid = ProcessGroup.spawn(
           spawn_env,
           *Shell.argv(wrapped_command),
           chdir: resolved_cwd,
           out: output_io,
-          err: output_io,
-          pgroup: true
+          err: output_io
         )
         Process.detach(pid)
 
@@ -185,26 +188,15 @@ module Samagotchi
         refreshed = refresh_record(record)
         return [refreshed, nil] unless refreshed["status"] == "running"
 
+        pid = refreshed["pid"]
+        # Checked again just before the signal: never a group chi didn't start.
+        return [mark_not_chis(refreshed), nil] unless ProcessGroup.leader?(pid)
+
         refreshed["stop_requested_by"] = by.to_s
         write_record(refreshed)
-        pid = refreshed["pid"].to_i
-
-        begin
-          Process.kill("TERM", -pid)
-        rescue Errno::ESRCH
-          # Process already exited; status refresh below handles final state.
-        end
 
-        deadline = monotonic_time + STOP_GRACE_SEC
-        sleep(STOP_POLL_INTERVAL_SEC) while process_alive?(pid) && monotonic_time < deadline
-
-        if process_alive?(pid)
-          begin
-            Process.kill("KILL", -pid)
-          rescue Errno::ESRCH
-            # Process exited between checks.
-          end
-        end
+        # A group that isn't ours (EPERM) is an error, not a stop.
+        ProcessGroup.stop(pid, grace: STOP_GRACE_SEC, poll: STOP_POLL_INTERVAL_SEC, quiet: [Errno::ESRCH])
 
         updated = mark_stopped(refresh_record(refreshed))
         write_record(updated)
@@ -217,10 +209,18 @@ module Samagotchi
       def refresh_record(record)
         return record unless record["status"] == "running"
 
-        pid = record["pid"].to_i
-        return mark_finished_without_exit_code(record) unless process_alive?(pid)
+        pid = record["pid"]
+        return record if ProcessGroup.leader?(pid)
+        # Gone: its exit code says how it ended.
+        return mark_finished_without_exit_code(record) if ProcessGroup.signalable?(pid) && !ProcessGroup.alive?(pid)
 
-        record
+        mark_not_chis(record)
+      end
+
+      # A running record whose pid isn't a group chi started (NOT_CHIS_PROCESS)
+      # ends as failed, unless its exit code or a stop on disk says more.
+      def mark_not_chis(record)
+        mark_finished_without_exit_code(record, missing_reason: NOT_CHIS_PROCESS)
       end
 
       # A session id (a uuid) is never a task's: task ids are a timestamp
@@ -338,16 +338,7 @@ module Samagotchi
         filtered.join(" ")
       end
 
-      def process_alive?(pid)
-        Process.kill(0, pid)
-        true
-      rescue Errno::ESRCH
-        false
-      rescue Errno::EPERM
-        true
-      end
-
-      def mark_finished_without_exit_code(record)
+      def mark_finished_without_exit_code(record, missing_reason: "process_ended_without_exit_code")
         record = current_record(record)
         return record unless record["status"] == "running"
 
@@ -359,7 +350,7 @@ module Samagotchi
         elsif exit_code.nil?
           record["status"] = "failed"
           record["exit_code"] = nil
-          record["stop_reason"] ||= "process_ended_without_exit_code"
+          record["stop_reason"] ||= missing_reason
         elsif exit_code.zero?
           record["status"] = "completed"
           record["exit_code"] = 0
@@ -401,10 +392,6 @@ module Samagotchi
       def timestamp
         Time.now.utc.iso8601
       end
-
-      def monotonic_time
-        Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      end
     end
   end
 end

data/lib/samagotchi/version.rb

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

data/lib/samagotchi/web/app.rb

@@ -9,6 +9,7 @@ require "uri"
 require "rack"
 require "rack/request"
 
+require_relative "../client_id"
 require_relative "../answer_tail"
 require_relative "../bridge_client"
 require_relative "../bridge/bounded_queue"
@@ -29,6 +30,8 @@ require_relative "../config"
 require_relative "../output_formatter"
 require_relative "../image_store"
 require_relative "../context_note"
+require_relative "../context_sources"
+require_relative "../context_providers"
 require_relative "../recap_store"
 require_relative "markdown_renderer"
 require_relative "message_parts"
@@ -150,6 +153,10 @@ module Samagotchi
         ["POST", %r{\A/api/sessions/([^/]+)/command\z}, :handle_command],
         ["POST", %r{\A/api/sessions/([^/]+)/images\z}, :handle_image_upload],
         ["GET", %r{\A/api/sessions/([^/]+)/images/([^/]+)\z}, :handle_image],
+        ["GET", %r{\A/api/sessions/([^/]+)/context\z}, :handle_context_list],
+        ["GET", %r{\A/api/sessions/([^/]+)/context/([^/]+)\z}, :handle_context_show],
+        ["POST", %r{\A/api/sessions/([^/]+)/context\z}, :handle_context_add],
+        ["DELETE", %r{\A/api/sessions/([^/]+)/context/([^/]+)\z}, :handle_context_delete],
         ["GET", %r{\A/api/sessions/([^/]+)\z}, :handle_show],
         ["DELETE", %r{\A/api/sessions/([^/]+)\z}, :handle_delete]
       ].freeze
@@ -1063,7 +1070,7 @@ module Samagotchi
       # {error: "held" | "not_running" | "unsupported" | "failed", reason, detail} in words; 409
       # owned_by_tui; 404.
       def handle_restart(_req, id)
-        result = @manager.restart_session(id, state_dir: @state_dir, client_id: "web:restart")
+        result = @manager.restart_session(id, state_dir: @state_dir, client_id: ClientId::WEB_RESTART)
         @hub&.touch(id)
         json_response(200, { status: "restarted", session_id: id, from_version: result.from_version,
                              version: result.version })
@@ -1117,6 +1124,101 @@ module Samagotchi
         error_response(404, "not_found", e.message)
       end
 
+      # ── Attached context (ContextSources): the session bar's chips ───────
+      # A source's command isn't shown (the page may be on a phone over the
+      # LAN), and the web adds a URL only, through an installed bundle's
+      # provider (ContextProviders): never a command.
+
+      # GET /api/sessions/:id/context: the sources this session sees, muted
+      # ones marked, with what the chips show.
+      def handle_context_list(_req, id)
+        session = @session_class.load(id, state_dir: default_state_dir)
+        own = ContextSources.session_location(id, state_dir: default_state_dir)
+        subs = own.subscriptions
+        rows = attached_context(session).map { |attached| context_row(attached, own, subs) }
+        json_response(200, { session_id: id, sources: rows, can_add_url: ContextProviders.any? })
+      rescue ArgumentError => e
+        error_response(404, "not_found", e.message)
+      end
+
+      # GET /api/sessions/:id/context/:name: one source with its text.
+      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]}")
+        own = ContextSources.session_location(id, state_dir: default_state_dir)
+        json_response(200, context_row(attached, own, own.subscriptions).merge(text: attached.snapshot.text))
+      rescue ArgumentError => e
+        error_response(404, "not_found", e.message)
+      end
+
+      # POST /api/sessions/:id/context {url, why}: the source an installed
+      # bundle's provider makes of +url+, attached to this session.
+      def handle_context_add(req, id)
+        session = @session_class.load(id, state_dir: default_state_dir)
+        body = parse_json(request_body(req))
+        return error_response(400, "invalid_json", "give {url, why}") unless body.is_a?(Hash) && body["url"].is_a?(String)
+
+        url = body["url"].strip
+        return error_response(422, "not_a_url", "give an http(s) URL") unless url.match?(%r{\Ahttps?://\S+\z})
+
+        resolved = ContextProviders.resolve(url)
+        return error_response(422, "no_provider", "no installed bundle resolves #{url[0, 200]}") unless resolved
+
+        own = ContextSources.session_location(session.id, state_dir: default_state_dir)
+        own.add(web_source(resolved, body["why"], own.scope))
+        json_response(201, { status: "attached", name: resolved.name })
+      rescue ContextProviders::Invalid => e
+        error_response(422, "no_provider", e.message)
+      rescue ContextSources::Invalid => e
+        error_response(409, "exists", e.message)
+      rescue ArgumentError => e
+        error_response(404, "not_found", e.message)
+      end
+
+      def web_source(resolved, why, scope)
+        why = ContextSources.one_line(why.is_a?(String) ? why : nil, ContextSources::LINE_MAX_CHARS) || resolved.why
+        ContextSources::Source.new(name: resolved.name, cmd: resolved.cmd, every_seconds: resolved.every_seconds, why: why,
+                                   hint: resolved.hint, scope: scope, added_by: "web", created_at: Time.now.utc.iso8601,
+                                   provider: resolved.bundle)
+      end
+
+      # DELETE /api/sessions/:id/context/:name: the session's own source is
+      # detached; a project's is muted for this session only.
+      def handle_context_delete(_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]}")
+        if attached.location.session?
+          attached.location.remove(attached.name)
+          json_response(200, { status: "detached", name: attached.name })
+        else
+          ContextSources.session_location(id, state_dir: default_state_dir).mute(attached.name)
+          json_response(200, { status: "muted", name: attached.name })
+        end
+      rescue ArgumentError => e
+        error_response(404, "not_found", e.message)
+      end
+
+      def attached_context(session)
+        ContextSources.attached(session.id, project_root: session.project_root, state_dir: default_state_dir)
+      end
+
+      # @return [ContextSources::Attached, nil]
+      def find_context(session, name)
+        ContextSources.check_name!(name)
+        attached_context(session).find { |attached| attached.name == name }
+      rescue ContextSources::Invalid
+        nil
+      end
+
+      def context_row(attached, own, subs)
+        source = attached.source
+        snapshot = attached.snapshot
+        { name: source.name, scope: source.scope, kind: source.push? ? "push" : "cmd", every_seconds: source.every_seconds,
+          why: source.why, hint: snapshot.hint || source.hint, summary: snapshot.summary, error: snapshot.error,
+          fetched_at: snapshot.fetched_at, has_text: snapshot.text?, muted: own.muted?(source.name),
+          unread: snapshot.text? && subs[source.name]&.read != snapshot.revision }
+      end
+
       def handle_stream(req, id)
         # Validate session exists
         begin
@@ -1491,7 +1593,14 @@ module Samagotchi
           role = (m[:role] || m["role"]).to_s
           content = (m[:content] || m["content"]).to_s
           if Samagotchi::ContextNote.note?(m)
-            filtered << { role: "note", content: Samagotchi::ContextNote.text_of(m), label: Samagotchi::ContextNote.label_of(m) }
+            note = { role: "note", content: Samagotchi::ContextNote.text_of(m), label: Samagotchi::ContextNote.label_of(m) }
+            # A context wake turn's note starts that turn (Steer.turn_prompt?):
+            # the page opens the turn with it and pairs it with its record.
+            if Samagotchi::Steer.turn_prompt?(m)
+              note[:turn_start] = true
+              note[:turn_id] = (m[:turn_id] || m["turn_id"]).to_s
+            end
+            filtered << note
             next
           end
           # A plugin's steer: a row of the step that answered it, which the