samagotchi 0.104.0 → 0.106.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 (103) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +70 -1
  3. data/docs/architecture.md +6 -3
  4. data/docs/cli.md +62 -19
  5. data/docs/configuration.md +10 -6
  6. data/docs/guardrails.md +69 -0
  7. data/docs/hooks.md +9 -0
  8. data/docs/internals/anthropic.md +2 -1
  9. data/docs/internals/engine.md +37 -1
  10. data/docs/internals/participants.md +229 -21
  11. data/docs/internals/prompt-caching.md +9 -0
  12. data/docs/internals/working-set.md +12 -5
  13. data/docs/plugins.md +2 -0
  14. data/docs/testing.md +23 -0
  15. data/lib/samagotchi/bridge/turn_accumulator.rb +15 -4
  16. data/lib/samagotchi/bridge.rb +45 -8
  17. data/lib/samagotchi/bridge_client.rb +4 -1
  18. data/lib/samagotchi/bundles/system/manifest.yml +1 -1
  19. data/lib/samagotchi/client_id.rb +21 -9
  20. data/lib/samagotchi/config.rb +17 -2
  21. data/lib/samagotchi/continue_offer.rb +13 -3
  22. data/lib/samagotchi/delivery.rb +10 -0
  23. data/lib/samagotchi/engine.rb +98 -8
  24. data/lib/samagotchi/guardrail_wiring.rb +13 -3
  25. data/lib/samagotchi/guardrails/review_boundary.rb +148 -0
  26. data/lib/samagotchi/guardrails.rb +1 -0
  27. data/lib/samagotchi/hook_routes.rb +5 -2
  28. data/lib/samagotchi/hooks/registry.rb +12 -3
  29. data/lib/samagotchi/idle_recap.rb +9 -0
  30. data/lib/samagotchi/last_turn.rb +5 -2
  31. data/lib/samagotchi/llm/chat_loop.rb +1 -0
  32. data/lib/samagotchi/parent_report.rb +17 -5
  33. data/lib/samagotchi/participant_messages.rb +16 -0
  34. data/lib/samagotchi/participant_name.rb +21 -0
  35. data/lib/samagotchi/participants.rb +29 -6
  36. data/lib/samagotchi/participants_watch.rb +90 -0
  37. data/lib/samagotchi/plugin/context.rb +7 -1
  38. data/lib/samagotchi/plugin/side_question.rb +9 -1
  39. data/lib/samagotchi/queued_command.rb +9 -5
  40. data/lib/samagotchi/reply_wait/poll.rb +18 -3
  41. data/lib/samagotchi/run_options.rb +1 -1
  42. data/lib/samagotchi/send_command.rb +41 -3
  43. data/lib/samagotchi/session_access/contract.rb +2 -0
  44. data/lib/samagotchi/session_access/local.rb +31 -9
  45. data/lib/samagotchi/session_access/remote.rb +19 -2
  46. data/lib/samagotchi/session_access/web_bridge_client.rb +4 -2
  47. data/lib/samagotchi/session_access.rb +6 -3
  48. data/lib/samagotchi/session_commands.rb +6 -0
  49. data/lib/samagotchi/session_inbox.rb +31 -5
  50. data/lib/samagotchi/session_manager.rb +43 -3
  51. data/lib/samagotchi/session_metrics/side_totals.rb +21 -7
  52. data/lib/samagotchi/session_metrics.rb +94 -1
  53. data/lib/samagotchi/session_participants.rb +59 -0
  54. data/lib/samagotchi/sessions_command.rb +10 -7
  55. data/lib/samagotchi/share_command.rb +61 -22
  56. data/lib/samagotchi/side_usage.rb +4 -2
  57. data/lib/samagotchi/steer.rb +120 -11
  58. data/lib/samagotchi/system_prompt.rb +21 -2
  59. data/lib/samagotchi/terminal_ui/attach_link.rb +5 -0
  60. data/lib/samagotchi/terminal_ui/attached_loop.rb +94 -22
  61. data/lib/samagotchi/terminal_ui/formatting.rb +66 -5
  62. data/lib/samagotchi/terminal_ui/local_link.rb +7 -0
  63. data/lib/samagotchi/terminal_ui/participant_commands.rb +77 -0
  64. data/lib/samagotchi/terminal_ui/reline_seam.rb +21 -1
  65. data/lib/samagotchi/terminal_ui/remote_link.rb +6 -2
  66. data/lib/samagotchi/terminal_ui/status_row.rb +11 -2
  67. data/lib/samagotchi/terminal_ui.rb +5 -0
  68. data/lib/samagotchi/testing/host.rb +4 -2
  69. data/lib/samagotchi/testing/recorder.rb +3 -1
  70. data/lib/samagotchi/toolkit.rb +21 -3
  71. data/lib/samagotchi/turn_checkpoint.rb +5 -2
  72. data/lib/samagotchi/version.rb +1 -1
  73. data/lib/samagotchi/web/app.rb +45 -20
  74. data/lib/samagotchi/web/grants.rb +89 -8
  75. data/lib/samagotchi/web/participant_access.rb +206 -35
  76. data/lib/samagotchi/web/participant_review.rb +165 -0
  77. data/lib/samagotchi/web/participant_stream_filter.rb +157 -0
  78. data/lib/samagotchi/web/participant_view.rb +415 -0
  79. data/lib/samagotchi/web/public/app.js +15 -1
  80. data/lib/samagotchi/web/public/bubbles.js +3 -3
  81. data/lib/samagotchi/web/public/data.js +20 -0
  82. data/lib/samagotchi/web/public/index.html +75 -30
  83. data/lib/samagotchi/web/public/info_bar.js +12 -5
  84. data/lib/samagotchi/web/public/info_bar_model.js +8 -5
  85. data/lib/samagotchi/web/public/participant.html +119 -0
  86. data/lib/samagotchi/web/public/participant.js +300 -0
  87. data/lib/samagotchi/web/public/participant_model.js +160 -0
  88. data/lib/samagotchi/web/public/participant_names.js +21 -0
  89. data/lib/samagotchi/web/public/participants_panel.js +311 -0
  90. data/lib/samagotchi/web/public/stream_handlers.js +8 -1
  91. data/lib/samagotchi/web/public/tokens.css +12 -0
  92. data/lib/samagotchi/web/public/turn_events.js +16 -5
  93. data/lib/samagotchi/web/public/turn_html.js +8 -4
  94. data/lib/samagotchi/web/public/turn_view.js +2 -1
  95. data/lib/samagotchi/web/public/working_set.js +6 -4
  96. data/lib/samagotchi/web/public/working_set_view.js +4 -4
  97. data/lib/samagotchi/web/qr.rb +14 -0
  98. data/lib/samagotchi/web/running.rb +52 -0
  99. data/lib/samagotchi/web/server.rb +13 -0
  100. data/lib/samagotchi/web/session_access_routes.rb +3 -0
  101. data/lib/samagotchi/worker.rb +125 -11
  102. data/lib/samagotchi/worker_inbound.rb +12 -1
  103. metadata +17 -1
@@ -1,9 +1,16 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require "cgi/escape"
3
+ require "json"
4
4
  require_relative "grants"
5
5
  require_relative "principal"
6
+ require_relative "qr"
6
7
  require_relative "../archive_store"
8
+ require_relative "../client_id"
9
+ require_relative "../delivery"
10
+ require_relative "../session_inbox"
11
+ require_relative "../session_metrics"
12
+ require_relative "../parent_report"
13
+ require_relative "../participant_messages"
7
14
  require_relative "../participants"
8
15
  require_relative "../session"
9
16
  require_relative "../log"
@@ -13,9 +20,10 @@ module Samagotchi
13
20
  # What a participant (a Web::Grants token) may do in chi web, mixed into
14
21
  # App: the gate's lookup of their grant, the refusals that are theirs
15
22
  # (token_revoked, token_expired, another session's 404, not_permitted
16
- # by role), the trimmed and filtered answers of the :participant routes,
17
- # the minimal participant page, and the running check that ends their
18
- # streams when the grant does. See docs/internals/participants.md.
23
+ # by role), the trimmed answers of the :participant routes, their turns,
24
+ # and the running check that ends their streams when the grant does
25
+ # (what they read is ParticipantReview's). See
26
+ # docs/internals/participants.md.
19
27
  module ParticipantAccess
20
28
  # A participant's refused routes are audited at most this often per
21
29
  # route (a page retrying would fill the log).
@@ -25,7 +33,7 @@ module Samagotchi
25
33
  revoked: ["token_revoked", "this review link was revoked by the session's owner"],
26
34
  expired: ["token_expired", "this review link expired: ask the session's owner for a new one"]
27
35
  }.freeze
28
- NOT_PERMITTED = "a participant can't do that: only the session's owner can"
36
+ NOT_PERMITTED = Participants::NOT_PERMITTED
29
37
 
30
38
  private
31
39
 
@@ -35,8 +43,13 @@ module Samagotchi
35
43
  @participant_peers = Hash.new { |hash, key| hash[key] = Set.new }
36
44
  @participant_refused = {}
37
45
  @participant_expired = Set.new
46
+ # enqueued_id => grant id of the turns participants sent through this
47
+ # chi web (their dequeue's check); the oldest go past PARTICIPANT_TURNS_KEPT.
48
+ @participant_turns = {}
38
49
  end
39
50
 
51
+ PARTICIPANT_TURNS_KEPT = 1000
52
+
40
53
  # The participant principal for the first of +tokens+ that is a live
41
54
  # grant's, or nil. An ended grant met on the way is kept in the
42
55
  # request's env for #token_gate's answer (#grant_ended_response). A
@@ -171,16 +184,155 @@ module Samagotchi
171
184
  .map { |entry| { id: entry.id, name: entry.name, kind: entry.kind, role: entry.role } }
172
185
  end
173
186
 
174
- # The page a participant's link opens (P2: before comments exist).
175
- # Never the owner's page, whose every route would refuse them.
176
- def participant_page(principal)
177
- grant = principal.grant
178
- session = @session_class.load(grant.session_id, state_dir: default_state_dir)
179
- name = CGI.escapeHTML(grant.name)
180
- others = participant_names(grant.session_id).map { |entry| CGI.escapeHTML(entry[:name]) }
181
- html_response(200, format(PARTICIPANT_PAGE, name: name, title: CGI.escapeHTML(participant_title(session)),
182
- status: CGI.escapeHTML(session.status.to_s),
183
- participants: others.join(", ")))
187
+ # ── A participant's turn ──────────────────────────────────────────
188
+
189
+ # POST /api/sessions/:id/turn from a participant: a review turn (D6,
190
+ # D10). Of the body only the prompt counts: the author and client id
191
+ # are the grant's (review:<id>), the delivery is always queue, no
192
+ # images, no no_interrupt; the owner's prompt history never sees it.
193
+ # Refused: a line starting ! or / (403 not_permitted: shell lines
194
+ # and commands are the owner's), images (403), their turn limit (429
195
+ # too_many_turns, the Bridge counts) and their cap (429 cap_reached).
196
+ # Every answer is audited (turn: accepted or refused, why).
197
+ def handle_participant_turn(req, id, body)
198
+ grant = principal(req).grant
199
+ prompt = body["prompt"].to_s
200
+ return error_response(400, "missing_fields", "prompt is required") if prompt.strip.empty?
201
+
202
+ reason = participant_turn_refusal(grant, prompt, body)
203
+ return participant_turn_refused(grant, prompt, *reason) if reason
204
+
205
+ result = SessionManager.deliver_turn(id, prompt: prompt, client_id: ClientId.review(grant.id),
206
+ delivery: Delivery::QUEUE, author: grant.author,
207
+ pending_limit: grant.queue_limit + 1,
208
+ state_dir: @state_dir, manager: @manager,
209
+ bridge: -> { live_bridge_client(id) })
210
+ participant_turn_result(grant, prompt, result)
211
+ rescue SessionManager::OwnedByTUI => e
212
+ owned_by_tui(e)
213
+ end
214
+
215
+ # [status, code, detail] for a turn refused before delivery, nil to send it.
216
+ def participant_turn_refusal(grant, prompt, body)
217
+ return [403, "not_permitted", NOT_PERMITTED] if prompt.lstrip.start_with?("!", "/")
218
+ return [403, "not_permitted", NOT_PERMITTED] unless body["images"].nil? || body["images"] == []
219
+
220
+ participant_cap_refusal(grant)
221
+ end
222
+
223
+ # [429, cap_reached, …] once the grant spent its cap (D7: their turns
224
+ # and the side requests they caused, from the session's saved
225
+ # analytics; a running turn's spend counts from its end, and the
226
+ # worker checks again before a queued one starts), nil before.
227
+ def participant_cap_refusal(grant)
228
+ dir = Session.session_dir(grant.session_id, state_dir: default_state_dir)
229
+ return nil if SessionMetrics.saved_spend(dir, grant.author) < grant.spend_cap
230
+
231
+ [429, "cap_reached", ParticipantMessages::CAP_REACHED]
232
+ end
233
+
234
+ def participant_turn_refused(grant, prompt, status, code, detail)
235
+ audit_turn(grant, prompt, status: "refused", reason: code)
236
+ error_response(status, code, detail)
237
+ end
238
+
239
+ def participant_turn_result(grant, prompt, result)
240
+ case result.status
241
+ when :accepted
242
+ enqueued_id = result.ack["enqueued_id"]
243
+ remember_participant_turn(enqueued_id, grant.id)
244
+ audit_turn(grant, prompt, status: "accepted", enqueued_id: enqueued_id)
245
+ json_response(202, result.ack.merge("via" => result.via.to_s, "delivery" => Delivery::QUEUE))
246
+ when :refused
247
+ audit_turn(grant, prompt, status: "refused", reason: result.ack["error"])
248
+ json_response(result.code, result.ack)
249
+ when :timeout
250
+ audit_turn(grant, prompt, status: "refused", reason: "worker_timeout")
251
+ error_response(504, "worker_timeout", result.detail)
252
+ else error_response(500, "enqueue_failed", "could not write turn input")
253
+ end
254
+ end
255
+
256
+ def audit_turn(grant, prompt, status:, **fields)
257
+ Participants.log(grant.session_id, :turn, state_dir: default_state_dir, participant: grant.id,
258
+ chars: prompt.length, status: status, **fields.compact)
259
+ end
260
+
261
+ def remember_participant_turn(enqueued_id, grant_id)
262
+ return if enqueued_id.to_s.empty?
263
+
264
+ @participant_mutex.synchronize do
265
+ @participant_turns[enqueued_id] = grant_id
266
+ @participant_turns.shift while @participant_turns.size > PARTICIPANT_TURNS_KEPT
267
+ end
268
+ end
269
+
270
+ # Whether the turn +enqueued_id+ of session +id+ is +grant+'s: chi
271
+ # web's record of who sent it, else (a chi web restarted since) its
272
+ # waiting input file's author, which only a principal stamps.
273
+ def own_turn?(grant, id, enqueued_id)
274
+ return false unless enqueued_id.is_a?(String) && !enqueued_id.empty?
275
+
276
+ sender = @participant_mutex.synchronize { @participant_turns[enqueued_id] }
277
+ return sender == grant.id if sender
278
+
279
+ SessionInbox.find_new_input_files(Session.session_dir(id, state_dir: default_state_dir)).any? do |file|
280
+ data = JSON.parse(File.read(file))
281
+ data.is_a?(Hash) && data["enqueued_id"] == enqueued_id && data["author"] == grant.author
282
+ rescue JSON::ParserError, SystemCallError
283
+ false
284
+ end
285
+ end
286
+
287
+ # GET /api/sessions/resolve?id= for a participant: their grant's
288
+ # session for its id or a prefix of it, else 404 as for no session
289
+ # (never another session's id, never an ambiguity listing them).
290
+ def participant_resolve(grant, given)
291
+ return json_response(200, { id: grant.session_id }) if grant.session_id.start_with?(given)
292
+
293
+ error_response(404, "not_found", "no session #{given[0, 80]}")
294
+ end
295
+
296
+ # POST …/wait/prepare for a participant (an agent's chi --remote
297
+ # send --wait, D11): only for a turn of theirs (+turn+, the enqueued
298
+ # id their POST …/turn answered); the body's busy, queue and created
299
+ # don't count.
300
+ def participant_wait_prepare(req, id, body)
301
+ grant = principal(req).grant
302
+ return not_permitted_for(req, principal(req)) unless own_turn?(grant, id, body["turn"])
303
+
304
+ start = session_access.prepare_wait(id, session: session_access.show(id), question_id: :pending, turn: body["turn"])
305
+ json_response(200, wait_start_json(id, start))
306
+ end
307
+
308
+ # POST …/wait for a participant: only on a turn of theirs, and the
309
+ # answer trimmed to what their turn's reply is (status, text, turn
310
+ # id, a cancel's reason): no file path, no question (an approval or a
311
+ # question their turn raised is the owner's to answer: the status
312
+ # says waiting_for_owner), no origin, no parent strategy. It waits as
313
+ # for a queued turn (theirs always is: never merged), so it never
314
+ # falls back to the next reply past a cursor, which would be anyone's;
315
+ # the body's cursor doesn't count.
316
+ def participant_wait(req, id, options)
317
+ grant = principal(req).grant
318
+ return not_permitted_for(req, principal(req)) unless own_turn?(grant, id, options[:turn])
319
+
320
+ options = options.merge(queued: true, cursor: nil)
321
+ session_access.show(id)
322
+ result = session_access.wait_reply(id, **options, poll_interval: @wait_poll_interval,
323
+ cancelled: -> { !@server_running.call })
324
+ return error_response(503, "server_stopping", "chi web is stopping; wait again") if result.status == :canceled
325
+
326
+ json_response(200, participant_wait_json(result))
327
+ end
328
+
329
+ def participant_wait_json(result)
330
+ if result.status.to_s == "waiting_for_answer"
331
+ return { status: "waiting_for_owner", detail: ParentReport::WAITING_FOR_OWNER, turn_id: result[:turn_id] }.compact
332
+ end
333
+
334
+ text = result[:text]&.dup&.force_encoding(Encoding::UTF_8)&.scrub
335
+ { status: result.status.to_s, text: text, turn_id: result[:turn_id], cancel_reason: result[:cancel_reason] }.compact
184
336
  end
185
337
 
186
338
  # Whether a principal's stream may go on (the proxy's running check,
@@ -202,21 +354,37 @@ module Samagotchi
202
354
  # or digest.
203
355
  def handle_participants_list(_req, id = nil)
204
356
  now = @grants.now
205
- json_response(200, { participants: @grants.list(session_id: id).map { |grant| grant.public_h(now) } })
357
+ grants = @grants.list(session_id: id).map { |grant| grant.public_h(now) }
358
+ json_response(200, { participants: id ? with_spend(id, grants) : grants })
206
359
  end
207
360
 
208
- # POST /api/sessions/:id/participants {name, kind?, ttl? (seconds)}:
209
- # a new grant. The answer carries the token and the link once; chi
210
- # keeps only its digest.
361
+ # One session's grants with what each spent and how many turns they
362
+ # ran (its saved analytics: SessionMetrics.saved_by_author), for the
363
+ # owner's participants panel.
364
+ def with_spend(id, grants)
365
+ rows = SessionMetrics.saved_by_author(Session.session_dir(id, state_dir: default_state_dir))
366
+ grants.map do |grant|
367
+ row = rows["p:#{grant[:id]}"] || { turns: 0, cost: 0.0 }
368
+ grant.merge(spend: row[:cost].round(4), turns: row[:turns])
369
+ end
370
+ end
371
+
372
+ # POST /api/sessions/:id/participants {name, kind?, ttl? (seconds),
373
+ # cap? (dollars)}: a new grant. The answer carries the token and the
374
+ # link once; chi keeps only its digest.
211
375
  def handle_participants_invite(req, id)
212
376
  body = body_hash(req) or return error_response(400, "invalid_json", "invalid JSON body")
213
377
  ttl = body["ttl"]
214
378
  return error_response(400, "invalid_participant", "ttl is a number of seconds") unless ttl.nil? || ttl.is_a?(Integer)
215
379
 
380
+ cap = body["cap"]
381
+ return error_response(400, "invalid_participant", Grants::CAP_RANGE) unless cap.nil? || Grants.cap?(cap)
382
+
216
383
  issued = Participants.invite(@grants, session_id: id, name: body["name"], kind: (body["kind"] || "human").to_s,
217
- ttl: ttl, state_dir: default_state_dir)
384
+ ttl: ttl, cap: cap, state_dir: default_state_dir)
385
+ link = participant_link(req, id, issued.token)
218
386
  json_response(201, { participant: issued.grant.public_h(@grants.now), token: issued.token,
219
- link: participant_link(req, id, issued.token), lan: !@lan.nil? })
387
+ link: link, lan: !@lan.nil?, qr_svg: QR.svg(link) })
220
388
  rescue Grants::Invalid => e
221
389
  error_response(400, "invalid_participant", e.message)
222
390
  end
@@ -235,6 +403,23 @@ module Samagotchi
235
403
  json_response(200, { revoked: revoked.map { |grant| grant.public_h(now) } })
236
404
  end
237
405
 
406
+ # POST /api/sessions/:id/participants/:participant/cap {cap}: the
407
+ # active participant's new spending cap (dollars), from their next
408
+ # turn on. 200 {participant}; 400 invalid_participant.
409
+ def handle_participants_cap(req, id, grant_id)
410
+ body = body_hash(req) or return error_response(400, "invalid_json", "invalid JSON body")
411
+ unless Grants::ID_RE.match?(grant_id.to_s)
412
+ return error_response(400, "invalid_participant", "not a participant id: #{grant_id.to_s[0, 40]}")
413
+ end
414
+
415
+ grant = Participants.set_cap(@grants, session_id: id, id: grant_id, cap: body["cap"], state_dir: default_state_dir)
416
+ return error_response(400, "invalid_participant", Participants.no_participant(grant_id, id)) unless grant
417
+
418
+ json_response(200, { participant: grant.public_h(@grants.now) })
419
+ rescue Grants::Invalid => e
420
+ error_response(400, "invalid_participant", e.message)
421
+ end
422
+
238
423
  # The link a participant opens: this chi web's LAN address when it has
239
424
  # one (the owner may be asking on loopback), else the Host asked; the
240
425
  # token traded for the cookie, the session in the fragment.
@@ -256,20 +441,6 @@ module Samagotchi
256
441
  .meta { opacity: .75; }
257
442
  CSS
258
443
 
259
- PARTICIPANT_PAGE = <<~HTML
260
- <!doctype html>
261
- <html lang="en"><head><meta charset="utf-8">
262
- <meta name="viewport" content="width=device-width, initial-scale=1">
263
- <title>chi · %<name>s's review</title>
264
- <style>#{PAGE_STYLE}</style></head>
265
- <body>
266
- <h1>%<name>s's review</h1>
267
- <p class="meta">%<title>s · %<status>s</p>
268
- <p>Comments open soon: the owner will see what you write here.</p>
269
- <p class="meta">Participants: %<participants>s</p>
270
- </body></html>
271
- HTML
272
-
273
444
  ENDED_PAGE = <<~HTML
274
445
  <!doctype html>
275
446
  <html lang="en"><head><meta charset="utf-8">
@@ -0,0 +1,165 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "participant_view"
4
+ require_relative "participant_stream_filter"
5
+ require_relative "../session_metrics"
6
+
7
+ module Samagotchi
8
+ module Web
9
+ # What a participant reads, mixed into App (P4a): their page, its data
10
+ # (GET /api/sessions/:id/review) and their stream, each through
11
+ # ParticipantView. The owner reaches the same reads as "the participant
12
+ # view": the page at /?as=participant, the review route, and the stream
13
+ # with ?as=participant, through the same filter with no participant of
14
+ # their own (nothing is "mine", no composer). See
15
+ # docs/internals/participants.md (What a participant sees).
16
+ module ParticipantReview
17
+ PARTICIPANT_VIEW = "participant"
18
+ # The stream's query keys a filtered stream passes to the Bridge: its
19
+ # cursor and its join. Not client_id (a stream named as a TUI's would
20
+ # count as one), not raw.
21
+ STREAM_KEYS = %w[from_seq snapshot].freeze
22
+
23
+ private
24
+
25
+ # Whether this request reads as a participant: a participant's, or
26
+ # the owner's with ?as=participant.
27
+ def participant_view?(req)
28
+ !principal(req).owner? || req.params["as"] == PARTICIPANT_VIEW
29
+ end
30
+
31
+ # Who reads: the participant (their author), or the owner through the
32
+ # participant view (nobody's own). The session's folder places tool
33
+ # paths; the owner's token is never shown.
34
+ def participant_viewer(req, session)
35
+ author = principal(req).owner? ? nil : principal(req).grant.author
36
+ ParticipantView::Viewer.new(author: author, cwd: session.working_directory, secrets: [@lan && current_token].compact)
37
+ end
38
+
39
+ # GET /api/sessions/:id/review: the participant page's data, always
40
+ # filtered (the owner gets the participant view of it).
41
+ # @return {viewer, session, participants, messages, current_turn,
42
+ # waiting_for_owner, queued: {mine, others}, last_event_id}
43
+ def handle_review(req, id)
44
+ session = @session_class.load(id, state_dir: default_state_dir)
45
+ viewer = participant_viewer(req, session)
46
+ live = bridge_get_json(id, "snapshot")
47
+ turn_snapshot = live && live["snapshot"]
48
+ state = live && live["session_state_snapshot"]
49
+ raw = live_or_saved(turn_snapshot, "messages") { session.messages }
50
+ shown = messages_for_display(visible_replies(raw), parts: true, cwd: session.working_directory)
51
+ current = turn_snapshot && ParticipantView.current_turn(turn_snapshot["current_turn"], viewer)
52
+ automatic = automatic_turn_ids(id, session, shown, current, state)
53
+ waiting = !!(current&.dig("waiting_for_owner") || turn_snapshot&.dig("continue_offer") ||
54
+ (turn_snapshot && !turn_snapshot["current_turn"] && turn_snapshot["pending_question"]))
55
+ json_response(200, {
56
+ viewer: review_viewer(req, id),
57
+ session: { id: session.id, title: participant_title(session), status: displayed_status(session, state) },
58
+ participants: participant_names(id).map { |entry| entry.slice(:id, :name, :kind) },
59
+ messages: with_reply_html(ParticipantView.messages(shown, viewer, automatic: automatic)),
60
+ current_turn: current,
61
+ waiting_for_owner: waiting,
62
+ queued: review_queue(snapshot_list(turn_snapshot, "queued"), viewer),
63
+ last_event_id: turn_snapshot && turn_snapshot["event_id"]
64
+ })
65
+ end
66
+
67
+ # The saved messages with each model message's content as a
68
+ # participant may read it (ParticipantView.visible_raw: no cut-off
69
+ # thought or tool call left as text).
70
+ def visible_replies(raw)
71
+ Array(raw).map do |message|
72
+ next message unless message.is_a?(Hash) && %w[model assistant].include?((message[:role] || message["role"]).to_s)
73
+
74
+ key = message.key?(:content) ? :content : "content"
75
+ content = message[key]
76
+ content.is_a?(String) ? message.merge(key => ParticipantView.visible_raw(content)) : message
77
+ end
78
+ end
79
+
80
+ # The ids of the turns no person sent, whose prompt a participant
81
+ # doesn't read: the turn records marked automatic (the saved ones and
82
+ # the live worker's, which has a finished turn's before it is saved),
83
+ # the running turn's when its start says so (its prompt is the last),
84
+ # and a delegate child's first turn (its task, the parent's text,
85
+ # came with no client).
86
+ def automatic_turn_ids(id, session, shown, current, state)
87
+ live = state.is_a?(Hash) && state["metrics"].is_a?(Hash) ? Array(state["metrics"]["turn_records"]) : []
88
+ records = Array(read_analytics(id)&.fetch("turn_records", nil)) + live
89
+ ids = records.filter_map { |record| record["id"].to_s if record.is_a?(Hash) && record["automatic"] }
90
+ prompts = shown.select { |message| message[:role] == "user" && message[:turn_id] }
91
+ ids << prompts.last[:turn_id].to_s if current&.dig("automatic") && prompts.last
92
+ ids << prompts.first[:turn_id].to_s if delegate_child?(session) && prompts.first
93
+ ids
94
+ end
95
+
96
+ # Session.load reads the parent sidecar over the file's field.
97
+ def delegate_child?(session) = !session.parent_id.to_s.empty?
98
+
99
+ # Who is reading: a participant (their id, name, whether they may
100
+ # comment: not once their cap is reached), or the owner looking
101
+ # through the participant view (no composer).
102
+ def review_viewer(req, id)
103
+ return { kind: "owner", can_comment: false } if principal(req).owner?
104
+
105
+ grant = principal(req).grant
106
+ capped = !participant_cap_refusal(grant).nil?
107
+ { kind: "participant", id: grant.id, name: grant.name, participant_kind: grant.kind, can_comment: !capped,
108
+ cap_reached: capped, session_id: id }
109
+ end
110
+
111
+ # The queue as a participant sees it: their own queued turns (the
112
+ # enqueued id, for dequeue, and the text), and how many others wait.
113
+ def review_queue(queued, viewer)
114
+ mine, others = queued.partition { |entry| entry.is_a?(Hash) && viewer.own?(entry["author"]) }
115
+ { mine: mine.map { |entry| ParticipantView::Redact.deep({ "enqueued_id" => entry["enqueued_id"].to_s, "prompt" => entry["prompt"].to_s }, viewer) },
116
+ others: others.size }
117
+ end
118
+
119
+ # Each reply's rendered markdown, from its filtered (redacted) text.
120
+ def with_reply_html(messages)
121
+ return messages unless @markdown_renderer.available?
122
+
123
+ messages.map do |message|
124
+ next message unless message["role"] == "assistant" && !message["content"].strip.empty?
125
+
126
+ message.merge("html" => @markdown_renderer.render(message["content"]))
127
+ end
128
+ end
129
+
130
+ # The page a participant's link opens, and the owner's participant
131
+ # view (/?as=participant#s=<id>): the participant page's shell; its
132
+ # script reads everything through the review route and the filtered
133
+ # stream.
134
+ def participant_shell(req)
135
+ path = File.join(@public_dir, "participant.html")
136
+ return error_response(500, "missing_page", "participant.html is missing") unless File.file?(path)
137
+
138
+ attrs = { "version" => Samagotchi::VERSION }
139
+ if principal(req).owner?
140
+ attrs["viewer"] = "owner"
141
+ else
142
+ grant = principal(req).grant
143
+ attrs.merge!("viewer" => "participant", "session" => grant.session_id, "name" => grant.name)
144
+ end
145
+ data = attrs.map { |key, value| %(data-#{key}="#{Rack::Utils.escape_html(value)}") }.join(" ")
146
+ html_response(200, File.read(path).sub("<body>", "<body #{data}>"))
147
+ end
148
+
149
+ # A filtered stream's frame filter (App#stream_filter), for the
150
+ # session +id+.
151
+ def participant_stream_filter(req, id)
152
+ session = @session_class.load(id, state_dir: default_state_dir)
153
+ ParticipantStreamFilter.new(participant_viewer(req, session))
154
+ end
155
+
156
+ # A filtered stream's query: only its cursor and its join.
157
+ def participant_stream_query(req)
158
+ pairs = URI.decode_www_form(req.query_string.to_s).select { |key, _| STREAM_KEYS.include?(key) }
159
+ pairs.empty? ? "" : "?#{URI.encode_www_form(pairs)}"
160
+ rescue ArgumentError
161
+ ""
162
+ end
163
+ end
164
+ end
165
+ end
@@ -0,0 +1,157 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "json"
4
+ require_relative "participant_view"
5
+
6
+ module Samagotchi
7
+ module Web
8
+ # A participant's stream (App#stream_filter): the Bridge's SSE bytes,
9
+ # read in chunks that split frames anywhere, cut into whole frames, and
10
+ # each frame's event rebuilt by ParticipantView.event. A frame whose
11
+ # event is dropped sends nothing; a comment (the Bridge's `: ping`)
12
+ # goes on as a ping; anything that doesn't parse is dropped. Frames are
13
+ # written again from the filtered event (its `id:` the Bridge's cursor,
14
+ # `event:` the filtered type), never passed through as bytes.
15
+ #
16
+ # The reply's text is sent by whole lines: a secret the model streams
17
+ # over two chunks is redacted as one (Redact sees the line), and a
18
+ # private key block is withheld from its BEGIN line to its END line.
19
+ # The rest of a line waits for its end, a boundary (a tool call, the
20
+ # turn's end, the owner's question) or MAX_HELD characters (then up to
21
+ # its last space).
22
+ #
23
+ # One per stream (it keeps the partial frame and line between chunks),
24
+ # called from the stream's one thread.
25
+ class ParticipantStreamFilter
26
+ # A partial frame longer than this is dropped (and the rest of it, up
27
+ # to its end): a participant's stream never buffers without bound.
28
+ MAX_FRAME_BYTES = 1_048_576
29
+ FRAME_END = /\r?\n\r?\n/
30
+ PING = ": ping\r\n\r\n"
31
+ # An SSE id is the Bridge's `<seq>-<epoch>` (EventId) or a plain seq.
32
+ EVENT_ID = /\A[0-9A-Za-z.-]{1,64}\z/
33
+ MAX_HELD = 400
34
+ # The events before which the held text goes out.
35
+ FLUSH_BEFORE = %w[tool_call_started turn_completed turn_canceled turn_failed question_requested continue_offered
36
+ snapshot reset].freeze
37
+ PEM_BEGIN = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/
38
+ PEM_END = /-----END [A-Z0-9 ]*PRIVATE KEY-----/
39
+
40
+ def initialize(viewer)
41
+ @viewer = viewer
42
+ @buffer = +""
43
+ @skipping = false
44
+ @held = +""
45
+ @held_iteration = nil
46
+ @in_key = false
47
+ end
48
+
49
+ # @param chunk [String] the Bridge's next read
50
+ # @return [String] the frames to send ("" for none)
51
+ def call(chunk)
52
+ @buffer << chunk.to_s.b
53
+ out = +""
54
+ while (match = FRAME_END.match(@buffer))
55
+ frame = @buffer[0, match.begin(0)]
56
+ @buffer = @buffer[match.end(0)..]
57
+ if @skipping
58
+ @skipping = false
59
+ next
60
+ end
61
+ out << rewrite(frame)
62
+ end
63
+ if @buffer.bytesize > MAX_FRAME_BYTES
64
+ @buffer = +""
65
+ @skipping = true
66
+ end
67
+ out
68
+ end
69
+
70
+ private
71
+
72
+ def rewrite(frame)
73
+ text = frame.dup.force_encoding(Encoding::UTF_8)
74
+ return "" unless text.valid_encoding?
75
+
76
+ lines = text.split(/\r?\n/)
77
+ return PING if lines.all? { |line| line.start_with?(":") }
78
+
79
+ id = nil
80
+ data = []
81
+ lines.each do |line|
82
+ if line.start_with?("id:") then id = line.delete_prefix("id:").strip
83
+ elsif line.start_with?("data:") then data << line.delete_prefix("data:").delete_prefix(" ")
84
+ end
85
+ end
86
+ event = parse(data.join("\n")) or return ""
87
+ shown = ParticipantView.event(event, @viewer) or return ""
88
+ id = nil unless id && EVENT_ID.match?(id)
89
+ return chunk(event, shown, id) if shown["type"] == "generation_chunk"
90
+
91
+ if shown["type"] == "generation_retrying" && shown["restarted"]
92
+ @held = +""
93
+ return frame(id, shown)
94
+ end
95
+ return flush + frame(id, shown) if FLUSH_BEFORE.include?(shown["type"])
96
+
97
+ frame(id, shown)
98
+ end
99
+
100
+ # A reply chunk: its text joins the held line; the whole lines go out.
101
+ def chunk(event, shown, id)
102
+ @held_iteration = shown["iteration"]
103
+ @held << event["text"].to_s
104
+ cut = @held.rindex("\n")
105
+ cut ||= @held.rindex(/\s/) if @held.size > MAX_HELD
106
+ cut ||= @held.size - 1 if @held.size > MAX_HELD * 4
107
+ return "" unless cut
108
+
109
+ text = @held[0..cut]
110
+ @held = @held[(cut + 1)..]
111
+ out = lines_of(text)
112
+ out.empty? ? "" : frame(id, shown.merge("text" => out))
113
+ end
114
+
115
+ # The held text as a chunk of its own (no cursor), before a boundary.
116
+ def flush
117
+ return "" if @held.empty?
118
+
119
+ text = lines_of(@held)
120
+ @held = +""
121
+ return "" if text.empty?
122
+
123
+ frame(nil, { "type" => "generation_chunk", "text" => text, **(@held_iteration ? { "iteration" => @held_iteration } : {}) })
124
+ end
125
+
126
+ # +text+'s lines redacted, a private key block's withheld whole.
127
+ def lines_of(text)
128
+ text.each_line.map do |line|
129
+ if @in_key
130
+ @in_key = false if PEM_END.match?(line)
131
+ next ""
132
+ end
133
+ if PEM_BEGIN.match?(line) && !PEM_END.match?(line)
134
+ @in_key = true
135
+ next "#{ParticipantView::Redact::MARK}#{"\n" if line.end_with?("\n")}"
136
+ end
137
+ ParticipantView::Redact.text(line, @viewer)
138
+ end.join
139
+ end
140
+
141
+ def frame(id, shown)
142
+ lines = []
143
+ lines << "id: #{id}" if id
144
+ lines << "event: #{shown["type"]}"
145
+ lines << "data: #{JSON.generate(shown)}"
146
+ "#{lines.join("\r\n")}\r\n\r\n"
147
+ end
148
+
149
+ def parse(json)
150
+ value = JSON.parse(json)
151
+ value.is_a?(Hash) ? value : nil
152
+ rescue JSON::ParserError
153
+ nil
154
+ end
155
+ end
156
+ end
157
+ end