samagotchi 0.105.0 → 0.107.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 (131) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +168 -1
  3. data/bin/chi +2 -0
  4. data/docs/architecture.md +10 -3
  5. data/docs/cli.md +90 -9
  6. data/docs/configuration.md +9 -5
  7. data/docs/guardrails.md +63 -1
  8. data/docs/hooks.md +9 -0
  9. data/docs/internals/engine.md +22 -4
  10. data/docs/internals/participants.md +319 -45
  11. data/docs/internals/prompt-caching.md +2 -1
  12. data/docs/internals/remote-sessions.md +12 -5
  13. data/docs/internals/working-set.md +8 -2
  14. data/docs/plugins.md +31 -1
  15. data/docs/releasing.md +2 -0
  16. data/docs/sessions.md +36 -1
  17. data/docs/sub-agent.md +2 -0
  18. data/docs/testing.md +5 -1
  19. data/lib/samagotchi/bridge/turn_accumulator.rb +19 -3
  20. data/lib/samagotchi/bridge.rb +39 -1
  21. data/lib/samagotchi/bridge_client/stream_request.rb +10 -3
  22. data/lib/samagotchi/bridge_client.rb +4 -1
  23. data/lib/samagotchi/bundles/coordinator/manifest.yml +6 -5
  24. data/lib/samagotchi/bundles/coordinator/plugin.rb +85 -5
  25. data/lib/samagotchi/bundles/coordinator/skill_coordinator.md +18 -0
  26. data/lib/samagotchi/bundles/dev/manifest.yml +2 -2
  27. data/lib/samagotchi/bundles/system/manifest.yml +1 -1
  28. data/lib/samagotchi/client_id.rb +21 -9
  29. data/lib/samagotchi/config.rb +16 -1
  30. data/lib/samagotchi/continue_offer.rb +60 -3
  31. data/lib/samagotchi/delivery.rb +10 -0
  32. data/lib/samagotchi/engine.rb +62 -6
  33. data/lib/samagotchi/guardrail_wiring.rb +13 -3
  34. data/lib/samagotchi/guardrails/review_boundary.rb +97 -0
  35. data/lib/samagotchi/guardrails/review_paths.rb +93 -0
  36. data/lib/samagotchi/guardrails.rb +1 -0
  37. data/lib/samagotchi/hook_routes.rb +5 -2
  38. data/lib/samagotchi/hooks/registry.rb +12 -3
  39. data/lib/samagotchi/idle_recap.rb +9 -0
  40. data/lib/samagotchi/model_profile.rb +5 -3
  41. data/lib/samagotchi/parent_report.rb +39 -5
  42. data/lib/samagotchi/participant_messages.rb +27 -0
  43. data/lib/samagotchi/participants.rb +46 -9
  44. data/lib/samagotchi/participants_watch.rb +90 -0
  45. data/lib/samagotchi/plugin/api.rb +2 -1
  46. data/lib/samagotchi/plugin/context.rb +7 -1
  47. data/lib/samagotchi/plugin/sessions.rb +25 -0
  48. data/lib/samagotchi/plugin/side_question.rb +9 -1
  49. data/lib/samagotchi/remote_command.rb +1 -1
  50. data/lib/samagotchi/remotes.rb +23 -8
  51. data/lib/samagotchi/reply_wait/poll.rb +18 -3
  52. data/lib/samagotchi/review_apply.rb +123 -0
  53. data/lib/samagotchi/review_command.rb +121 -0
  54. data/lib/samagotchi/review_start.rb +161 -0
  55. data/lib/samagotchi/run_options.rb +18 -3
  56. data/lib/samagotchi/send_command/wait_target.rb +5 -0
  57. data/lib/samagotchi/send_command.rb +43 -3
  58. data/lib/samagotchi/session.rb +33 -5
  59. data/lib/samagotchi/session_access/contract.rb +12 -2
  60. data/lib/samagotchi/session_access/dispatch.rb +8 -2
  61. data/lib/samagotchi/session_access/http_transport.rb +10 -1
  62. data/lib/samagotchi/session_access/local.rb +50 -11
  63. data/lib/samagotchi/session_access/remote.rb +34 -3
  64. data/lib/samagotchi/session_access/web_bridge_client.rb +1 -1
  65. data/lib/samagotchi/session_access.rb +29 -13
  66. data/lib/samagotchi/session_chain.rb +10 -2
  67. data/lib/samagotchi/session_commands.rb +6 -0
  68. data/lib/samagotchi/session_continue.rb +4 -3
  69. data/lib/samagotchi/session_inbox.rb +31 -5
  70. data/lib/samagotchi/session_manager.rb +68 -6
  71. data/lib/samagotchi/session_metrics/side_totals.rb +21 -7
  72. data/lib/samagotchi/session_metrics.rb +88 -1
  73. data/lib/samagotchi/session_review.rb +28 -0
  74. data/lib/samagotchi/share_command.rb +68 -23
  75. data/lib/samagotchi/side_usage.rb +4 -2
  76. data/lib/samagotchi/steer.rb +37 -1
  77. data/lib/samagotchi/terminal_ui/attach_link.rb +5 -0
  78. data/lib/samagotchi/terminal_ui/attached_loop.rb +58 -8
  79. data/lib/samagotchi/terminal_ui/formatting.rb +66 -5
  80. data/lib/samagotchi/terminal_ui/local_link.rb +7 -0
  81. data/lib/samagotchi/terminal_ui/participant_commands.rb +77 -0
  82. data/lib/samagotchi/terminal_ui/remote_link.rb +6 -2
  83. data/lib/samagotchi/terminal_ui/status_row.rb +11 -2
  84. data/lib/samagotchi/terminal_ui.rb +5 -0
  85. data/lib/samagotchi/testing/host.rb +4 -2
  86. data/lib/samagotchi/testing/recorder.rb +3 -1
  87. data/lib/samagotchi/testing/sessions.rb +10 -2
  88. data/lib/samagotchi/toolkit.rb +21 -3
  89. data/lib/samagotchi/turn_checkpoint.rb +13 -0
  90. data/lib/samagotchi/version.rb +1 -1
  91. data/lib/samagotchi/web/app.rb +151 -41
  92. data/lib/samagotchi/web/grants.rb +172 -18
  93. data/lib/samagotchi/web/participant_access.rb +273 -46
  94. data/lib/samagotchi/web/participant_review.rb +208 -0
  95. data/lib/samagotchi/web/participant_stream_filter.rb +258 -0
  96. data/lib/samagotchi/web/participant_view.rb +426 -0
  97. data/lib/samagotchi/web/public/app.js +75 -6
  98. data/lib/samagotchi/web/public/bubbles.js +3 -3
  99. data/lib/samagotchi/web/public/chip_popover.js +10 -3
  100. data/lib/samagotchi/web/public/data.js +30 -2
  101. data/lib/samagotchi/web/public/delivery_line.js +79 -15
  102. data/lib/samagotchi/web/public/index.html +97 -27
  103. data/lib/samagotchi/web/public/info_bar.js +17 -6
  104. data/lib/samagotchi/web/public/info_bar_model.js +15 -6
  105. data/lib/samagotchi/web/public/live_turn.js +3 -0
  106. data/lib/samagotchi/web/public/participant.html +172 -0
  107. data/lib/samagotchi/web/public/participant.js +447 -0
  108. data/lib/samagotchi/web/public/participant_model.js +220 -0
  109. data/lib/samagotchi/web/public/participant_names.js +53 -0
  110. data/lib/samagotchi/web/public/participants_panel.js +379 -0
  111. data/lib/samagotchi/web/public/question_cards.js +1 -0
  112. data/lib/samagotchi/web/public/review_apply.js +34 -0
  113. data/lib/samagotchi/web/public/review_start.js +101 -0
  114. data/lib/samagotchi/web/public/send_turn.js +25 -1
  115. data/lib/samagotchi/web/public/session_actions.js +44 -3
  116. data/lib/samagotchi/web/public/session_state.js +3 -0
  117. data/lib/samagotchi/web/public/start_page.js +38 -2
  118. data/lib/samagotchi/web/public/stream_handlers.js +18 -1
  119. data/lib/samagotchi/web/public/tokens.css +12 -0
  120. data/lib/samagotchi/web/public/turn_events.js +16 -5
  121. data/lib/samagotchi/web/public/turn_html.js +9 -4
  122. data/lib/samagotchi/web/public/turn_view.js +7 -1
  123. data/lib/samagotchi/web/public/working_set_view.js +3 -3
  124. data/lib/samagotchi/web/qr.rb +14 -0
  125. data/lib/samagotchi/web/running.rb +52 -0
  126. data/lib/samagotchi/web/server.rb +13 -0
  127. data/lib/samagotchi/web/session_access_routes.rb +3 -0
  128. data/lib/samagotchi/web/session_summary.rb +3 -0
  129. data/lib/samagotchi/worker.rb +121 -7
  130. data/lib/samagotchi/worker_inbound.rb +12 -4
  131. metadata +22 -1
@@ -119,9 +119,12 @@ module Samagotchi
119
119
  # cancels the running turn (true when it did); +steer+ takes (text:,
120
120
  # hook:) and puts the text into the running turn (Engine#steer, true
121
121
  # when queued); +stop_generation+ takes (reason:, hook:) and cuts the
122
- # streaming generation while the turn goes on (true when it did). A
123
- # registry without one gives hooks no-op helpers.
124
- Runtime = Struct.new(:notify, :ask_user, :stop_turn, :steer, :stop_generation, keyword_init: true)
122
+ # streaming generation while the turn goes on (true when it did);
123
+ # +turn_author+ returns the running turn's author when a participant
124
+ # wrote it ("p:<id>"), nil for the owner's (every event of such a turn
125
+ # carries it as author:). A registry without one gives hooks no-op
126
+ # helpers.
127
+ Runtime = Struct.new(:notify, :ask_user, :stop_turn, :steer, :stop_generation, :turn_author, keyword_init: true)
125
128
 
126
129
  # A thread-safe registry for named hook callbacks.
127
130
  #
@@ -386,6 +389,12 @@ module Samagotchi
386
389
  def with_runtime(event)
387
390
  return unless event.is_a?(Hash)
388
391
 
392
+ # A participant's turn: its events say whose it is (the owner's
393
+ # carry no author:, as before).
394
+ if !event.key?(:author) && (author = @runtime&.turn_author&.call)
395
+ event[:author] = author
396
+ end
397
+
389
398
  event[:notify] ||= lambda { |text, level: :info, fallback_for: nil|
390
399
  notice = { text: text.to_s, level: level, hook: event[:hook] }
391
400
  notice[:fallback_for] = fallback_for unless fallback_for.nil?
@@ -55,6 +55,8 @@ module Samagotchi
55
55
  TOOL_OUTPUT_SEPARATOR = "\n\n---\n\n"
56
56
  TOOL_OUTPUT_HEADER_RE = /\A\[([\w.:-]+)\]/
57
57
  DELEGATE_REPORT_LINE = "(a delegate session's report, delivered by chi; not the user's words)"
58
+ # A participant's message (chi share): a reviewer's, not the user's.
59
+ PARTICIPANT_LINE = "(a review contribution from %s, a participant; not the user's words)"
58
60
 
59
61
  module_function
60
62
 
@@ -75,6 +77,8 @@ module Samagotchi
75
77
  # A delegate child's report (ChildReports) is chi's news, not
76
78
  # what the user said.
77
79
  content = "#{DELEGATE_REPORT_LINE}\n#{content}" if message["source"].to_s == Steer::DELEGATE_REPORT
80
+ # A participant's is theirs, by the name it was saved with.
81
+ content = "#{participant_line(message)}\n#{content}" if Steer.participant_message?(message)
78
82
  images = ImageRef.placeholder_only?(content) ? [] : image_lines(message["images"])
79
83
  [content, *images].reject(&:empty?).join("\n")
80
84
  when "model", "assistant"
@@ -97,6 +101,11 @@ module Samagotchi
97
101
  end
98
102
  end
99
103
 
104
+ def participant_line(message)
105
+ name = ParticipantName.clean(message["author_name"])
106
+ format(PARTICIPANT_LINE, name.empty? ? "a participant" : name)
107
+ end
108
+
100
109
  def image_lines(images)
101
110
  Array(images).filter_map { |ref| "[image #{ref["name"] || File.basename(ref["file"].to_s)}]" if ref.is_a?(Hash) }
102
111
  end
@@ -228,8 +228,10 @@ module Samagotchi
228
228
  # @param lists [#read] ModelListStore by default
229
229
  # @param relist [#call, nil] how a miss re-lists the host:
230
230
  # (host_name, env) -> ids or nil. HostRegistry#list_models by default.
231
+ # @param now [Integer] epoch seconds the saved list's age is judged at
232
+ # (one clock read for both the TTL and the re-list age)
231
233
  # @return [String, nil]
232
- def self.model_warning(model_name, env: ENV, hosts: nil, lists: nil, relist: nil)
234
+ def self.model_warning(model_name, env: ENV, hosts: nil, lists: nil, relist: nil, now: Time.now.to_i)
233
235
  require_relative "config"
234
236
  require_relative "model_list_store"
235
237
  hosts ||= Samagotchi::ConfigFile.hosts_config(env: env)
@@ -241,13 +243,13 @@ module Samagotchi
241
243
  return nil if hosts[host.to_s.strip.downcase]&.models&.key?(parsed.id.to_s.strip.downcase)
242
244
 
243
245
  list = lists.read(env: env)[host.to_s.strip.downcase]
244
- return nil if list.nil? || list.stale? || list.known?(parsed.id)
246
+ return nil if list.nil? || list.stale?(now: now) || list.known?(parsed.id)
245
247
  # A saved list this recent is taken at its word. Re-listing every miss
246
248
  # would make each launch of an id a host serves but never lists (a
247
249
  # gateway's round-robin aliases) pay the re-list's cap and warn
248
250
  # anyway; a list that old is the case worth catching (a one-model
249
251
  # server reloaded with another model).
250
- return unknown_model_message(parsed.id, host, list.ids) if list.age < RELIST_AFTER_SECONDS
252
+ return unknown_model_message(parsed.id, host, list.ids) if list.age(now: now) < RELIST_AFTER_SECONDS
251
253
 
252
254
  fresh_ids = relist_or_nil(relist || default_relist(hosts), host, env)
253
255
  # A re-list that answered: the saved list catches up. The default
@@ -9,6 +9,7 @@ require_relative "pending_question"
9
9
  require_relative "session"
10
10
  require_relative "turn_checkpoint"
11
11
  require_relative "guardrails/parent_policy"
12
+ require_relative "participant_messages"
12
13
 
13
14
  module Samagotchi
14
15
  # How a wait's end (ReplyWait::Result) reads to whoever runs chi as a
@@ -33,15 +34,25 @@ module Samagotchi
33
34
  end
34
35
  end
35
36
 
37
+ # A participant's turn waiting on the session's owner (a question or
38
+ # approval it raised, the owner's step-limit Continue offer it is held
39
+ # for): what chi web's participant wait says, and how it reads here.
40
+ WAITING_FOR_OWNER = "waiting for the session's owner"
41
+
36
42
  module_function
37
43
 
38
44
  # @param result [ReplyWait::Result]
39
45
  # @return [String] answered, question, failed, canceled, limit (the
40
46
  # turn ran out of iterations, nobody asked), not_continued (a Stop
41
47
  # answered the step-limit question), removed (the queued message was
42
- # taken back before it ran), no_answer, error, worker_gone, stopped
43
- # or running
48
+ # taken back before it ran), no_answer, error, worker_gone, stopped,
49
+ # waiting_for_owner (a participant's turn waits on the owner: chi
50
+ # web's participant wait, through --remote), refused (a participant's
51
+ # queued turn the worker refused: revoked, expired, at their cap; no
52
+ # turn ran) or running
44
53
  def status(result)
54
+ return "refused" if refused?(result)
55
+
45
56
  case result.status
46
57
  when :done then "answered"
47
58
  when :waiting_for_answer then "question"
@@ -57,19 +68,33 @@ module Samagotchi
57
68
  when :error then "error"
58
69
  when :worker_gone then "worker_gone"
59
70
  when :stopped then "stopped"
71
+ when :waiting_for_owner then "waiting_for_owner"
60
72
  # ReplyWait's own :canceled is the caller giving up (its cancelled:),
61
73
  # and :timeout the deadline: the turn goes on either way.
62
74
  else "running"
63
75
  end
64
76
  end
65
77
 
78
+ # The reasons a worker refuses a participant's queued turn
79
+ # (Worker#participant_refusal), as its settled record's cancel_reason.
80
+ REFUSED_LINES = { "revoked" => ParticipantMessages::TOKEN_ENDED,
81
+ "cap_reached" => ParticipantMessages::CAP_REACHED }.freeze
82
+
83
+ # A participant's turn the worker refused before it ran: by its
84
+ # cancel_reason (chi web's participant wait sends no outcome).
85
+ def refused?(result)
86
+ result.status == :no_reply && REFUSED_LINES.key?(result.cancel_reason.to_s) &&
87
+ [nil, "canceled"].include?(result.outcome)
88
+ end
89
+
66
90
  # @return [Integer] 0 answered (or not continued: the Stop asked for
67
- # was carried out), 3 a question waits, 4 still running, 1 anything
91
+ # was carried out), 3 a question waits (or, for a participant, the
92
+ # owner: waiting_for_owner), 4 still running, 1 anything
68
93
  # else
69
94
  def exit_status(result)
70
95
  case status(result)
71
96
  when "answered", "not_continued" then CLI::Exit::OK
72
- when "question" then CLI::Exit::QUESTION
97
+ when "question", "waiting_for_owner" then CLI::Exit::QUESTION
73
98
  when "running" then CLI::Exit::RUNNING
74
99
  else CLI::Exit::FAILED
75
100
  end
@@ -108,6 +133,8 @@ module Samagotchi
108
133
  case status(result)
109
134
  when "failed" then { error_kind: result.error_kind, retryable: result.retryable, kept_steps: result.kept_steps }.compact
110
135
  when "canceled" then { cancel_reason: result.cancel_reason, stopped_by: result.stopped_by }.compact
136
+ # The refusal's code: revoked or cap_reached.
137
+ when "refused" then { cancel_reason: result.cancel_reason }
111
138
  else {}
112
139
  end
113
140
  end
@@ -304,8 +331,12 @@ module Samagotchi
304
331
  when :error then "the worker failed: #{result.text}; #{shows} shows what happened"
305
332
  when :worker_gone then "the worker is gone; #{shows} shows what happened"
306
333
  when :stopped then "the session was stopped (chi sessions stop)"
334
+ when :waiting_for_owner
335
+ turn = turn_id || result.turn_id
336
+ turn.to_s.empty? ? WAITING_FOR_OWNER : "#{WAITING_FOR_OWNER}: #{via.command("send --wait --turn #{turn} #{session_id}")}"
307
337
  else
308
- wait_again = via.command("send --wait --turn #{turn_id} #{session_id}") unless turn_id.to_s.empty?
338
+ turn = turn_id || result.turn_id
339
+ wait_again = via.command("send --wait --turn #{turn} #{session_id}") unless turn.to_s.empty?
309
340
  hint = wait_again || shows
310
341
  timeout ? "still running after #{format("%g", timeout)} s: #{hint}" : "still running: #{hint}"
311
342
  end
@@ -353,6 +384,9 @@ module Samagotchi
353
384
 
354
385
  def no_reply_line(result, session_id = nil, strategy: nil, via: ChiInvocation::HERE)
355
386
  return command_line(result) if result.origin == TurnCheckpoint::COMMAND_ORIGIN
387
+ if refused?(result)
388
+ return "the turn was refused (#{REFUSED_LINES.fetch(result.cancel_reason.to_s)}); no turn ran for it"
389
+ end
356
390
 
357
391
  case result.outcome
358
392
  when "failed" then failed_line(result)
@@ -0,0 +1,27 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Samagotchi
4
+ # The words a participant is refused with, one per condition, wherever
5
+ # it is met: chi web's routes, the Bridge, the worker, and the
6
+ # SessionAccess errors a chi --remote client raises for the same codes.
7
+ # No requires, so any file can use it.
8
+ module ParticipantMessages
9
+ # 401 token_revoked: the owner revoked the grant, or archived or deleted its session.
10
+ TOKEN_REVOKED = "this review link was revoked by the session's owner"
11
+ # 401 token_expired: the grant's time ran out.
12
+ TOKEN_EXPIRED = "this review link expired: ask the session's owner for a new one"
13
+ # Either of those, where only that the link ended is known: the
14
+ # worker's cancel_reason "revoked" (participants.json reads them
15
+ # removed or past expires_at), as their chi send --wait reports it.
16
+ TOKEN_ENDED = "this review link was revoked or expired"
17
+ # 403 not_permitted: a route, a command or a shell line only the owner may use.
18
+ NOT_PERMITTED = "a participant can't do that: only the session's owner can"
19
+ # 429 too_many_turns: their running turn and its queue are full.
20
+ TOO_MANY_TURNS = "this participant has too many turns waiting: wait for one to finish"
21
+ # 429 cap_reached: their grant spent its cap.
22
+ CAP_REACHED = "this participant's spending cap is reached: ask the session's owner to raise it"
23
+ # Their turn failed (a wait's error, a failed turn's no_reply): never
24
+ # the exception's words or the failure summary, which may name a path.
25
+ TURN_FAILED = "this turn failed: the session's owner can see why"
26
+ end
27
+ end
@@ -4,6 +4,7 @@ require "fileutils"
4
4
  require "json"
5
5
  require "time"
6
6
  require_relative "atomic_file"
7
+ require_relative "participant_messages"
7
8
  require_relative "archive_store"
8
9
  require_relative "session"
9
10
  require_relative "web/grants"
@@ -26,11 +27,16 @@ module Samagotchi
26
27
  module Participants
27
28
  FILE = "participants.json"
28
29
  LOG = "participants.jsonl"
30
+ # What a participant is told when they try what only the owner may do:
31
+ # a route (chi web's 403 not_permitted), a command or a shell line.
32
+ NOT_PERMITTED = ParticipantMessages::NOT_PERMITTED
29
33
 
30
34
  # One participant as the sidecar has them. +removed_at+ when the grant
31
35
  # was revoked (nil while it works, or once it simply expired:
32
- # +expires_at+ says when).
33
- Entry = Data.define(:id, :kind, :name, :role, :added_at, :expires_at, :removed_at) do
36
+ # +expires_at+ says when). +cap+: their spending cap in dollars (the
37
+ # worker's check before their queued turn starts), nil in a sidecar
38
+ # from before caps.
39
+ Entry = Data.define(:id, :kind, :name, :role, :added_at, :expires_at, :removed_at, :cap) do
34
40
  def self.from_h(hash) = new(**members.to_h { |key| [key, hash[key.to_s]] })
35
41
 
36
42
  # Still in the review at +now+.
@@ -65,11 +71,22 @@ module Samagotchi
65
71
 
66
72
  entries = grants.map do |grant|
67
73
  { "id" => grant.id, "kind" => grant.kind, "name" => grant.name, "role" => grant.role,
68
- "added_at" => grant.created_at, "expires_at" => grant.expires_at, "removed_at" => grant.revoked_at }
74
+ "added_at" => grant.created_at, "expires_at" => grant.expires_at, "removed_at" => grant.revoked_at,
75
+ "cap" => grant.spend_cap }
69
76
  end
70
77
  AtomicFile.write(File.join(dir, FILE), "#{JSON.pretty_generate({ "participants" => entries })}\n", perm: 0o600)
71
78
  end
72
79
 
80
+ # Web::Grants' on_write for a change to +session_ids+ (nil: the sessions
81
+ # of the grants it changed, a revoke's result): their sidecars rewritten
82
+ # from the grants just written, under the store's lock (two writers, chi
83
+ # web and chi share, can't finish out of order and lose a revoke here).
84
+ def sidecar_writer(state_dir, session_ids = nil)
85
+ lambda do |all, result|
86
+ (session_ids || result.map(&:session_id).uniq).each { |sid| write(sid, all.select { |grant| grant.session_id == sid }, state_dir: state_dir) }
87
+ end
88
+ end
89
+
73
90
  # One audit line: {"at", "event", …fields}. Nothing for a session whose
74
91
  # dir is gone (deleted, pruned).
75
92
  def log(session_id, event, state_dir: Session.default_state_dir, at: Time.now, **fields)
@@ -85,27 +102,42 @@ module Samagotchi
85
102
  # @return [Web::Grants::Issued]
86
103
  # @raise [Web::Grants::Invalid] an archived session, or bad values
87
104
  # @raise [ArgumentError] no such session
88
- def invite(grants, session_id:, name:, kind: "human", ttl: nil, state_dir: Session.default_state_dir)
105
+ def invite(grants, session_id:, name:, kind: "human", ttl: nil, cap: nil, state_dir: Session.default_state_dir)
89
106
  raise ArgumentError, "Session not found: #{session_id}" unless File.exist?(Session.session_file(session_id, state_dir: state_dir))
90
107
  if ArchiveStore.archived?(Session.session_dir(session_id, state_dir: state_dir))
91
108
  raise Web::Grants::Invalid, "session #{session_id[0, 8]} is archived: unarchive it to invite anyone"
92
109
  end
93
110
 
94
- issued = grants.issue(session_id: session_id, name: name, kind: kind, **{ ttl: ttl }.compact)
95
- write(session_id, grants.list(session_id: session_id), state_dir: state_dir)
111
+ issued = grants.issue(session_id: session_id, name: name, kind: kind, ttl: ttl, cap: cap,
112
+ on_write: sidecar_writer(state_dir, [session_id]))
96
113
  grant = issued.grant
97
114
  log(session_id, :issued, state_dir: state_dir, participant: grant.id, name: grant.name, kind: grant.kind,
98
- role: grant.role, expires_at: grant.expires_at)
115
+ role: grant.role, expires_at: grant.expires_at, cap: grant.spend_cap)
99
116
  issued
100
117
  end
101
118
 
119
+ # Sets participant +id+'s cap on +session_id+ (chi share cap): the
120
+ # grant, the sidecar (the worker's check) and the audit line.
121
+ # @return [Web::Grants::Grant, nil] nil when +id+ isn't an active grant there
122
+ # @raise [Web::Grants::Invalid] a cap out of range
123
+ def set_cap(grants, session_id:, id:, cap:, state_dir: Session.default_state_dir)
124
+ grant = grants.set_cap(id, cap, session_id: session_id, on_write: sidecar_writer(state_dir, [session_id]))
125
+ return nil unless grant
126
+
127
+ log(session_id, :cap, state_dir: state_dir, participant: grant.id, cap: grant.spend_cap)
128
+ grant
129
+ end
130
+
131
+ # The refusal for a cap change of +id+, no active participant of
132
+ # +session_id+.
133
+ def no_participant(id, session_id) = "no active participant #{id} in #{session_id.to_s[0, 8]} (chi share ls lists them)"
134
+
102
135
  # Revokes grants (Web::Grants#revoke's arguments) and brings each
103
136
  # affected session's sidecar and audit trail along.
104
137
  # @return [Array<Web::Grants::Grant>] the grants it revoked
105
138
  def revoke(grants, session_id: nil, id: nil, by: "owner", state_dir: Session.default_state_dir)
106
- revoked = grants.revoke(session_id: session_id, id: id, by: by)
139
+ revoked = grants.revoke(session_id: session_id, id: id, by: by, on_write: sidecar_writer(state_dir))
107
140
  revoked.group_by(&:session_id).each do |sid, ended|
108
- write(sid, grants.list(session_id: sid), state_dir: state_dir)
109
141
  ended.each { |grant| log(sid, :revoked, state_dir: state_dir, participant: grant.id, by: by) }
110
142
  end
111
143
  revoked
@@ -114,9 +146,14 @@ module Samagotchi
114
146
  # Ends the grants of sessions that were archived or deleted
115
147
  # (SessionManager): +by+ "archive" or "delete". Nothing is written for a
116
148
  # session nobody was invited to.
149
+ # A grants store that doesn't read (Web::Grants::Corrupt) doesn't stop
150
+ # the archive or delete: its links already find no grant, and the
151
+ # store itself says so (Log.warn) until it's fixed.
117
152
  def end_sessions(session_ids, by:, state_dir: Session.default_state_dir)
118
153
  grants = Web::Grants.new(Web::Grants.path(state_dir: state_dir))
119
154
  session_ids.each { |sid| revoke(grants, session_id: sid, by: by, state_dir: state_dir) }
155
+ rescue Web::Grants::Corrupt
156
+ nil
120
157
  end
121
158
  end
122
159
  end
@@ -0,0 +1,90 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Samagotchi
4
+ # Loaded only when a sidecar is read: it brings Web::Grants (and Rack).
5
+ autoload :Participants, File.expand_path("participants", __dir__)
6
+
7
+ # Who is in a session's review now, and who came or went since the last
8
+ # look: participants.json (Participants.read) read again when its mtime
9
+ # moves, each entry's expiry measured at every look. The worker asks
10
+ # #changes on its idle tick and announces :participants_changed; the
11
+ # Bridge's join snapshot asks #active (any thread). A session nobody was
12
+ # invited to has no sidecar: one stat per look. Joined means invited (an
13
+ # active grant the last look didn't have), left means revoked or expired:
14
+ # participants have no presence of their own yet. See
15
+ # docs/internals/participants.md (The owner's terminal).
16
+ class ParticipantsWatch
17
+ # Participants::FILE, without loading Participants for a stat.
18
+ FILE = "participants.json"
19
+
20
+ # What changed: the active participants now, the ones that joined, and
21
+ # the ones that left (each with +reason+ "revoked" or "expired").
22
+ Change = Data.define(:participants, :joined, :left) do
23
+ def to_event = { type: :participants_changed, participants: participants, joined: joined, left: left }
24
+ end
25
+
26
+ # @param session_id [#call] → the session's id (nil before it has one)
27
+ # @param state_dir [#call] → the sessions' state dir
28
+ # @param clock [#call] → Time
29
+ def initialize(session_id:, state_dir:, clock: -> { Time.now })
30
+ @session_id = session_id
31
+ @state_dir = state_dir
32
+ @clock = clock
33
+ @mutex = Mutex.new
34
+ @stamp = nil
35
+ @entries = []
36
+ @known = nil
37
+ end
38
+
39
+ # The participants in the review now: [{id:, name:, kind:}], [] for none.
40
+ # @return [Array<Hash>]
41
+ def active
42
+ @mutex.synchronize { active_rows(read_entries) }
43
+ end
44
+
45
+ # The change since the last call, nil when none. The first call only
46
+ # takes the state as it is (a worker's start announces nobody).
47
+ # @return [Change, nil]
48
+ def changes
49
+ @mutex.synchronize do
50
+ entries = read_entries
51
+ rows = active_rows(entries)
52
+ known = @known
53
+ @known = rows.to_h { |row| [row[:id], row] }
54
+ next nil if known.nil?
55
+
56
+ joined = rows.reject { |row| known.key?(row[:id]) }
57
+ left = known.values.reject { |row| @known.key?(row[:id]) }.map do |row|
58
+ entry = entries.find { |e| e.id == row[:id] }
59
+ row.merge(reason: entry&.removed_at ? "revoked" : "expired")
60
+ end
61
+ next nil if joined.empty? && left.empty?
62
+
63
+ Change.new(participants: rows, joined: joined, left: left)
64
+ end
65
+ end
66
+
67
+ private
68
+
69
+ def active_rows(entries)
70
+ now = @clock.call
71
+ entries.select { |entry| entry.active?(now) }.map { |entry| { id: entry.id, name: entry.name, kind: entry.kind } }
72
+ end
73
+
74
+ # The sidecar's entries, read again only when its mtime moved.
75
+ def read_entries
76
+ id = @session_id.call
77
+ return @entries = [] if id.to_s.empty?
78
+
79
+ file = File.join(Session.session_dir(id, state_dir: @state_dir.call), FILE)
80
+ stamp = [id, File.mtime(file)]
81
+ return @entries if stamp == @stamp
82
+
83
+ @stamp = stamp
84
+ @entries = Participants.read(id, state_dir: @state_dir.call)
85
+ rescue SystemCallError
86
+ @stamp = nil
87
+ @entries = []
88
+ end
89
+ end
90
+ end
@@ -41,7 +41,8 @@ module Samagotchi
41
41
  "ctx.use_toolkit" => "0.66.0", "ctx.toolkit" => "0.66.0", "ctx.declared_tools" => "0.66.0",
42
42
  "chi.tool_source" => "0.67.0", "chi.peer_source" => "0.67.0", "ctx.http" => "0.80.0",
43
43
  "ctx.cost" => "0.83.0", "ctx.sessions.children" => "0.34.0", "ctx.load_tools" => "0.99.0",
44
- "ctx.usage" => "0.100.0"
44
+ "ctx.usage" => "0.100.0", "ctx.sessions.stop" => "0.34.0", "ctx.turn_author" => "0.106.0",
45
+ "ctx.sessions.review" => "0.107.0"
45
46
  }.freeze
46
47
 
47
48
  # @param bundle [String]
@@ -61,7 +61,7 @@ module Samagotchi
61
61
  Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
62
62
  :ask_model, :model_name, :model_key, :state_dir, :scratch, :setup, :prompt_files,
63
63
  :steer, :stop_turn, :stop_generation, :frontend, :toolkit, :declared_tools, :use_toolkit, :load_tools,
64
- :cancel_controller, :cost, :usage, keyword_init: true)
64
+ :cancel_controller, :cost, :usage, :turn_author, keyword_init: true)
65
65
 
66
66
  # ctx.ask_model failed: the model couldn't be reached, timed out, or
67
67
  # sent nothing usable. The message says why, for the user.
@@ -175,6 +175,12 @@ module Samagotchi
175
175
  # with no session
176
176
  def usage = @host.usage&.call || SessionMetrics::Usage.zero
177
177
 
178
+ # @return [String, nil] who wrote the running turn when it isn't the
179
+ # session's owner: a participant's "p:<id>" (chi share); nil for the
180
+ # owner's turns and between turns. A handler runs with the owner's
181
+ # power whatever the author (docs/hooks.md).
182
+ def turn_author = @host.turn_author&.call
183
+
178
184
  # @return [String, nil] the name of the session's toolkit ("full" for
179
185
  # one from before toolkits; nil with no session)
180
186
  def toolkit = @host.toolkit&.call
@@ -7,6 +7,8 @@ require_relative "../bridge_client"
7
7
  require_relative "../bridge/turn_accumulator"
8
8
  require_relative "../tools/delegate"
9
9
  require_relative "../children_status"
10
+ require_relative "../review_start"
11
+ require_relative "../model_profile"
10
12
 
11
13
  module Samagotchi
12
14
  # Loaded on first use: this autoload keeps SessionManager and its ~80
@@ -60,6 +62,29 @@ module Samagotchi
60
62
  child.id
61
63
  end
62
64
 
65
+ # A review of this session (ReviewStart.fork, chi review --from): a new
66
+ # session in its folder, on its model and setup, seeded with its recap
67
+ # (never its transcript) and +seed+ (more context: the coordinator's
68
+ # handoff, say), idle, to share with participants (chi share). This
69
+ # session keeps running, unarchived. Not a child: it has no parent.
70
+ # The recap is the one saved (the worker is asked for a fresh one, not
71
+ # waited on unless +recap_wait+ seconds are given: this runs in this
72
+ # session's own worker).
73
+ # @param subjects [Array<String>] files under review, relative to its
74
+ # folder (ReviewStart.check_subjects)
75
+ # @return [String] the review session's id
76
+ # @raise [Error] no session yet, a scratch session, a subject refused
77
+ # (its one message), or it could not start
78
+ def review(subjects: [], seed: nil, recap_wait: 0)
79
+ source = @host.session_id.call or raise Error, "this session has no id yet"
80
+ raise Error, "a scratch session starts no other sessions: they would outlive it" if @host.scratch&.call
81
+
82
+ ReviewStart.fork(from: source, subjects: Array(subjects), seed: seed, state_dir: state_dir,
83
+ recap_wait: recap_wait).id
84
+ rescue ReviewStart::Refused, ModelProfile::MissingModel, ArgumentError => e
85
+ raise Error, e.message
86
+ end
87
+
63
88
  # Send +text+ to session +id+ as a user message (it runs as a turn;
64
89
  # a stopped session is woken). Waits up to 5 s for its worker, so call
65
90
  # it from an anytime command or your own thread, never a tool or hook
@@ -42,13 +42,21 @@ module Samagotchi
42
42
  line = IdleRecap::TranscriptFilter.build([message])
43
43
  next if line.strip.empty?
44
44
 
45
- "#{message["role"] == "user" ? "User" : "Assistant"}: #{line}"
45
+ "#{speaker(message)}: #{line}"
46
46
  end.join("\n\n")
47
47
  return text if text.length <= MAX_TRANSCRIPT_CHARS
48
48
 
49
49
  "[earlier conversation left out]\n\n#{text[-MAX_TRANSCRIPT_CHARS..]}"
50
50
  end
51
51
 
52
+ # Who a paragraph is: a participant's message is a Participant's (the
53
+ # filter's line names them), any other user message the User's.
54
+ def speaker(message)
55
+ return "Assistant" unless message["role"] == "user"
56
+
57
+ Steer.participant_message?(message) ? "Participant" : "User"
58
+ end
59
+
52
60
  # String keys, as TranscriptFilter reads a saved session.
53
61
  def stringified(messages)
54
62
  JSON.parse(JSON.generate(Array(messages)))
@@ -27,7 +27,7 @@ module Samagotchi
27
27
  in #{Paths.tilde(Remotes.path)} (0600); an existing NAME is replaced.
28
28
  ls [--format json] the remotes (never their tokens)
29
29
  rm NAME forget one
30
- Then: chi --remote NAME send|answer|note|context|sessions …, or CHI_REMOTE=NAME.
30
+ Then: chi --remote NAME send|answer|note|context|sessions|share|review …, or CHI_REMOTE=NAME.
31
31
  TEXT
32
32
 
33
33
  SUBCOMMANDS = %w[add ls rm].freeze
@@ -17,7 +17,8 @@ module Samagotchi
17
17
  # url: http://192.168.1.29:4567
18
18
  # token: …
19
19
  #
20
- # chi remote add / ls / rm write and read it (RemoteCommand).
20
+ # chi remote add / ls / rm write and read it (RemoteCommand); a write
21
+ # replaces it whole (AtomicFile) under remotes.yml.lock.
21
22
  module Remotes
22
23
  FILE = "remotes.yml"
23
24
  # A name as git takes a remote's, short: letters, digits, - and _.
@@ -27,7 +28,8 @@ module Samagotchi
27
28
  # path) and its access +token+ (nil for a loopback chi web, which needs
28
29
  # none). #inspect leaves the token out.
29
30
  Entry = Data.define(:name, :url, :token) do
30
- def host = URI(url).host
31
+ # The host as an address, an IPv6 one bare (::1, not [::1]).
32
+ def host = URI(url).hostname
31
33
 
32
34
  # How a failure names it: "remote studio (http://192.168.1.29:4567)".
33
35
  def label = "remote #{name} (#{url})"
@@ -80,17 +82,19 @@ module Samagotchi
80
82
 
81
83
  # Saves +entry+, replacing one of its name.
82
84
  def put(entry, path: self.path)
83
- write(all(path: path).reject { |other| other.name == entry.name } + [entry], path)
85
+ locked(path) { write(all(path: path).reject { |other| other.name == entry.name } + [entry], path) }
84
86
  end
85
87
 
86
88
  # @return [Boolean] whether there was one
87
89
  def remove(name, path: self.path)
88
- entries = all(path: path)
89
- kept = entries.reject { |entry| entry.name == name }
90
- return false if kept.size == entries.size
90
+ locked(path) do
91
+ entries = all(path: path)
92
+ kept = entries.reject { |entry| entry.name == name }
93
+ next false if kept.size == entries.size
91
94
 
92
- write(kept, path)
93
- true
95
+ write(kept, path)
96
+ true
97
+ end
94
98
  end
95
99
 
96
100
  # @raise [Invalid] unless +name+ is one
@@ -120,6 +124,17 @@ module Samagotchi
120
124
  raise Invalid, "give chi web's address, http://HOST:PORT, not #{text}"
121
125
  end
122
126
 
127
+ # The read-modify-write of +path+ under <path>.lock (0600), so two
128
+ # chi remote add / rm at once never drop each other's entry.
129
+ def locked(path)
130
+ FileUtils.mkdir_p(File.dirname(path))
131
+ File.open("#{path}.lock", File::RDWR | File::CREAT, 0o600) do |lock|
132
+ lock.flock(File::LOCK_EX)
133
+ yield
134
+ end
135
+ end
136
+ private_class_method :locked
137
+
123
138
  def write(entries, path)
124
139
  FileUtils.mkdir_p(File.dirname(path))
125
140
  remotes = entries.sort_by(&:name).to_h { |entry| [entry.name, { "url" => entry.url, "token" => entry.token }.compact] }
@@ -3,6 +3,8 @@
3
3
  require_relative "../session"
4
4
  require_relative "../session_inbox"
5
5
  require_relative "../turn_checkpoint"
6
+ require_relative "../continue_offer"
7
+ require_relative "../steer"
6
8
 
7
9
  module Samagotchi
8
10
  module ReplyWait
@@ -70,7 +72,7 @@ module Samagotchi
70
72
 
71
73
  note_own_running(session)
72
74
  follow_merge(session)
73
- reply(session) || settled_turn(session) || status_end(session) || question(session) || canceled ||
75
+ reply(session) || settled_turn(session) || status_end(session) || question(session) || held(session) || canceled ||
74
76
  ended_before_reply(session) || ended_before_turn(session) || turn_end(session) || owner_gone(session) ||
75
77
  timed_out
76
78
  end
@@ -78,8 +80,9 @@ module Samagotchi
78
80
  def look_at_input
79
81
  return unless @turn && !@claimed
80
82
 
81
- waiting = SessionInbox.waiting_input(@session_dir, @turn)
82
- @own_turn_input ||= waiting == :turn_end
83
+ waiting = SessionInbox.waiting_input_data(@session_dir, @turn)
84
+ @own_turn_input ||= !waiting.nil? && SessionInbox.turn_end_data?(waiting)
85
+ @participant_input ||= !waiting.nil? && Steer.participant_author?(waiting["author"])
83
86
  @claimed = waiting.nil?
84
87
  end
85
88
 
@@ -161,6 +164,18 @@ module Samagotchi
161
164
  Result.new(status: :waiting_for_answer, question: pending, session: session)
162
165
  end
163
166
 
167
+ # A participant's turn its worker holds while the owner's Continue
168
+ # offer stands (Worker#run_input_files): it waits for the owner's
169
+ # answer to that question, whenever it was asked (the baseline's
170
+ # question too). An owner's turn is never held: it drops the offer.
171
+ def held(session)
172
+ pending = session.pending_question
173
+ return nil unless @participant_input && !@claimed && pending&.kind.to_s == ContinueOffer::KIND &&
174
+ session.waiting_question(live: SessionManager.worker_live?(@id, state_dir: @state_dir))
175
+
176
+ Result.new(status: :waiting_for_answer, question: pending, session: session)
177
+ end
178
+
164
179
  def canceled = @cancelled.call ? Result.new(status: :canceled) : nil
165
180
 
166
181
  # The turn that ended before this wait (ended_before: chi send --wait