samagotchi 0.56.0 → 0.58.0

data/lib/samagotchi/terminal_ui.rb

@@ -98,7 +98,7 @@ module Samagotchi
       @thinking_word  = thinking
       @prompt         = prompt
       @llm_context_words = llm_context
-      @default_model_name = ModelProfile.required_model_name(nil)
+      @default_model_name = ModelProfile.default_model_name
       # As typed: the Engine applies an alias where it resolves the model.
       flag_model_name = model_name.to_s.strip.empty? ? nil : ModelProfile.required_model_name(model_name)
       @effective_model_name = flag_model_name || @default_model_name
@@ -127,6 +127,12 @@ module Samagotchi
         # Re-resolve client after resume may change effective model
         @client = @host_registry.resolve(@effective_model_name).client
       end
+      # No --model, no session model and no default: nothing to run.
+      raise ModelProfile::MissingModel, ModelProfile.missing_model_message if @effective_model_name.to_s.strip.empty?
+
+      # With no config default the Engine starts on the model it runs.
+      no_default = @default_model_name.nil?
+
       # The model it starts on names a configured host (a bad default.model
       # doesn't matter when --model or the session picks another).
       ModelProfile.check_host!(@effective_model_name, hosts: @host_registry.entries)
@@ -166,8 +172,10 @@ module Samagotchi
         session_id: session_id,
         no_interrupt: no_interrupt,
         # nil: the config default, unchecked here (the model the REPL starts
-        # on is checked above, and --model may make the default moot).
-        model_name: nil,
+        # on is checked above, and --model may make the default moot). With
+        # no default, the model it runs (the switch below is then skipped).
+        model_name: no_default ? @effective_model_name : nil,
+        model_typed: no_default ? @resumed_model_typed : nil,
         memories: @requested_memories,
         muted_memories: @muted_memory_names,
         recap: scratch ? nil : recap_config,
@@ -199,8 +207,9 @@ module Samagotchi
       @commands = SessionCommands.new(engine: @engine, turn_flow: @turn_flow, default_model: @default_model_name,
                                       registry: @engine.command_registry)
       # Runtime --model flag or resumed session: switch the Engine (client,
-      # kernel profile) without persisting the default.
-      @engine.switch_model!(@effective_model_name, typed: @resumed_model_typed) if @effective_model_name != @default_model_name
+      # kernel profile) without persisting the default. Skipped when there's
+      # no config default (the Engine was built on the session model).
+      @engine.switch_model!(@effective_model_name, typed: @resumed_model_typed) if !no_default && @effective_model_name != @default_model_name
       # Render an idle session-recap via the cursor-safe background writer; the
       # detector itself is Engine-owned (see Engine#recap) and opt-in.
       @recap_handle = @engine.subscribe(observer: ->(event) { @between_turns.take_recap(event) })

data/lib/samagotchi/tool_runner.rb

@@ -28,7 +28,8 @@ module Samagotchi
 
     # @param kernel [KernelLoop] read lazily: Engine sets its hooks after
     #   the kernel is built.
-    # @param clock [#call] monotonic seconds, for the approval wait
+    # @param clock [#call] monotonic seconds, for the approval wait and the
+    #   dispatch time (after_tool_call's elapsed_ms)
     def initialize(kernel, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
       @kernel = kernel
       @clock = clock
@@ -71,7 +72,14 @@ module Samagotchi
       end
       before = verdict.deny? ? NOT_AN_EDIT : file_before(call)
       index_before = before.equal?(NOT_AN_EDIT) ? nil : memory_index_size(call)
-      result = verdict.deny? ? denied(call, verdict) : dispatch(call)
+      elapsed_ms = nil
+      if verdict.deny?
+        result = denied(call, verdict)
+      else
+        dispatched_at = @clock.call
+        result = dispatch(call)
+        elapsed_ms = ((@clock.call - dispatched_at) * 1000).round
+      end
       diff = file_change(call, before)
       if diff && refresh_memory_index(call)
         result = with_index_note(result, index_before, call)
@@ -80,6 +88,9 @@ module Samagotchi
       result, images = attach_images(call, result) if result[:images]
 
       output = scrub(result[:output].to_s)
+      # The tool's own text, for after_tool_call: no "[tool]" lead, no
+      # ran-as line, no cap.
+      tool_text = output.sub(/\A\[#{Regexp.escape(call[:name].to_s)}\](?:\n| )/, "")
       # The gate may have replaced the call (known-names corrects a near
       # miss): one leading line tells the model what actually ran.
       if (changed = changed_call_line(original, call))
@@ -104,7 +115,7 @@ module Samagotchi
       # After the completed event: a hook's card (check-in, skills) prints
       # under the call's tool row, not before it.
       fire(:after_tool_call, { type: :after_tool_call, iteration: iteration, tool: call[:name], output: capped,
-                               status: status || "error" })
+                               status: status || "error", call: call.dup, elapsed_ms: elapsed_ms, result: tool_text })
 
       run = { output: output, capped_output: capped, truncated: truncated, activity: result[:activity] }
       run[:images] = images if images&.any?

data/lib/samagotchi/tools/execute.rb

@@ -24,6 +24,8 @@ module Samagotchi
       NOT_RUN_ON_STOP = "Error: not run, the user stopped the turn"
       # The first words of a command the user's Stop killed.
       STOPPED_BY_USER = "Error: command stopped by the user"
+      # The first words of a command killed at the limit (hooks match on it).
+      TIMEOUT_PREFIX = "Error: command timed out after"
       TIMEOUT_HINT = "(killed at the limit; for a long command use task_create, then task_wait)"
       # How long the output may stay open once the shell has exited: a
       # `server &` child keeps the pipes, and the read would never end.
@@ -68,7 +70,7 @@ module Samagotchi
       rescue CommandTimedOut => e
         # Keep the "Error:" first line (callers classify on it), say how to run
         # a long command, and return whatever it printed before it was killed.
-        stopped_result("Error: command timed out after #{timeout_sec}s\n#{TIMEOUT_HINT}", e)
+        stopped_result("#{TIMEOUT_PREFIX} #{timeout_sec}s\n#{TIMEOUT_HINT}", e)
       rescue CommandCancelled => e
         stopped_result("#{STOPPED_BY_USER} after #{e.elapsed.round}s (killed; rerun it if still needed)", e)
       rescue StandardError => e
@@ -189,7 +191,6 @@ module Samagotchi
       def self.timeout_seconds
         OutputGuardrails.config_positive_int("execute.timeout_sec", TIMEOUT_SEC)
       end
-      private_class_method :timeout_seconds
 
       # Resolves the working directory for the child process. An empty/absent
       # cwd defaults to the project root (Dir.pwd), mirroring task_runtime.

data/lib/samagotchi/version.rb

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

data/lib/samagotchi/web/app.rb

@@ -45,6 +45,7 @@ require_relative "editor"
 require_relative "message_parts"
 require_relative "session_summary"
 require_relative "../log"
+require_relative "../redacted_inspect"
 
 module Samagotchi
   module Web
@@ -56,6 +57,9 @@ module Samagotchi
     # (the single live client transport); history for any session — including
     # dead ones — is served by GET /api/sessions/:id/output from output/ files.
     class App
+      # @lan holds the LAN access token.
+      include RedactedInspect
+
       DEFAULT_HOST = BridgeClient::HOST
       BRIDGE_WAIT_TIMEOUT = 10.0
       # An uploaded image may be this big before it is downscaled.
@@ -706,10 +710,12 @@ module Samagotchi
 
       # POST /api/sessions with continues: <id, prefix or last:id>: the next
       # link of that session's chain (SessionManager.continue_session), in its
-      # folder, on its model and with its llm_context and thinking level, so
-      # dir, model, llm_context and thinking are refused beside it. 409 continued (with next_id, the
-      # link that continues it already: the page opens that one),
-      # open_children (ids), folder_gone, busy, scratch or owned_by_tui.
+      # folder, on its model and with its own setup (SessionSetup: llm_context,
+      # thinking and reasoning_history levels), so dir, model, llm_context and
+      # thinking are refused beside it (a create takes no reasoning_history).
+      # 409 continued (with next_id, the link that continues it already: the
+      # page opens that one), open_children (ids), folder_gone, busy, scratch
+      # or owned_by_tui.
       def handle_continue(body, prompt, idle)
         given = body["continues"]
         unless given.is_a?(String) && !given.strip.empty?
@@ -2128,10 +2134,12 @@ module Samagotchi
       # before returning, and a read blocked on a quiet worker would hang
       # Ctrl-C of chi web. The bytes go through unchanged.
       class ProxyStreamBody
+        # @param headers [Hash] the request's Rack env; only its Last-Event-ID
+        #   is kept (the env carries the token cookie, never held or inspected)
         def initialize(host:, port:, session_id:, query:, headers:, server_running: -> { true })
           @client = BridgeClient.new(session_id: session_id, port: port, host: host)
           @query = query
-          @headers = headers
+          @last_event_id = headers["HTTP_LAST_EVENT_ID"]
           @server_running = server_running
         end
 
@@ -2140,7 +2148,7 @@ module Samagotchi
           # Last-Event-ID header over ?from_seq, and the reconnect URL carries a
           # stale initial cursor — without this the bridge would replay content
           # already delivered (duplicate bubbles).
-          @client.stream(query: @query, last_event_id: @headers["HTTP_LAST_EVENT_ID"], running: @server_running, &)
+          @client.stream(query: @query, last_event_id: @last_event_id, running: @server_running, &)
         end
       end
     end

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

@@ -65,7 +65,8 @@ import {
   appendAboveLiveTiming, formatDuration, mergeTiming, normalizeTiming, sessionDurationNow, STOPPED_LINE_CLASS,
 } from "./timing.js";
 import { createLiveTurn } from "./live_turn.js";
-import { installRefClicks, setRefKinds } from "./refs.js";
+import { installRefClicks } from "./refs.js";
+import { linkRefs, touchedFiles } from "./ref_scan.js";
 import { DONE_MS, applyInitEvent, dropDone, initRowHtml, newInitTasks, seedInitTasks } from "./init_row.js";
 import { isReportClient, hookNoticeLabel, llmContextNotice, newClientId, noticeLine, promptOps, snapshotEvents, workerGoneText } from "./turn_events.js";
 import { applyConfirm, drawCommandBubble, keptCommandBubbles, restoreCommandBubbles } from "./commands.js";
@@ -837,6 +838,7 @@ function renderHistory(items) {
   }
   if (typeof items[0] === "object" && items[0].role) {
     historyEl.replaceChildren(turnHistoryNodes(items, current.timing, { thumbs: (images) => thumbsHtml(selected, images) }));
+    linkTextRefs();
   } else {
     historyEl.innerHTML = items.map((c) => `<div class="bubble output">${escapeHtml(c)}</div>`).join("");
   }
@@ -853,13 +855,11 @@ function setMarkdownWarning(warning) {
   markdownWarningEl.hidden = false;
 }
 
-// Both from one payload, together; the body's has-editor and refs-<kind>
-// classes follow (the refs' hover styling keys on refs-<kind>).
+// Both from one payload, together; the body's has-editor class follows.
 function setCapabilities(capabilities, editorUrl) {
   pageCapabilities = capabilities && typeof capabilities === "object" ? capabilities : {};
   pageEditorUrl = pageCapabilities.editor === true && typeof editorUrl === "string" && editorUrl ? editorUrl : null;
   document.body.classList.toggle("has-editor", pageEditorUrl !== null);
-  setRefKinds(document.body, pageViewer());
 }
 
 // What this viewer can do with a ref (refs.js REF_ACTIONS).
@@ -867,8 +867,11 @@ function pageViewer() {
   return { editor: pageCapabilities.editor === true, editorUrl: pageEditorUrl };
 }
 
-// Refs anywhere on the page (a tool row's file, its diff lines): one listener.
-installRefClicks(document.body, pageViewer);
+// Refs anywhere on the page (a tool row's file, its diff lines, an
+// answer's path:line): one listener set; "Copy path" says so in a toast.
+installRefClicks(document.body, pageViewer, {
+  copy: async (text) => showToast((await copyText(text)) ? "Path copied" : "Couldn't copy the path"),
+});
 
 async function readTurnEnd() {
   if (!selected) return;
@@ -901,20 +904,34 @@ async function readTurnEnd() {
   } catch(_){}
 }
 
+// The turn's answer as its rendered markdown, once it is final (the
+// turn-end read, an answer_display re-read); then its refs.
 function applyFinalMarkdown(messages) {
   const message = [...messages].reverse().find(
     (item) => item?.role === "assistant" && typeof item.html === "string",
   );
-  if (!message) return;
-
-  const bubble = findInTurnRoots(".bubble.output")
+  const bubble = message && findInTurnRoots(".bubble.output")
     .reverse()
     .find((item) => showsAnswer(item, message, normalize));
-  if (!bubble) return;
-
-  bubble.classList.add("markdown");
-  bubble.setAttribute(COPY_SOURCE_ATTR, copySource(message));
-  bubble.innerHTML = message.html;
+  if (bubble) {
+    bubble.classList.add("markdown");
+    bubble.setAttribute(COPY_SOURCE_ATTR, copySource(message));
+    bubble.innerHTML = message.html;
+  }
+  linkTextRefs();
+}
+
+// The `path:line` refs in the answers' and closed steps' texts that name a
+// file the session's rows (and cards) touched, on this page (ref_scan.js).
+// Not mid-stream: at a turn's end and after a reload's render. A ref
+// already made stays as it is.
+function linkTextRefs() {
+  const roots = turnRoots();
+  const touched = touchedFiles(roots);
+  if (!touched.size) return;
+  for (const root of roots) {
+    for (const el of root.querySelectorAll(".bubble.output, .gen:not(.live) > .gen-text")) linkRefs(el, touched, current.dir);
+  }
 }
 
 function seedSeenFromDom() {

data/lib/samagotchi/web/public/index.html

@@ -178,6 +178,17 @@ button.task-stop:hover:not(:disabled){background:var(--danger-bg-dim);filter:non
 .activity-diff>summary{cursor:pointer;font-size:12px;color:var(--text-muted);width:max-content;font-variant-numeric:tabular-nums}
 .activity-diff>summary:hover{color:var(--text-2)}
 .activity-diff[open]>summary{margin-bottom:4px}
+/* A read of the file as-is: its numbered lines, closed under the preview (read_view.js); open, they stand for it. */
+.activity-read{flex:1 1 100%;min-width:0;margin:2px 0 2px var(--row-gutter)}
+.activity-read>summary{cursor:pointer;font-size:12px;color:var(--text-muted);width:max-content;font-variant-numeric:tabular-nums}
+.activity-read>summary:hover{color:var(--text-2)}
+.activity-read[open]>summary{margin-bottom:4px}
+.activity-row:has(>.activity-read[open])>.activity-output{display:none}
+.read-lines{margin:0;padding:4px 0;background:var(--bg-inset);border:1px solid var(--border);border-radius:6px;font-size:12px;line-height:1.45;overflow:auto;max-height:420px}
+.read-lines code{display:block;min-width:max-content}
+.read-line{display:block;padding:0 10px 0 0;white-space:pre;color:var(--text-2)}
+.read-line::before{content:attr(data-line);display:inline-block;width:5ch;margin-right:10px;padding-right:6px;text-align:right;color:var(--text-faint);user-select:none;font-variant-numeric:tabular-nums}
+.read-meta{color:var(--text-faint)}
 /* An execute/task_create's full command, above its output and lined up with it: as written, its own scroll. */
 .activity-row>.activity-command{flex:1 1 100%;min-width:0;margin:4px 0 2px var(--row-gutter)}
 .activity-command pre{margin:0;max-height:160px;overflow:auto;white-space:pre-wrap;word-break:break-word;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:12px;line-height:1.45;color:var(--text-2);background:var(--bg-inset);border:1px solid var(--border);border-radius:6px;padding:6px 34px 6px 8px}
@@ -215,6 +226,7 @@ button.task-stop:hover:not(:disabled){background:var(--danger-bg-dim);filter:non
   .activity-params{flex:1 1 0}
   .activity-output{margin-left:0}
   .activity-diff{margin-left:0}
+  .activity-read{margin-left:0}
   .activity-edit{margin-left:0}
   .activity-row>.activity-command{margin-left:0}
 }
@@ -368,11 +380,26 @@ button.task-stop:hover:not(:disabled){background:var(--danger-bg-dim);filter:non
 .diff{margin:0;padding:4px 0;background:var(--bg-inset);border:1px solid var(--border);border-radius:6px;font-size:12px;line-height:1.45;overflow:auto;max-height:420px}
 .diff code{display:block;min-width:max-content}
 .diff-line{display:block;padding:0 10px;white-space:pre;color:var(--text-2)}
-/* Refs (refs.js): text until hovered, and only for a kind this viewer has an action for (body.refs-file). */
-.refs-file .ref[data-ref-kind="file"]:hover{color:var(--accent);text-decoration:underline dotted;text-underline-offset:3px;cursor:pointer}
-.refs-file .ref[data-ref-kind="file"]:hover::after{content:"\2197";margin-left:.3em;color:var(--text-faint);display:inline-block}
-.refs-file .activity-row:has(.ref[data-ref-kind="file"]) .diff-line[data-line]:hover{cursor:pointer;box-shadow:inset 2px 0 var(--accent)}
-.refs-file .activity-row:has(.ref[data-ref-kind="file"]) .diff-line[data-line]:hover::after{content:"\2197  " attr(data-line);float:right;padding-left:12px;color:var(--text-faint)}
+/* Refs (refs.js): text until hovered or focused, and only with a target for this viewer (refs.js marks it: data-ref-main, the main one). A link ref keeps its link look. */
+.ref[data-ref-main]:not(a):is(:hover,:focus-visible){color:var(--accent);text-decoration:underline dotted;text-underline-offset:3px;cursor:pointer}
+.ref[data-ref-main="editor"]:not(a):is(:hover,:focus-visible)::after{content:"\2197";margin-left:.3em;color:var(--text-faint);display:inline-block}
+.ref[data-ref-kind]:focus-visible{outline:2px solid var(--accent);outline-offset:2px;border-radius:3px}
+:is(.activity-row,.bubble.approval) .diff-line[data-ref-main]:hover{cursor:pointer;box-shadow:inset 2px 0 var(--accent)}
+:is(.activity-row,.bubble.approval) .diff-line[data-ref-main]:hover::after{content:"\2197  " attr(data-line);float:right;padding-left:12px;color:var(--text-faint)}
+.activity-row .read-line[data-ref-main]:hover{cursor:pointer;box-shadow:inset 2px 0 var(--accent)}
+.activity-row .read-line[data-ref-main]:hover::before{color:var(--accent)}
+/* A ref's ▾ and its menu (ref_menu.js): one each, placed next to the ref. */
+.ref-more{position:fixed;z-index:60;display:inline-flex;align-items:center;justify-content:center;width:20px;height:20px;padding:0;border:1px solid var(--border-strong);border-radius:5px;background:var(--bg-panel);color:var(--text-muted);font-size:12px;line-height:1;cursor:pointer;box-shadow:0 1px 3px var(--shadow-strong)}
+.ref-more[hidden]{display:none}
+.ref-more:hover{color:var(--accent);border-color:var(--accent)}
+.ref-menu{position:fixed;z-index:61;min-width:160px;max-width:calc(100vw - 16px);padding:4px;border:1px solid var(--border-strong);border-radius:8px;background:var(--bg-panel);box-shadow:var(--toast-shadow);animation:fadeIn .12s ease-out}
+.ref-menu [role="menuitem"]{display:block;width:100%;padding:6px 10px;border:0;border-radius:5px;background:none;color:var(--text);font:inherit;font-size:13px;text-align:left;cursor:pointer;white-space:nowrap}
+.ref-menu [role="menuitem"]:is(:hover,:focus-visible){background:var(--accent-bg);color:var(--text-bright);outline:none}
+@media (pointer:coarse){.ref-menu [role="menuitem"]{padding:11px 14px;font-size:15px}}
+/* Show in turn: the row (and its line) flash once. */
+@keyframes ref-flash{0%,35%{background:color-mix(in srgb,var(--accent) 22%,transparent)}100%{background:transparent}}
+.ref-flash{animation:ref-flash 1.6s ease-out}
+@media (prefers-reduced-motion:reduce){.ref-menu{animation:none}.ref-flash{animation:none;outline:2px solid var(--accent);outline-offset:2px}}
 .diff-add{background:var(--diff-add-bg);color:var(--diff-add-text)}
 .diff-del{background:var(--diff-del-bg);color:var(--diff-del-text)}
 .diff-hunk{color:var(--text-faint)}

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

@@ -49,9 +49,10 @@ export function relayView(pq) {
   };
 }
 
-// @return {null | {tool, what, isCommand, where, why, preview?, delegate?}};
-// preview is an edit/write's dry-run diff (diff_view.js draws it); delegate
-// is relayView's, for a delegate's approval
+// @return {null | {tool, what, isCommand, where, why, paths?, preview?, delegate?}};
+// paths are what +what+ joins when it shows paths (the card draws a ref
+// for each); preview is an edit/write's dry-run diff (diff_view.js draws
+// it); delegate is relayView's, for a delegate's approval
 export function approvalView(pq) {
   if (!isApproval(pq)) return null;
   const a = pq.approval || {};
@@ -74,6 +75,7 @@ export function approvalView(pq) {
     // A tool without a command or path (an MCP tool): its compact args.
     what: command || paths.join("\n") || a.args || "",
     isCommand: !!command,
+    ...(!command && paths.length ? { paths } : {}),
     where,
     why: `${reason} (${who})`,
     ...(a.preview && typeof a.preview === "object" ? { preview: a.preview } : {}),

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

@@ -254,7 +254,8 @@ export function createQuestionCards({
       const what = doc.createElement("pre");
       what.className = view.isCommand ? "approval-what command" : "approval-what paths";
       const code = doc.createElement("code");
-      code.textContent = view.what;
+      if (view.paths) appendPathRefs(code, view.paths);
+      else code.textContent = view.what;
       what.appendChild(code);
       box.appendChild(what);
     }
@@ -279,6 +280,25 @@ export function createQuestionCards({
     return box;
   }
 
+  // One file ref per path, a line each (refs.js: the card's path opens
+  // the current file at the dry run's first change). A directory (a
+  // plugin's path ending in /) stays plain text.
+  function appendPathRefs(code, paths) {
+    paths.forEach((path, i) => {
+      if (i) code.appendChild(doc.createTextNode("\n"));
+      if (String(path).endsWith("/")) {
+        code.appendChild(doc.createTextNode(String(path)));
+        return;
+      }
+      const ref = doc.createElement("span");
+      ref.className = "ref";
+      ref.dataset.refKind = "file";
+      ref.dataset.refPath = String(path);
+      ref.textContent = String(path);
+      code.appendChild(ref);
+    });
+  }
+
   // "Waiting for approval in parent ab12: answering here works too", or
   // an empty (hidden) line while the question isn't relayed.
   function renderRelayedTo(pq) {

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

@@ -0,0 +1,74 @@
+// A read row's output as the file's lines, numbered, apart from the DOM.
+// Only when the output is the file text as-is: each numbered line is a
+// ref's line (refs.js opens the row's file there). The row's preview
+// (turn_html.js) strips any "[tag] " and cuts at 300 chars; numbering
+// needs the text exactly as read, so it is drawn on its own, closed.
+
+import { escapeHtml } from "./format.js";
+
+// What follows one of these isn't the file's next line: a ToolRunner cap
+// ("[cut: …]"), a head/tail preview's gap ("[... omitted …]") or the note
+// of a range clamped at the end of the file ("[read: end_line …]"). They
+// are appended at the end (a clamp note, then a cut), so only the last
+// MARKER_LINES lines can be one: such a line earlier is the file's own.
+const MARKER_LINES = 2;
+const MARKER = /^(?:\[cut: |\[\.\.\. omitted |\[read: end_line \d+ exceeds )/;
+
+// An image's line instead of its text: attached, or why not (ToolRunner).
+const IMAGE = /\((?:\d+×\d+ )?[A-Z]+\)(?: attached\.| is an image; | is not attached: )/;
+
+// The file text of a read row's output, or null when it isn't the file
+// as-is: an error, the head/tail preview of a big file, an image's line.
+function fileText(row) {
+  if (row?.tool !== "read" || row.status !== "ok" || row.ref?.kind !== "file" || row.images?.length) return null;
+  let text = String(row.output || "");
+  // The call the gate replaced says so on a line before the tag.
+  if (text.startsWith("ran as: ")) text = text.slice(text.indexOf("\n") + 1);
+  if (!text.startsWith("[read]\n")) return null;
+  text = text.slice("[read]\n".length);
+  if (!text || text.startsWith("Error: ") || text.startsWith("truncated=true\n")) return null;
+  if (!text.includes("\n") && IMAGE.test(text)) return null;
+  return text;
+}
+
+// @return {null | Array<{text, line}>} the output's lines, line null for
+// one that isn't the file's: a marker and all after it, and the "…" of a
+// reload's capped output (output_truncated; a cut line already says so
+// for a live one). The first line is the range's start_line (the ref's
+// line), else 1.
+export function readLines(row) {
+  const text = fileText(row);
+  if (text === null) return null;
+  const lines = text.split("\n");
+  // The file's last newline ends a line, it doesn't start one.
+  if (lines.at(-1) === "") lines.pop();
+  let next = Number(row.ref.line) || 1;
+  let numbering = true;
+  const out = [];
+  lines.forEach((line, i) => {
+    if (numbering && i >= lines.length - MARKER_LINES && MARKER.test(line)) {
+      numbering = false;
+      // The newline before a marker is the marker's: the blank it leaves
+      // isn't a line of the file.
+      if (i > 0 && lines[i - 1] === "" && out.at(-1)?.line !== null) out.pop();
+    }
+    out.push({ text: line, line: numbering ? next++ : null });
+  });
+  if (row.output_truncated && numbering) out.push({ text: "…", line: null });
+  return out;
+}
+
+// A read row's numbered lines behind a closed toggle ("lines 40–60"); ""
+// when its output isn't the file as-is.
+export function readLinesHtml(row) {
+  const lines = readLines(row);
+  const numbered = lines?.filter((l) => l.line !== null) || [];
+  if (!numbered.length) return "";
+  const first = numbered[0].line;
+  const last = numbered.at(-1).line;
+  const label = first === last ? `line ${first}` : `lines ${first}–${last}`;
+  const spans = lines.map(({ text, line }) => line === null
+    ? `<span class="read-line read-meta">${escapeHtml(text)}</span>`
+    : `<span class="read-line" data-line="${line}">${escapeHtml(text) || " "}</span>`).join("");
+  return `<details class="activity-read"><summary>${label}</summary><pre class="read-lines"><code>${spans}</code></pre></details>`;
+}

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

@@ -0,0 +1,188 @@
+// A ref's menu (refs.js): the small ▾ that shows next to a hovered or
+// focused ref with more than one target, and the menu of its targets it
+// opens (a tap and ↓ open it too). One of each per page, placed next to
+// the ref (position: fixed); a scroll, a resize, a click elsewhere, Esc or
+// Tab closes them. Keyboard: ↑/↓ (Home/End) move, Enter picks, Esc closes
+// back to the ref.
+
+// How long the ▾ stays after the pointer leaves the ref: long enough to
+// reach it.
+const HIDE_MS = 300;
+// Kept from the viewport's edges (a phone's width).
+const EDGE = 8;
+
+// +doc+'s ▾ and menu. open(el, items, {focus}) shows +items+ ({id, label,
+// run}) under +el+; showMore(el, onOpen) puts the ▾ after +el+, whose click
+// calls +onOpen+; hideMoreSoon(el) takes it away unless the pointer reaches
+// it; close({refocus}) closes the menu.
+export function createRefMenu(doc = globalThis.document) {
+  let more = null;
+  let menu = null;
+  let moreFor = null;
+  let menuFor = null;
+  let onMore = null;
+  let hideTimer = null;
+  const win = doc.defaultView || globalThis;
+
+  function moreButton() {
+    if (more) return more;
+    more = doc.createElement("button");
+    more.type = "button";
+    more.className = "ref-more";
+    more.textContent = "▾";
+    more.title = "More for this ref";
+    more.setAttribute("aria-label", "More for this ref");
+    more.setAttribute("aria-haspopup", "menu");
+    more.tabIndex = -1;
+    more.hidden = true;
+    more.addEventListener("mouseenter", () => clearTimeout(hideTimer));
+    more.addEventListener("mouseleave", () => hideMoreSoon(moreFor));
+    more.addEventListener("mousedown", (e) => e.preventDefault()); // keeps the ref's focus
+    more.addEventListener("click", (e) => {
+      e.preventDefault();
+      e.stopPropagation();
+      onMore?.();
+    });
+    doc.body.appendChild(more);
+    return more;
+  }
+
+  function showMore(el, onOpen) {
+    clearTimeout(hideTimer);
+    const button = moreButton();
+    moreFor = el;
+    onMore = onOpen;
+    button.hidden = false;
+    const rect = lastRect(el);
+    const top = rect.top + (rect.height - (button.offsetHeight || rect.height)) / 2;
+    button.style.left = `${Math.min(rect.right + 2, win.innerWidth - (button.offsetWidth || 16) - 2)}px`;
+    button.style.top = `${top}px`;
+  }
+
+  function hideMore() {
+    clearTimeout(hideTimer);
+    if (more) more.hidden = true;
+    moreFor = null;
+  }
+
+  function hideMoreSoon(el) {
+    if (!more || (el && el !== moreFor)) return;
+    clearTimeout(hideTimer);
+    hideTimer = setTimeout(() => {
+      if (menu && menuFor === moreFor) return;
+      if (doc.activeElement && doc.activeElement === moreFor) return;
+      hideMore();
+    }, HIDE_MS);
+  }
+
+  function open(el, items, { focus = true } = {}) {
+    close();
+    menuFor = el;
+    menu = doc.createElement("div");
+    menu.className = "ref-menu";
+    menu.setAttribute("role", "menu");
+    for (const item of items) {
+      const button = doc.createElement("button");
+      button.type = "button";
+      button.setAttribute("role", "menuitem");
+      button.tabIndex = -1;
+      button.dataset.target = item.id;
+      button.textContent = item.label;
+      button.addEventListener("click", (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        close({ refocus: false });
+        hideMore();
+        item.run();
+      });
+      menu.appendChild(button);
+    }
+    menu.addEventListener("keydown", onMenuKey);
+    menu.addEventListener("focusout", (e) => {
+      if (menu && !menu.contains(e.relatedTarget) && e.relatedTarget) close({ refocus: false });
+    });
+    doc.body.appendChild(menu);
+    place(menu, el);
+    el.setAttribute("aria-expanded", "true");
+    doc.addEventListener("pointerdown", onOutside, true);
+    win.addEventListener("scroll", onScroll, true);
+    win.addEventListener("resize", onScroll);
+    if (focus) menuItems()[0]?.focus();
+    return menu;
+  }
+
+  function close({ refocus = false } = {}) {
+    if (!menu) return;
+    const el = menuFor;
+    menu.remove();
+    menu = null;
+    menuFor = null;
+    el?.removeAttribute("aria-expanded");
+    doc.removeEventListener("pointerdown", onOutside, true);
+    win.removeEventListener("scroll", onScroll, true);
+    win.removeEventListener("resize", onScroll);
+    if (refocus) el?.focus?.();
+  }
+
+  function menuItems() {
+    return menu ? [...menu.querySelectorAll('[role="menuitem"]')] : [];
+  }
+
+  function onMenuKey(e) {
+    const items = menuItems();
+    const at = items.indexOf(doc.activeElement);
+    const go = (index) => items[(index + items.length) % items.length]?.focus();
+    if (e.key === "ArrowDown") go(at + 1);
+    else if (e.key === "ArrowUp") go(at < 0 ? -1 : at - 1);
+    else if (e.key === "Home") go(0);
+    else if (e.key === "End") go(-1);
+    else if (e.key === "Escape") close({ refocus: true });
+    else if (e.key === "Tab") { close({ refocus: true }); return; }
+    else return;
+    e.preventDefault();
+    e.stopPropagation();
+  }
+
+  function onOutside(e) {
+    if (menu?.contains(e.target) || more?.contains(e.target)) return;
+    close();
+  }
+
+  function onScroll(e) {
+    if (menu?.contains(e?.target)) return;
+    close();
+    hideMore();
+  }
+
+  // Under the ref's last line, flipped above it when there is no room
+  // below, kept inside the viewport.
+  function place(box, el) {
+    const rect = lastRect(el);
+    const first = el.getClientRects?.()[0] || rect;
+    const width = box.offsetWidth;
+    const height = box.offsetHeight;
+    const left = Math.max(EDGE, Math.min(rect.left, win.innerWidth - width - EDGE));
+    const below = rect.bottom + 4;
+    const top = below + height > win.innerHeight - EDGE && first.top - height - 4 >= EDGE ? first.top - height - 4 : below;
+    box.style.left = `${left}px`;
+    box.style.top = `${top}px`;
+  }
+
+  return {
+    open,
+    close,
+    showMore,
+    hideMore,
+    hideMoreSoon,
+    get isOpen() { return !!menu; },
+    get element() { return menu; },
+    get moreButton() { return more; },
+  };
+}
+
+// The ref's last line box (a ref wrapped over two lines ends on the
+// second); its whole box when it has none.
+function lastRect(el) {
+  const rects = el.getClientRects?.() || [];
+  return rects.length ? rects[rects.length - 1] : el.getBoundingClientRect();
+}