samagotchi 0.125.0 → 0.126.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +25 -1
  3. data/docs/guardrails.md +22 -0
  4. data/docs/internals/participants.md +70 -2
  5. data/docs/internals/web-push.md +10 -6
  6. data/docs/sessions.md +3 -0
  7. data/lib/samagotchi/bridge.rb +4 -3
  8. data/lib/samagotchi/bridge_client.rb +8 -1
  9. data/lib/samagotchi/bundles/known-names/hooks/known_names.rb +25 -4
  10. data/lib/samagotchi/bundles/known-names/manifest.yml +2 -2
  11. data/lib/samagotchi/bundles/system/manifest.yml +1 -1
  12. data/lib/samagotchi/child_reports.rb +3 -0
  13. data/lib/samagotchi/children_status.rb +6 -1
  14. data/lib/samagotchi/engine.rb +43 -7
  15. data/lib/samagotchi/guardrail_wiring.rb +10 -1
  16. data/lib/samagotchi/llm/chat_loop.rb +1 -0
  17. data/lib/samagotchi/session.rb +40 -3
  18. data/lib/samagotchi/session_inbox.rb +14 -8
  19. data/lib/samagotchi/session_manager.rb +11 -4
  20. data/lib/samagotchi/session_participants.rb +10 -2
  21. data/lib/samagotchi/verdict.rb +20 -0
  22. data/lib/samagotchi/verify_anchor.rb +28 -0
  23. data/lib/samagotchi/verify_fresh.rb +275 -0
  24. data/lib/samagotchi/verify_fresh_origin.rb +71 -0
  25. data/lib/samagotchi/version.rb +1 -1
  26. data/lib/samagotchi/web/app.rb +3 -0
  27. data/lib/samagotchi/web/participant_access.rb +15 -4
  28. data/lib/samagotchi/web/participant_review.rb +7 -1
  29. data/lib/samagotchi/web/participant_view.rb +46 -5
  30. data/lib/samagotchi/web/public/annotate_bar.js +9 -1
  31. data/lib/samagotchi/web/public/app.js +69 -4
  32. data/lib/samagotchi/web/public/data.js +2 -1
  33. data/lib/samagotchi/web/public/index.html +1 -0
  34. data/lib/samagotchi/web/public/notify.js +13 -2
  35. data/lib/samagotchi/web/public/participant.html +2 -1
  36. data/lib/samagotchi/web/public/participant.js +69 -7
  37. data/lib/samagotchi/web/public/send_turn.js +6 -1
  38. data/lib/samagotchi/web/public/session_state.js +5 -0
  39. data/lib/samagotchi/web/public/stream_handlers.js +3 -0
  40. data/lib/samagotchi/web/public/verdict_card.js +65 -0
  41. data/lib/samagotchi/web/public/verdict_fresh.js +120 -0
  42. data/lib/samagotchi/web/public/verify_card.css +17 -0
  43. data/lib/samagotchi/web/push/attention.rb +25 -5
  44. data/lib/samagotchi/web/push/notifier.rb +4 -3
  45. data/lib/samagotchi/web/session_control.rb +2 -0
  46. data/lib/samagotchi/web/session_summary.rb +25 -1
  47. data/lib/samagotchi/web/verify_fresh_routes.rb +110 -0
  48. data/lib/samagotchi/worker.rb +68 -9
  49. data/lib/samagotchi/worker_inbound.rb +4 -4
  50. metadata +9 -1
@@ -25,6 +25,9 @@ export function emptySessionState() {
25
25
  continues: null,
26
26
  // A review session's {subjects, from} (its `review`), or null.
27
27
  review: null,
28
+ verdicts: [],
29
+ // The Verify fresh checks running ({of, child_id}; the summary's verify_fresh).
30
+ verifyFresh: [],
28
31
  // Its start (the summary's created_at; the info bar's chain links are
29
32
  // times on its day), or null.
30
33
  createdAt: null,
@@ -116,6 +119,8 @@ export function sessionStateFrom(data) {
116
119
  state.parentId = s.parent_id || null;
117
120
  state.continues = s.continues || null;
118
121
  state.review = s.review || null;
122
+ state.verdicts = Array.isArray(s.verdicts) ? s.verdicts : [];
123
+ state.verifyFresh = Array.isArray(s.verify_fresh) ? s.verify_fresh : [];
119
124
  state.createdAt = s.created_at || null;
120
125
  state.commands = Array.isArray(data.commands) ? data.commands : [];
121
126
  return state;
@@ -181,6 +181,7 @@ export function createStreamHandlers(deps) {
181
181
  endTurnView("completed", null, { emptyAnswer: data.turn_summary?.empty_answer || null });
182
182
  const out = turnOutput(data);
183
183
  if (out) appendChunk(out);
184
+ if (data.verdict) deps.placeVerdict?.(data.verdict);
184
185
  // after_turn hooks are running and may present the answer: its
185
186
  // answer_display (display: null when they didn't) comes next. A worker
186
187
  // that dies before it never sends one: workerGone releases the wait, and
@@ -356,6 +357,8 @@ export function createStreamHandlers(deps) {
356
357
  // Someone joined, left or was revoked (the worker's ParticipantsWatch):
357
358
  // the owner's chip and panel read the list again.
358
359
  participants_changed: () => participantsControl?.reload(),
360
+ // A Verify fresh child's verdict, taken onto its card by the worker.
361
+ verdict_recorded: (data) => deps.placeVerdict?.(data.verdict),
359
362
  continue_offered: (data) => questionCards.renderContinue(data),
360
363
  continue_resolved: (data) => questionCards.resolveContinue(data),
361
364
  tool_call_started: (data) => turnDom.toolStarted(data),
@@ -0,0 +1,65 @@
1
+ const TYPES = Object.freeze({
2
+ confirmed: { icon: "✅", label: "confirmed" },
3
+ refuted: { icon: "❌", label: "refuted" },
4
+ unclear: { icon: "❓", label: "unclear" },
5
+ });
6
+
7
+ export function placeVerdict(root, record, { who = "Owner", author = null } = {}) {
8
+ const anchor = record?.anchor;
9
+ const type = TYPES[record?.verdict];
10
+ if (!root || !type || typeof anchor?.turn_id !== "string" || typeof anchor?.quote !== "string"
11
+ || typeof record.reason !== "string" || typeof record.check_turn_id !== "string") return null;
12
+
13
+ const elements = [...root.querySelectorAll("[data-turn-id]")];
14
+ const source = elements.find((element) => element.dataset.turnId === anchor.turn_id);
15
+ if (!source) return null;
16
+ const cards = [...root.querySelectorAll(".verify-verdict")];
17
+ const existing = cards.find((card) => card.dataset.checkTurnId === record.check_turn_id);
18
+ if (existing) return existing;
19
+
20
+ const doc = root.ownerDocument;
21
+ const card = doc.createElement("aside");
22
+ card.className = `verify-verdict ${record.verdict}`;
23
+ card.dataset.sourceTurnId = anchor.turn_id;
24
+ card.dataset.checkTurnId = record.check_turn_id;
25
+ if (author) card.dataset.author = author;
26
+ card.setAttribute("aria-label", `Claim verdict: ${type.label}`);
27
+
28
+ const heading = doc.createElement("div");
29
+ heading.className = "verify-verdict-heading";
30
+ heading.append(doc.createTextNode(`${type.icon} ${type.label} · `));
31
+ const name = doc.createElement("span");
32
+ name.className = "verify-verdict-who";
33
+ name.textContent = who;
34
+ heading.append(name);
35
+
36
+ const quote = doc.createElement("blockquote");
37
+ quote.className = "verify-verdict-quote";
38
+ quote.textContent = anchor.quote;
39
+ const reason = doc.createElement("p");
40
+ reason.className = "verify-verdict-reason";
41
+ reason.textContent = record.reason;
42
+
43
+ // Verify fresh (an unclear verdict's button, its fresh verdicts): verdict_fresh.js.
44
+ const link = doc.createElement("a");
45
+ link.href = "#";
46
+ link.className = "verify-verdict-link";
47
+ link.textContent = "View check";
48
+ link.addEventListener("click", (event) => {
49
+ event.preventDefault();
50
+ [...root.querySelectorAll("[data-turn-id]")].find((element) => element.dataset.turnId === record.check_turn_id)
51
+ ?.scrollIntoView?.({ behavior: "smooth", block: "center" });
52
+ });
53
+ card.append(heading, quote, reason, link);
54
+
55
+ const previous = cards.filter((candidate) => candidate.dataset.sourceTurnId === anchor.turn_id).at(-1);
56
+ (previous || source).after(card);
57
+ return card;
58
+ }
59
+
60
+ export function nameVerdictCards(root, nameFor) {
61
+ for (const card of root?.querySelectorAll?.(".verify-verdict[data-author]") || []) {
62
+ const name = nameFor(card.dataset.author);
63
+ if (name) card.querySelector(".verify-verdict-who").textContent = name;
64
+ }
65
+ }
@@ -0,0 +1,120 @@
1
+ // Verify fresh on a verdict card, both pages (docs/internals/participants.md,
2
+ // Verify fresh): an unclear verdict's card offers a new agent that checks the
3
+ // claim with none of the session's context; while it runs the card says so
4
+ // (the owner's links to its session), and its verdict lands on the same card
5
+ // as a "fresh:" line. A module of its own: static JS is cached at unversioned
6
+ // URLs, and a new export on an old module would blank the page.
7
+
8
+ import { placeVerdict } from "./verdict_card.js";
9
+
10
+ const ICONS = Object.freeze({ confirmed: "✅", refuted: "❌", unclear: "❓" });
11
+
12
+ // The request that starts one (owner and participant alike).
13
+ export function freshURL(sessionId, checkTurnId) {
14
+ return `/api/sessions/${encodeURIComponent(sessionId)}/verdicts/${encodeURIComponent(checkTurnId)}/fresh`;
15
+ }
16
+
17
+ // A running entry's verdict: the participant's are its check_turn_id, the
18
+ // owner's {of, child_id}.
19
+ function runningOf(entry) {
20
+ return typeof entry === "string" ? entry : entry?.of;
21
+ }
22
+
23
+ // +running+ without the check a fresh verdict just ended (+record+).
24
+ export function settleRunning(running, record) {
25
+ if (!record?.fresh) return running || [];
26
+ return (running || []).filter((entry) => runningOf(entry) !== record.of);
27
+ }
28
+
29
+ // Places a session verdict as the pages draw them: an original verdict's
30
+ // card (verdict_card.js) with its Verify fresh part, or a fresh verdict on
31
+ // its original's card. +fresh+: {verdicts (all of the session's), running
32
+ // (the page's own array; a start adds to it), canStart, start(of) → Promise
33
+ // of {ok, child_id, error}, childHref(id) → a link to the child or null}.
34
+ export function placeVerdictWithFresh(root, record, opts = {}, fresh = {}) {
35
+ if (record?.fresh) {
36
+ const card = [...(root?.querySelectorAll?.(".verify-verdict") || [])]
37
+ .find((candidate) => candidate.dataset.checkTurnId === record.of);
38
+ if (card) renderFresh(card, fresh);
39
+ return card || null;
40
+ }
41
+ const card = placeVerdict(root, record, opts);
42
+ if (card) renderFresh(card, fresh);
43
+ return card;
44
+ }
45
+
46
+ // The card's Verify fresh part, drawn again from +fresh+: the fresh
47
+ // verdicts, the running check, else the button (an unclear verdict, and a
48
+ // viewer who could run a turn now).
49
+ export function renderFresh(card, fresh = {}) {
50
+ const doc = card.ownerDocument;
51
+ const of = card.dataset.checkTurnId;
52
+ card.querySelector(":scope > .verify-fresh")?.remove();
53
+ const part = doc.createElement("div");
54
+ part.className = "verify-fresh";
55
+ const childLink = (id) => {
56
+ const href = id && fresh.childHref ? fresh.childHref(id) : null;
57
+ if (!href) return null;
58
+ const link = doc.createElement("a");
59
+ link.className = "verify-fresh-link";
60
+ link.href = href;
61
+ link.textContent = "open its session";
62
+ return link;
63
+ };
64
+
65
+ for (const result of (fresh.verdicts || []).filter((r) => r?.fresh && r.of === of)) {
66
+ const line = doc.createElement("p");
67
+ line.className = `verify-fresh-result ${ICONS[result.verdict] ? result.verdict : ""}`.trim();
68
+ line.textContent = `fresh: ${ICONS[result.verdict] || ""} ${result.verdict} — ${result.reason || ""}`;
69
+ const link = childLink(result.child_id);
70
+ if (link) line.append(" · ", link);
71
+ part.append(line);
72
+ }
73
+
74
+ const run = (fresh.running || []).find((entry) => runningOf(entry) === of);
75
+ if (run) {
76
+ const line = doc.createElement("p");
77
+ line.className = "verify-fresh-running";
78
+ line.textContent = "Verifying fresh…";
79
+ const link = childLink(typeof run === "string" ? null : run.child_id);
80
+ if (link) line.append(" ", link);
81
+ part.append(line);
82
+ } else if (card.classList.contains("unclear") && fresh.canStart && fresh.start) {
83
+ const button = doc.createElement("button");
84
+ button.type = "button";
85
+ button.className = "verify-fresh-btn";
86
+ button.textContent = "Verify fresh";
87
+ button.title = "A new agent checks this claim against the files, with none of this session's context";
88
+ button.addEventListener("click", () => startFresh(card, button, fresh));
89
+ part.append(button);
90
+ }
91
+
92
+ if (card.dataset.freshError) {
93
+ const line = doc.createElement("p");
94
+ line.className = "verify-fresh-error";
95
+ line.textContent = card.dataset.freshError;
96
+ part.append(line);
97
+ }
98
+ if (part.childNodes.length) card.append(part);
99
+ }
100
+
101
+ async function startFresh(card, button, fresh) {
102
+ const of = card.dataset.checkTurnId;
103
+ button.disabled = true;
104
+ button.textContent = "Starting…";
105
+ let result;
106
+ try {
107
+ result = await fresh.start(of);
108
+ } catch (error) {
109
+ result = { ok: false, error: error?.message };
110
+ }
111
+ if (result?.ok) {
112
+ delete card.dataset.freshError;
113
+ if (fresh.running && !fresh.running.some((entry) => runningOf(entry) === of)) {
114
+ fresh.running.push(result.child_id ? { of, child_id: result.child_id } : of);
115
+ }
116
+ } else {
117
+ card.dataset.freshError = result?.error || "Couldn't start a fresh check.";
118
+ }
119
+ renderFresh(card, fresh);
120
+ }
@@ -0,0 +1,17 @@
1
+ .verify-verdict{margin:8px 0 8px 14px;padding:8px 10px;border:1px solid var(--border-strong);border-left:3px solid var(--text-3);border-radius:8px;background:var(--bg-inset);font-size:13px}
2
+ .verify-verdict.confirmed{border-left-color:var(--ok);background:var(--ok-bg)}
3
+ .verify-verdict.refuted{border-left-color:var(--danger);background:var(--danger-bg-dim)}
4
+ .verify-verdict.unclear{border-left-color:var(--warn);background:var(--warn-bg)}
5
+ .verify-verdict-heading{font-weight:600;color:var(--text-bright)}
6
+ .verify-verdict-quote{margin:6px 0;color:var(--text-muted);font-style:italic;white-space:pre-wrap}
7
+ .verify-verdict-reason{margin:4px 0 6px;white-space:pre-wrap;overflow-wrap:anywhere}
8
+ .verify-verdict-link{color:var(--accent)}
9
+ .verify-fresh{margin-top:6px;padding-top:6px;border-top:1px solid var(--border)}
10
+ .verify-fresh p{margin:2px 0;white-space:pre-wrap;overflow-wrap:anywhere}
11
+ .verify-fresh-result{font-weight:600;color:var(--text-bright)}
12
+ .verify-fresh-running{color:var(--text-muted);font-style:italic}
13
+ .verify-fresh-error{color:var(--danger-text)}
14
+ .verify-fresh-link{color:var(--accent);font-weight:400}
15
+ .verify-fresh-btn{font:inherit;font-size:12px;font-weight:600;padding:3px 12px;border-radius:8px;cursor:pointer;background:var(--accent-bg);color:var(--accent);border:1px solid var(--accent-border)}
16
+ .verify-fresh-btn:hover{border-color:var(--accent)}
17
+ .verify-fresh-btn:disabled{opacity:.6;cursor:default}
@@ -49,7 +49,7 @@ module Samagotchi
49
49
 
50
50
  # What +nxt+ newly needs the user for, compared with +prev+ (nil for
51
51
  # a session not seen yet): a new question first, then a new card,
52
- # then a finished turn (notify.js attentionFor's order).
52
+ # then a finished turn or its new Verify verdict (notify.js's order).
53
53
  # @return [Event, nil]
54
54
  def for(prev, nxt)
55
55
  return nil unless nxt && nxt[:id]
@@ -70,14 +70,20 @@ module Samagotchi
70
70
  turn_event(prev, nxt)
71
71
  end
72
72
 
73
- # A top-level turn that ended since +prev+: failed, or done when it
74
- # ran long or nobody watched it. A delegated child's turn is
75
- # reported by its parent's.
73
+ # A top-level turn that ended since +prev+: its new Verify verdict,
74
+ # failed, or done when it ran long or nobody watched it. A delegated
75
+ # child's turn is reported by its parent's.
76
76
  def turn_event(prev, nxt)
77
77
  turn = nxt[:last_turn]
78
78
  return nil unless turn.is_a?(Hash) && turn["ended_at"]
79
79
  return nil if turn["ended_at"] == prev&.dig(:last_turn, "ended_at") || nxt[:parent_id]
80
80
 
81
+ verdict = nxt[:last_verdict]
82
+ if verdict.is_a?(Hash) && present?(verdict[:check_turn_id]) &&
83
+ verdict[:check_turn_id] != prev&.dig(:last_verdict, :check_turn_id)
84
+ return Event.new(reason: "verdict", session_id: nxt[:id], key: key(nxt[:id], verdict[:check_turn_id]), hold: nil)
85
+ end
86
+
81
87
  reason = case turn["outcome"]
82
88
  when "failed" then "failed"
83
89
  when "completed"
@@ -133,10 +139,24 @@ module Samagotchi
133
139
  name = (summary && [summary[:title], summary[:auto_title], summary[:recap], summary[:first_preview], summary[:last_prompt]]
134
140
  .find { |v| present?(v) }) ||
135
141
  "chi session"
136
- body = reason == "done" ? "done in #{seconds(summary&.dig(:last_turn) || {}).round} s" : BODIES.fetch(reason, "")
142
+ body = case reason
143
+ when "done" then "done in #{seconds(summary&.dig(:last_turn) || {}).round} s"
144
+ when "verdict" then verdict_text(summary&.dig(:last_verdict) || {})
145
+ else BODIES.fetch(reason, "")
146
+ end
137
147
  [clip(name.to_s.strip, TITLE_MAX), body]
138
148
  end
139
149
 
150
+ def verdict_text(verdict)
151
+ result = verdict[:verdict].to_s
152
+ icon = { "confirmed" => "✅", "refuted" => "❌", "unclear" => "❓" }.fetch(result, "")
153
+ by = verdict[:by_name]
154
+ by = verdict[:by].nil? ? "You" : "A participant" unless present?(by)
155
+ reason = clip(verdict[:reason].to_s, 120)
156
+ "#{by}: #{icon} #{result} — #{reason}"
157
+ end
158
+ private_class_method :verdict_text
159
+
140
160
  # notify.js Number(turn.seconds): anything that isn't a number is 0.
141
161
  def seconds(turn)
142
162
  value = turn["seconds"]
@@ -13,7 +13,8 @@ module Samagotchi
13
13
  # the summaries the page's trackAttention keeps (seeded by the
14
14
  # subscribe's snapshot, so what was open before never pushes), turns
15
15
  # each new attention (Attention.for: a question, an approval, a
16
- # step-limit continue, a card with actions, a failed or done turn)
16
+ # step-limit continue, a card with actions, a failed or done turn, a
17
+ # recorded Verify verdict)
17
18
  # into a show, and hands it to its own sender thread through a Queue;
18
19
  # one answered anywhere (Attention.closed_keys) only cancels its
19
20
  # show's hold.
@@ -43,7 +44,7 @@ module Samagotchi
43
44
  HOLD = 3.0
44
45
  # Waiting kinds: kept 12 h for an offline phone, delivered at once.
45
46
  SHOW_TTL = 12 * 3600
46
- # A failed or done turn: stale soon, no need to wake the phone.
47
+ # A failed, done or verdict turn: stale soon, no need to wake the phone.
47
48
  EVENT_TTL = 600
48
49
  # A newly available chi is useful for a day while the phone is away.
49
50
  UPDATE_TTL = 24 * 3600
@@ -280,7 +281,7 @@ module Samagotchi
280
281
  retries.each { |again| send_retry(again, open) if still_due?(again.show, open) }
281
282
  end
282
283
 
283
- # A waiting show while its key is open; a failed or done turn's as
284
+ # A waiting show while its key is open; a failed, done or verdict turn's as
284
285
  # is (nothing to answer).
285
286
  def still_due?(show, open) = !Attention.waiting?(show.attention.reason) || open.include?(show.attention.key)
286
287
 
@@ -196,9 +196,11 @@ module Samagotchi
196
196
 
197
197
  # no_interrupt: an attached TUI's --no-interrupt (chi --remote --attach).
198
198
  # author: the principal's (nil for the owner), never the body's.
199
+ verify = VerifyAnchor.from(body["verify"])
199
200
  result = SessionManager.deliver_turn(id, prompt: prompt.to_s, client_id: client_id, images: images,
200
201
  delivery: delivery, no_interrupt: body["no_interrupt"] == true,
201
202
  author: principal(req).author,
203
+ verify: verify,
202
204
  state_dir: @state_dir, manager: @manager,
203
205
  bridge: -> { live_bridge_client(id) })
204
206
  case result.status
@@ -1,6 +1,9 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require_relative "../session"
4
+ require_relative "../steer"
5
+ require_relative "../participants"
6
+ require_relative "../verify_fresh"
4
7
  require_relative "../recap_store"
5
8
  require_relative "../archive_store"
6
9
  require_relative "../session_metrics"
@@ -108,10 +111,31 @@ module Samagotchi
108
111
  # chi REPL's (only a worker shares it).
109
112
  pending_question: session.waiting_question(live: !!owner&.worker?),
110
113
  pending_card: up ? Bridge::PendingCard.read(session_dir) : nil,
111
- last_turn: session.last_turn&.to_file
114
+ last_turn: session.last_turn&.to_file,
115
+ # Its Verify verdicts, the fresh ones its worker hasn't taken yet
116
+ # too (VerifyFresh.verdicts_of), and the fresh checks running now
117
+ # ({of, child_id}: the card's "verifying fresh" and its link).
118
+ verdicts: VerifyFresh.verdicts_of(session, session_dir),
119
+ verify_fresh: VerifyFresh.running(session.id, state_dir: File.dirname(session_dir))
120
+ .map { |row| { of: row[:of], child_id: row[:child_id] } },
121
+ last_verdict: last_verdict(session, session_dir)
112
122
  }
113
123
  end
114
124
 
125
+ def last_verdict(session, session_dir)
126
+ raw = Array(session.verdicts).last
127
+ return unless raw.is_a?(Hash)
128
+
129
+ verdict = raw.to_h { |key, value| [key.to_sym, value] }
130
+ author = verdict[:by]
131
+ return verdict unless Steer.participant_author?(author)
132
+
133
+ participant = Participants.read(session.id, state_dir: File.dirname(session_dir))
134
+ .find { |entry| entry.id == Steer.participant_id(author) }
135
+ participant ? verdict.merge(by_name: participant.name) : verdict
136
+ end
137
+ private_class_method :last_verdict
138
+
115
139
  # The budget resolver SessionMetrics.saved_summary takes: a callable,
116
140
  # so the session's llm_context budget (config + the registry's index,
117
141
  # no network) is resolved only for a session that has a saved context
@@ -0,0 +1,110 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "../delivery"
4
+ require_relative "../participant_mode"
5
+ require_relative "../participant_messages"
6
+ require_relative "../participants"
7
+ require_relative "../session"
8
+ require_relative "../steer"
9
+ require_relative "../verify_fresh"
10
+
11
+ module Samagotchi
12
+ module Web
13
+ # POST /api/sessions/:id/verdicts/:check_turn_id/fresh, mixed into App:
14
+ # Verify fresh (VerifyFresh) for the owner and for a participant. A
15
+ # participant's is refused as their turn would be (their cap, counted
16
+ # with their fresh children's spend; a worker that predates
17
+ # participants' turns) and audited like one (participants.log,
18
+ # verify_fresh); their child runs under the boundary their grant has
19
+ # here now (ParticipantMode.live_for), saved on the child. See
20
+ # docs/internals/participants.md (Verify fresh).
21
+ module VerifyFreshRoutes
22
+ private
23
+
24
+ # Whose child it is (D6, the security review's MED-2): a verdict a
25
+ # participant's turn recorded is re-checked AS that participant
26
+ # (their author, their grant's mode, their cap), whoever clicks: its
27
+ # quote is their text, never run with the owner's power. Their link
28
+ # must still be live (else 409 author_link_ended). An owner's verdict
29
+ # is re-checked as whoever clicks: the owner's child for the owner, the
30
+ # clicking participant's for a participant. A participant who clicks
31
+ # passes their own turn's refusals first.
32
+ # @return 202 {of, running: true} (+child_id+ for the owner only)
33
+ def handle_verify_fresh(req, id, of)
34
+ clicker = principal(req).owner? ? nil : principal(req).grant
35
+ session = @session_class.load(id, state_dir: default_state_dir)
36
+ if clicker && (refused = participant_cap_refusal(clicker) || fresh_worker_refusal(session))
37
+ return verify_fresh_refused(clicker, of, *refused)
38
+ end
39
+
40
+ by = Steer.sender_author(field_of(VerifyFresh.original(session.verdicts, of), :by))
41
+ runner = by ? verdict_author_grant(id, by) : clicker
42
+ return author_link_ended(clicker, id, of, by) if by && runner.nil?
43
+ if runner && runner != clicker && (refused = participant_cap_refusal(runner) || fresh_worker_refusal(session))
44
+ return verify_fresh_refused(clicker, of, *refused, runner: runner)
45
+ end
46
+
47
+ mode = runner && ParticipantMode.live_for(session, runner, state_dir: default_state_dir)
48
+ child = VerifyFresh.start(id, of: of, author: runner&.author, mode: mode, state_dir: default_state_dir,
49
+ spawn: fresh_spawn)
50
+ audit_verify_fresh(clicker, of, status: "accepted", child: child.id, mode: mode&.to_s, runner: runner)
51
+ json_response(202, clicker ? { of: of, running: true } : { of: of, running: true, child_id: child.id })
52
+ rescue VerifyFresh::Refused => e
53
+ verify_fresh_refused(clicker, of, e.status, e.code, e.message, runner: runner)
54
+ end
55
+
56
+ # The live grant of the participant +author+ ("p:<id>") in session
57
+ # +id+, nil when it is gone, revoked or expired.
58
+ def verdict_author_grant(id, author)
59
+ grant = @grants.find(Steer.participant_id(author))
60
+ grant if grant && grant.session_id == id && grant.active?(@grants.now)
61
+ end
62
+
63
+ # 409 author_link_ended: the verdict's participant can't be charged or
64
+ # bounded any more, so no child runs for it.
65
+ def author_link_ended(clicker, id, of, author)
66
+ pid = Steer.participant_id(author)
67
+ name = Participants.read(id, state_dir: default_state_dir).find { |entry| entry.id == pid }&.name
68
+ name = pid if name.to_s.strip.empty?
69
+ detail = format(AUTHOR_LINK_ENDED, name: name)
70
+ audit_verify_fresh(clicker, of, status: "refused", reason: "author_link_ended", participant_id: pid) if clicker
71
+ error_response(409, "author_link_ended", detail)
72
+ end
73
+
74
+ AUTHOR_LINK_ENDED = "%<name>s's link has ended: their verdict can't be checked again as theirs " \
75
+ "(re-invite them, or verify the claim yourself)"
76
+
77
+ def field_of(record, key) = record && (record[key] || record[key.to_s])
78
+
79
+ # A live worker of the session that predates participants' turns runs
80
+ # no participant's turn (Delivery::REVIEW_UNAVAILABLE): no fresh
81
+ # child for one either. nil to go on.
82
+ def fresh_worker_refusal(session)
83
+ features = ParticipantMode.live_features(session, default_state_dir)
84
+ return nil if features.nil? || features.include?(Delivery::REVIEW_FEATURE)
85
+
86
+ [409, Delivery::REVIEW_UNAVAILABLE["error"], Delivery::REVIEW_UNAVAILABLE["detail"]]
87
+ end
88
+
89
+ def verify_fresh_refused(clicker, of, status, code, detail, runner: nil)
90
+ audit_verify_fresh(clicker, of, status: "refused", reason: code, runner: runner)
91
+ error_response(status, code, detail)
92
+ end
93
+
94
+ # Audited in the participants' trail when a participant clicked or the
95
+ # child runs as one: +clicker+ the participant who asked (nil: the
96
+ # owner), +runner+ whose child it is.
97
+ def audit_verify_fresh(clicker, of, status:, runner: nil, participant_id: nil, **fields)
98
+ subject = runner || clicker
99
+ return if subject.nil? && participant_id.nil?
100
+
101
+ Participants.log(subject&.session_id || clicker.session_id, :verify_fresh, state_dir: default_state_dir,
102
+ participant: subject&.id || participant_id,
103
+ asked_by: clicker ? clicker.id : "owner",
104
+ of: of.to_s[0, 64], status: status, **fields.compact)
105
+ end
106
+
107
+ def fresh_spawn = ->(**options) { @manager.spawn_session(**options) }
108
+ end
109
+ end
110
+ end
@@ -33,6 +33,7 @@ require_relative "session_setting"
33
33
  require_relative "queued_command"
34
34
  require_relative "model_profile"
35
35
  require_relative "child_reports"
36
+ require_relative "verify_fresh"
36
37
  require_relative "child_move"
37
38
  require_relative "context_absorber"
38
39
  require_relative "context_poller"
@@ -423,6 +424,7 @@ module Samagotchi
423
424
  # A change that asks to wake may start a turn here (C4), but not
424
425
  # ahead of an exit or restart a client asked for: it is a note then.
425
426
  @inbound.absorb_notes
427
+ absorb_fresh_verdicts
426
428
  return if absorb_context(wake: nothing_queued? && !@exit_requested)
427
429
 
428
430
  if (prompt = @inbound.take_initial_prompt)
@@ -659,9 +661,13 @@ module Samagotchi
659
661
  # The first prompt (spawn_session's): a delegate child's task, which is
660
662
  # its parent's although no client sent it. Its turn carries the id
661
663
  # spawn_session gave it, so a wait for it (--new --wait) names it.
664
+ # A Verify fresh child's is a Verify turn on its claim (its verdict is
665
+ # recorded and forwarded to the parent).
662
666
  def run_initial_prompt(prompt)
663
667
  @initial_turn = true
664
- run_prompt(WorkerInbound::Prompt.new(text: prompt, origin: TurnOrigin.new(enqueued_id: @session.first_turn_id)))
668
+ fresh = @session.verify_fresh
669
+ run_prompt(WorkerInbound::Prompt.new(text: prompt, origin: TurnOrigin.new(enqueued_id: @session.first_turn_id),
670
+ verify: fresh&.anchor))
665
671
  ensure
666
672
  @initial_turn = false
667
673
  end
@@ -672,7 +678,7 @@ module Samagotchi
672
678
 
673
679
  # @param prompt [WorkerInbound::Prompt]
674
680
  def run_prompt(prompt)
675
- origin = prompt.origin
681
+ origin = fresh_origin(prompt.origin)
676
682
  # A participant's turn queued before their link ended or their cap was
677
683
  # reached doesn't start (chi web refuses new ones; this is the
678
684
  # worker's check).
@@ -688,7 +694,7 @@ module Samagotchi
688
694
  @continue_offer.drop(origin)
689
695
  @turn_flow.before_prompt_turn
690
696
  run_engine_turn(prompt.text, origin: origin, max_iterations: max_iterations(prompt.no_interrupt),
691
- images: prompt.images) do |result, error|
697
+ images: prompt.images, **(prompt.verify ? { verify: prompt.verify } : {})) do |result, error|
692
698
  if error
693
699
  # The Engine announced :turn_failed (with the error's one line).
694
700
  restore_failed_turn([[prompt.text, origin, prompt.images], *@merged_this_turn], error: error)
@@ -699,6 +705,13 @@ module Samagotchi
699
705
  participant_refusal(origin.author)
700
706
  end
701
707
 
708
+ # +origin+ as this session's turns run it: a participant's Verify fresh
709
+ # child's are all theirs (VerifyFreshOrigin#origin_for).
710
+ def fresh_origin(origin)
711
+ fresh = @session&.verify_fresh
712
+ fresh ? fresh.origin_for(origin) : TurnOrigin.of(origin)
713
+ end
714
+
702
715
  # Why the participant +author+ ("p:<id>") may run no more turns, nil
703
716
  # while they may (and for the owner): "revoked" when participants.json
704
717
  # has no active entry for them (revoked, expired, never invited),
@@ -708,11 +721,11 @@ module Samagotchi
708
721
  def participant_refusal(author)
709
722
  author = Steer.sender_author(author) or return nil
710
723
 
711
- entry = Participants.read(@session_id, state_dir: @state_dir).find { |e| Steer.author_for(e.id) == author }
724
+ entry = participant_entry(author)
712
725
  return "revoked" unless entry&.active?(Time.now)
713
726
 
714
727
  cap = participant_cap(entry)
715
- return nil if @engine.metrics.spend(author) < cap
728
+ return nil if participant_spend(author) < cap
716
729
 
717
730
  cap_notice(author, entry, cap)
718
731
  "cap_reached"
@@ -725,13 +738,30 @@ module Samagotchi
725
738
  def participant_turn_stop(author)
726
739
  reason = participant_refusal(author) or return nil
727
740
 
728
- entry = Participants.read(@session_id, state_dir: @state_dir).find { |e| Steer.author_for(e.id) == author }
741
+ entry = participant_entry(author)
729
742
  name = participant_label(author, entry&.name)
730
743
  return format(REVOKED_STOP, name: name) if reason == "revoked"
731
744
 
732
745
  format(CAP_STOP, name: name, cap: participant_cap(entry))
733
746
  end
734
747
 
748
+ # +author+'s participants.json entry: this session's, a Verify fresh
749
+ # child's parent's (Session#participants_source_id); nil for none.
750
+ def participant_entry(author)
751
+ Participants.read(participants_id, state_dir: @state_dir).find { |e| Steer.author_for(e.id) == author }
752
+ end
753
+
754
+ # The session whose participants.json and audit trail this session's
755
+ # participants are in.
756
+ def participants_id = @session&.participants_source_id || @session_id
757
+
758
+ # What +author+ spent against their cap: this session's metrics (live)
759
+ # and, through Verify fresh, the parent's or the children's saved ones
760
+ # (VerifyFresh.related_spend).
761
+ def participant_spend(author)
762
+ @engine.metrics.spend(author) + VerifyFresh.related_spend(@session, author, state_dir: @state_dir)
763
+ end
764
+
735
765
  # A participant's cap in dollars: their own, else the config's.
736
766
  def participant_cap(entry) = entry&.cap.is_a?(Numeric) ? entry.cap.to_f : Web::Grants.default_cap
737
767
 
@@ -753,7 +783,7 @@ module Samagotchi
753
783
  id = Steer.participant_id(author)
754
784
  text = ParticipantMode.for_turn(@session, entry) == ParticipantMode::PAIR ? PAIR_CAP_NOTICE : CAP_NOTICE
755
785
  @engine.announce(type: :hook_notice, hook: Engine::PARTICIPANTS_HOOK, level: :warn, between_turns: true,
756
- text: format(text, name: participant_label(author, entry.name), cap: cap, session: @session_id[0, 8], id: id))
786
+ text: format(text, name: participant_label(author, entry.name), cap: cap, session: participants_id[0, 8], id: id))
757
787
  end
758
788
 
759
789
  CAP_NOTICE = "%<name>s reached their $%<cap>.2f review cap: their comments are refused until you raise it " \
@@ -774,7 +804,7 @@ module Samagotchi
774
804
  # @param origin [TurnOrigin] a participant's
775
805
  def refuse_participant_turn(origin, reason)
776
806
  TurnCheckpoint.record_refused(@session_dir, origin.enqueued_id, reason: reason, author: origin.participant_author)
777
- Participants.log(@session_id, :turn, state_dir: @state_dir, participant: origin.participant_id,
807
+ Participants.log(participants_id, :turn, state_dir: @state_dir, participant: origin.participant_id,
778
808
  enqueued_id: origin.enqueued_id, status: "refused", reason: reason)
779
809
  @engine.announce(type: :turn_dequeued, enqueued_id: origin.enqueued_id, client_id: origin.client_id)
780
810
  nil
@@ -1196,7 +1226,9 @@ module Samagotchi
1196
1226
  # Every kind of turn merges steering (a reminder turn too, which may be
1197
1227
  # a fresh worker's first), so the list is this turn's from the start.
1198
1228
  @merged_this_turn = []
1199
- origin = TurnOrigin.of(turn_args[:origin])
1229
+ origin = fresh_origin(turn_args[:origin])
1230
+ turn_args = turn_args.merge(origin: origin)
1231
+ verdicts_before = @session.verdicts.size
1200
1232
  @reporting_turn = reports_to_parent?(origin)
1201
1233
  # A participant's review turn merges no input (#pending_input_drain).
1202
1234
  @participant_turn = origin.participant?
@@ -1241,6 +1273,33 @@ module Samagotchi
1241
1273
  # turn that failed (kept with its failed note), read them.
1242
1274
  settle_child_reports(rolled_back: @turn_flow.restores != restores || merges_lost?(error))
1243
1275
  ring_parent_after_turn
1276
+ forward_fresh_verdicts(verdicts_before)
1277
+ end
1278
+
1279
+ # A Verify fresh child's verdicts this turn recorded go to its parent
1280
+ # (VerifyFresh.forward), after the save: the parent's card shows them.
1281
+ # A fresh child never rings (ChildRing.ring): nothing enters the
1282
+ # parent's conversation.
1283
+ def forward_fresh_verdicts(before)
1284
+ return unless @session.verify_fresh
1285
+
1286
+ added = @session.verdicts.drop(before)
1287
+ VerifyFresh.forward(@session, added, state_dir: @state_dir) unless added.empty?
1288
+ end
1289
+
1290
+ # The parent's side, between turns: the verdicts its Verify fresh
1291
+ # children forwarded join the session's (saved, then their files go)
1292
+ # and the UIs hear each (:verdict_recorded).
1293
+ def absorb_fresh_verdicts
1294
+ added, files = VerifyFresh.take(@session, @session_dir)
1295
+ return if files.empty?
1296
+
1297
+ return unless save_or_log(:fresh_verdicts) { save_session }
1298
+
1299
+ FileUtils.rm_f(files)
1300
+ added.each { |record| @engine.announce(type: :verdict_recorded, verdict: record) }
1301
+ rescue StandardError => e
1302
+ Log.warn(:worker, "fresh_verdicts_failed", error: e.class.name, msg: e.message)
1244
1303
  end
1245
1304
 
1246
1305
  # The delegate reports this turn took: a kept turn moves the cursors on