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
@@ -11,6 +11,8 @@ require_relative "analytics_file"
11
11
  require_relative "atomic_file"
12
12
  require_relative "config"
13
13
  require_relative "delivery"
14
+ require_relative "steer"
15
+ require_relative "participant_messages"
14
16
 
15
17
  require_relative "session"
16
18
  require_relative "session_inbox"
@@ -155,6 +157,8 @@ module Samagotchi
155
157
  # @param note [String, nil] a context note the session starts with,
156
158
  # from +note_source+: queued before its worker spawns, so its first
157
159
  # turn sees it
160
+ # @param review [SessionReview, nil] a review session's (ReviewStart; a
161
+ # continue keeps its previous link's)
158
162
  # @param before_spawn [#call, nil] (session) runs once the session and
159
163
  # its note are saved, before its worker spawns
160
164
  # @return [Session] with #seed_images_dropped: refs whose file was gone,
@@ -162,7 +166,7 @@ module Samagotchi
162
166
  def self.spawn_session(prompt:, mode: "assist", working_directory: nil, model_name: nil, state_dir: nil,
163
167
  memories: [], muted_memories: [], parent_id: nil, messages: [], images_from: nil,
164
168
  preview: nil, title: nil, delegate: false, setup: SessionSetup.new, continues: nil, note: nil,
165
- note_source: "chi", before_spawn: nil)
169
+ note_source: "chi", before_spawn: nil, review: nil)
166
170
  sd = state_dir || Session.default_state_dir
167
171
  # The resolved ref is stored (a resumed session keeps its model when an
168
172
  # alias is retargeted), with the name as typed beside it. A wrong host
@@ -184,7 +188,8 @@ module Samagotchi
184
188
  messages: messages,
185
189
  delegate: delegate,
186
190
  setup: setup,
187
- continues: continues
191
+ continues: continues,
192
+ review: review
188
193
  )
189
194
  session.toolkit = Toolkit.configured(delegate: delegate) if session.toolkit.nil?
190
195
  session.model_warning = model_warning
@@ -1216,6 +1221,9 @@ module Samagotchi
1216
1221
  # owner (Web::Principal#author: chi web stamps it, never the body);
1217
1222
  # to the Bridge or the file only when given, so an owner's turn is
1218
1223
  # sent and saved as before
1224
+ # @param pending_limit [Integer, nil] with +author+: how many of their
1225
+ # turns may be running or waiting (the Bridge counts them; with no
1226
+ # worker, their waiting files): :refused 429 too_many_turns past it
1219
1227
  # @param manager [#resume_session, #write_turn_input] this class, or a
1220
1228
  # stand-in (the web's specs); #session_owner is optional
1221
1229
  # @param bridge [#call, nil] returns the BridgeClient or nil; defaults to
@@ -1229,7 +1237,7 @@ module Samagotchi
1229
1237
  # @raise [OwnedByTUI] a chi REPL owns the session
1230
1238
  # @raise [ArgumentError] no such session
1231
1239
  def self.deliver_turn(session_id, prompt:, client_id: nil, images: [], delivery: nil, no_interrupt: false,
1232
- author: nil, state_dir: nil, manager: self, bridge: nil)
1240
+ author: nil, pending_limit: nil, state_dir: nil, manager: self, bridge: nil)
1233
1241
  session_dir = Session.session_dir(session_id, state_dir: state_dir || Session.default_state_dir)
1234
1242
  bridge ||= -> { BridgeClient.wait_for(session_id, session_dir: session_dir, timeout: TURN_BRIDGE_WAIT) }
1235
1243
  manager.resume_session(session_id, state_dir: state_dir)
@@ -1237,6 +1245,8 @@ module Samagotchi
1237
1245
  # A worker from before queueing (no "delivery" feature) ignores the
1238
1246
  # field or refuses it; either way a file would steer the running turn.
1239
1247
  return queue_unavailable if Delivery.queue?(delivery) && !worker_queues?(session_dir)
1248
+ # A participant's turn only to a worker with the review boundary.
1249
+ return review_unavailable if Steer.participant_author?(author) && !worker_has?(session_dir, Delivery::REVIEW_FEATURE)
1240
1250
 
1241
1251
  begin
1242
1252
  options = { prompt: prompt, client_id: client_id }
@@ -1245,6 +1255,7 @@ module Samagotchi
1245
1255
  options[:delivery] = delivery unless Delivery.next_step?(delivery)
1246
1256
  options[:no_interrupt] = true if no_interrupt
1247
1257
  options[:author] = author if author
1258
+ options[:pending_limit] = pending_limit if author && pending_limit
1248
1259
  reply = client.post_turn(**options)
1249
1260
  ack = reply.json
1250
1261
  return DeliverResult.new(status: :accepted, via: :bridge, ack: ack) if reply.status == 202 && ack.is_a?(Hash)
@@ -1267,13 +1278,32 @@ module Samagotchi
1267
1278
  nil # the worker closed its Bridge on the way out: queue the file
1268
1279
  end
1269
1280
  end
1281
+ # A participant's file only for a worker started after it: a worker
1282
+ # still holding the session with its Bridge gone (exiting) may be an
1283
+ # older one, which would run it without the review boundary.
1284
+ # (A chi REPL holding it is refused as for anyone, below.)
1285
+ if Steer.participant_author?(author) && (holder = delivery_owner(manager, session_id, state_dir)) && !holder.tui?
1286
+ return DeliverResult.new(status: :timeout, via: :file,
1287
+ ack: { "error" => "worker_timeout",
1288
+ "detail" => "the session's worker is exiting, so the message was not sent; send it again" })
1289
+ end
1270
1290
  enqueued_id = SecureRandom.uuid
1271
1291
  input = { prompt: prompt, client_id: client_id, enqueued_id: enqueued_id, state_dir: state_dir }
1272
1292
  input[:images] = images unless images.empty?
1273
1293
  input[:delivery] = delivery unless Delivery.next_step?(delivery)
1274
1294
  input[:no_interrupt] = true if no_interrupt
1275
1295
  input[:author] = author if author
1276
- path = manager.write_turn_input(session_id, **input)
1296
+ path = participant_queue_lock(session_dir, author && pending_limit) do
1297
+ # No worker: the participant's waiting files are all their turns,
1298
+ # counted and written under one lock (the Bridge counts under its).
1299
+ next :too_many if author && pending_limit && pending_files(session_dir, author) >= pending_limit
1300
+
1301
+ manager.write_turn_input(session_id, **input)
1302
+ end
1303
+ if path == :too_many
1304
+ return DeliverResult.new(status: :refused, code: 429,
1305
+ ack: { "error" => "too_many_turns", "detail" => ParticipantMessages::TOO_MANY_TURNS })
1306
+ end
1277
1307
  return DeliverResult.new(status: :failed) unless path
1278
1308
 
1279
1309
  owner = delivery_owner(manager, session_id, state_dir)
@@ -1294,15 +1324,47 @@ module Samagotchi
1294
1324
  # Whether the session's live worker runs delivery: queue (its sidecar
1295
1325
  # names the feature). No sidecar to read (the client came from a stand-in,
1296
1326
  # or it went between the wait and here): true, the post finds out.
1297
- private_class_method def self.worker_queues?(session_dir)
1327
+ private_class_method def self.worker_queues?(session_dir) = worker_has?(session_dir, Delivery::QUEUE_FEATURE)
1328
+
1329
+ # Whether the session's live worker names +feature+ in its sidecar; no
1330
+ # sidecar to read: true, as for #worker_queues?.
1331
+ private_class_method def self.worker_has?(session_dir, feature)
1298
1332
  sidecar = WorkerSidecar.read(session_dir)
1299
- sidecar.nil? || sidecar.features.include?(Delivery::QUEUE_FEATURE)
1333
+ sidecar.nil? || sidecar.features.include?(feature)
1334
+ end
1335
+
1336
+ # The unclaimed input files +author+ wrote.
1337
+ PARTICIPANT_QUEUE_LOCK = "participants.lock"
1338
+
1339
+ # The block under the session's participant queue lock (a file lock:
1340
+ # chi web's threads, and another chi web), when +locked+; else as is.
1341
+ private_class_method def self.participant_queue_lock(session_dir, locked)
1342
+ return yield unless locked
1343
+
1344
+ FileUtils.mkdir_p(session_dir)
1345
+ File.open(File.join(session_dir, PARTICIPANT_QUEUE_LOCK), File::RDWR | File::CREAT, 0o600) do |lock|
1346
+ lock.flock(File::LOCK_EX)
1347
+ yield
1348
+ end
1349
+ end
1350
+
1351
+ private_class_method def self.pending_files(session_dir, author)
1352
+ SessionInbox.find_new_input_files(session_dir).count do |file|
1353
+ data = JSON.parse(File.read(file))
1354
+ data.is_a?(Hash) && data["author"] == author
1355
+ rescue JSON::ParserError, SystemCallError
1356
+ false
1357
+ end
1300
1358
  end
1301
1359
 
1302
1360
  private_class_method def self.queue_unavailable
1303
1361
  DeliverResult.new(status: :refused, code: 409, ack: Delivery::QUEUE_UNAVAILABLE)
1304
1362
  end
1305
1363
 
1364
+ private_class_method def self.review_unavailable
1365
+ DeliverResult.new(status: :refused, code: 409, ack: Delivery::REVIEW_UNAVAILABLE)
1366
+ end
1367
+
1306
1368
  private_class_method def self.turn_timeout
1307
1369
  DeliverResult.new(status: :timeout, via: :bridge,
1308
1370
  ack: { "error" => "worker_timeout",
@@ -12,12 +12,16 @@ module Samagotchi
12
12
  # +cost_sum+ is nil until a request reports a cost (a reported 0
13
13
  # included), +cost_estimate_sum+ 0 until one is estimated from a price
14
14
  # (ModelPrice.estimate, the turns' rule). +by_kind+ is a frozen Hash
15
- # kind => {requests:, cost_sum:, cost_estimate_sum:} in first-seen order.
15
+ # kind => {requests:, cost_sum:, cost_estimate_sum:} in first-seen order;
16
+ # +by_author+ the same rows by the participant who caused them ("p:<id>":
17
+ # their turn's ctx.ask_model, the recap after it), the owner's not kept.
16
18
  class SideTotals < Data.define(:requests, :prompt_sum, :completion_sum, :cached_sum, :cache_write_sum,
17
- :reasoning_sum, :cost_sum, :cost_estimate_sum, :by_kind)
19
+ :reasoning_sum, :cost_sum, :cost_estimate_sum, :by_kind, :by_author)
18
20
  # The counts summed as they are (the costs and by_kind apart).
19
21
  COUNTS = %i[requests prompt_sum completion_sum cached_sum cache_write_sum reasoning_sum].freeze
20
22
 
23
+ def initialize(by_author: {}.freeze, **) = super
24
+
21
25
  def self.zero
22
26
  new(**COUNTS.to_h { |key| [key, 0] }, cost_sum: nil, cost_estimate_sum: 0, by_kind: {}.freeze)
23
27
  end
@@ -35,7 +39,7 @@ module Samagotchi
35
39
  **COUNTS.to_h { |key| [key, count(hash[key.to_s])] },
36
40
  cost_sum: cost(hash["cost_sum"]),
37
41
  cost_estimate_sum: number(hash["cost_estimate_sum"]),
38
- by_kind: saved_kinds(hash["by_kind"])
42
+ by_kind: saved_kinds(hash["by_kind"]), by_author: saved_kinds(hash["by_author"])
39
43
  )
40
44
  end
41
45
 
@@ -59,13 +63,14 @@ module Samagotchi
59
63
  one = { requests: 1, cost_sum: usage.cost&.to_f, cost_estimate_sum: estimate || 0 }
60
64
  kind = usage.kind.to_s
61
65
  rows = by_kind.merge(kind => sum_row(by_kind[kind], one))
66
+ authors = usage.author ? by_author.merge(usage.author => sum_row(by_author[usage.author], one)).freeze : by_author
62
67
  with(requests: requests + 1, prompt_sum: prompt_sum + usage.prompt_tokens.to_i,
63
68
  completion_sum: completion_sum + usage.completion_tokens.to_i,
64
69
  cached_sum: cached_sum + usage.cached_tokens.to_i,
65
70
  cache_write_sum: cache_write_sum + usage.cache_write_tokens.to_i,
66
71
  reasoning_sum: reasoning_sum + usage.reasoning_tokens.to_i,
67
72
  cost_sum: add_cost(cost_sum, one[:cost_sum]),
68
- cost_estimate_sum: cost_estimate_sum + one[:cost_estimate_sum], by_kind: rows.freeze)
73
+ cost_estimate_sum: cost_estimate_sum + one[:cost_estimate_sum], by_kind: rows.freeze, by_author: authors)
69
74
  end
70
75
 
71
76
  # These totals with +other+'s added (a loaded block and the requests
@@ -74,18 +79,27 @@ module Samagotchi
74
79
  # @return [SideTotals]
75
80
  def merge(other)
76
81
  rows = other.by_kind.each_with_object(by_kind.dup) { |(kind, row), all| all[kind] = sum_row(all[kind], row) }
82
+ authors = other.by_author.each_with_object(by_author.dup) { |(who, row), all| all[who] = sum_row(all[who], row) }
77
83
  with(**COUNTS.to_h { |key| [key, public_send(key) + other.public_send(key)] },
78
84
  cost_sum: add_cost(cost_sum, other.cost_sum),
79
- cost_estimate_sum: cost_estimate_sum + other.cost_estimate_sum, by_kind: rows.freeze)
85
+ cost_estimate_sum: cost_estimate_sum + other.cost_estimate_sum, by_kind: rows.freeze, by_author: authors.freeze)
80
86
  end
81
87
 
82
88
  def empty? = requests.zero?
83
89
 
84
- # The snapshot's side block (symbol keys; by_kind keyed by kind).
90
+ # The snapshot's side block (symbol keys; by_kind keyed by kind;
91
+ # by_author only when a participant caused any).
85
92
  # @return [Hash]
86
93
  def to_h
87
94
  counts = COUNTS.to_h { |key| [key, public_send(key)] }
88
- counts.merge(cost_sum: cost_sum, cost_estimate_sum: cost_estimate_sum, by_kind: by_kind.transform_values(&:dup))
95
+ block = counts.merge(cost_sum: cost_sum, cost_estimate_sum: cost_estimate_sum, by_kind: by_kind.transform_values(&:dup))
96
+ by_author.empty? ? block : block.merge(by_author: by_author.transform_values(&:dup))
97
+ end
98
+
99
+ # The dollars +author+'s side requests cost (reported and estimated).
100
+ def spent_by(author)
101
+ row = by_author[author] or return 0.0
102
+ row[:cost_sum].to_f + row[:cost_estimate_sum].to_f
89
103
  end
90
104
 
91
105
  def self.count(value) = value.is_a?(Numeric) ? value.to_i : 0
@@ -6,6 +6,7 @@ require "time"
6
6
  require "fileutils"
7
7
  require "securerandom"
8
8
  require_relative "analytics_file"
9
+ require_relative "client_id"
9
10
  require_relative "atomic_file"
10
11
  require_relative "log"
11
12
  require_relative "token_usage"
@@ -178,6 +179,10 @@ module Samagotchi
178
179
  # Who wrote the turn when it wasn't the owner (:turn_started's
179
180
  # origin author, "p:<id>"); its record carries it, the owner's none.
180
181
  :author,
182
+ # A turn no person sent (its origin's client isn't a human's,
183
+ # ClientId.human?: a task's or a context's wake, a plugin's send);
184
+ # its record carries it (a participant's page hides its prompt).
185
+ :automatic,
181
186
  :id,
182
187
  :started_at,
183
188
  :started_monotonic,
@@ -371,6 +376,65 @@ module Samagotchi
371
376
  # side block, apart from the turns' totals. Safe from any thread.
372
377
  # @param usage [SideUsage]
373
378
  # @return [Hash] the side block now (SideTotals#to_h)
379
+ # What a finished turn's record cost: reported and estimated dollars.
380
+ def self.record_cost(record) = record[:cost].to_f + record[:cost_estimate].to_f
381
+
382
+ # What +author+ ("p:<id>") has cost the session from its saved
383
+ # analytics.json: their turns' records and the side requests they
384
+ # caused. 0.0 without a file. chi web's cap check (a running turn's
385
+ # spend is saved at its end).
386
+ # @return [Float]
387
+ def self.saved_spend(session_dir, author)
388
+ saved_by_author(session_dir).dig(author, :cost) || 0.0
389
+ end
390
+
391
+ # Every participant's turns and cost from the saved analytics.json
392
+ # (#saved_spend's reading): author => {turns:, cost:}; {} without a
393
+ # file. The owner's turns (no author) aren't counted. The web's
394
+ # participants panel.
395
+ # @return [Hash{String => Hash}]
396
+ def self.saved_by_author(session_dir)
397
+ data = AnalyticsFile.read(session_dir) or return {}
398
+ rows = Hash.new { |hash, author| hash[author] = { turns: 0, cost: 0.0 } }
399
+ Array(data["turn_records"]).each do |record|
400
+ next unless record.is_a?(Hash) && record["author"].is_a?(String)
401
+
402
+ row = rows[record["author"]]
403
+ row[:turns] += 1
404
+ row[:cost] += record_cost(record.transform_keys(&:to_sym))
405
+ end
406
+ side = SideTotals.from_saved(data["side"])
407
+ side.by_author.each_key { |author| rows[author][:cost] += side.spent_by(author) }
408
+ rows.to_h
409
+ rescue TypeError
410
+ {}
411
+ end
412
+
413
+ # What +author+ has cost so far: their finished turns, their running
414
+ # one's finished generations, and the side requests they caused.
415
+ # @return [Float]
416
+ def spend(author)
417
+ @mutex.synchronize { spend_rows[author]&.dig(:cost) || 0.0 }
418
+ end
419
+
420
+ # Caller holds the mutex. author => {turns:, cost:, side_cost:}, the
421
+ # running turn and the side requests in; {} for a session no
422
+ # participant spent in.
423
+ def spend_rows
424
+ rows = @author_turns.transform_values(&:dup)
425
+ if (turn = @turn) && turn.author
426
+ row = rows[turn.author] ||= { turns: 0, cost: 0.0 }
427
+ row[:cost] += turn.cost_sum.to_f + turn.cost_estimate_sum.to_f
428
+ end
429
+ @side.by_author.each_key do |author|
430
+ side = @side.spent_by(author)
431
+ row = rows[author] ||= { turns: 0, cost: 0.0 }
432
+ row[:cost] += side
433
+ row[:side_cost] = side
434
+ end
435
+ rows
436
+ end
437
+
374
438
  def add_side(usage)
375
439
  @mutex.synchronize do
376
440
  @side = @side.add(usage)
@@ -591,6 +655,9 @@ module Samagotchi
591
655
  # The side requests (recap, ctx.ask_model), apart from +tokens+;
592
656
  # only when there were any.
593
657
  **(@side.empty? ? {} : { side: @side.to_h }),
658
+ # What each participant's turns and side requests cost; only when
659
+ # one spent any.
660
+ **((spend = spend_rows).empty? ? {} : { spend_by_author: spend }),
594
661
  tool_errors: @tool_tallies[:errors],
595
662
  iterations_total: totals.iterations,
596
663
  gen_latency_ms: totals.gen_ms.round,
@@ -700,6 +767,7 @@ module Samagotchi
700
767
  continue: event[:continue] ? true : false,
701
768
  resumed: event[:resumed] ? true : false,
702
769
  author: Steer.sender_author(event[:origin].is_a?(Hash) ? event[:origin][:author] : nil),
770
+ automatic: automatic_origin?(event[:origin]),
703
771
  id: event[:turn_id] || SecureRandom.uuid,
704
772
  started_at: now.iso8601(3),
705
773
  started_monotonic: monotonic_time,
@@ -741,6 +809,7 @@ module Samagotchi
741
809
  record[:continue] = @turn.continue
742
810
  record[:resumed] = @turn.resumed
743
811
  record[:author] = @turn.author if @turn.author
812
+ record[:automatic] = true if @turn.automatic
744
813
  record.merge!(turn_token_fields(@turn))
745
814
  @turn_records << record
746
815
  count_turn(record)
@@ -749,6 +818,13 @@ module Samagotchi
749
818
  end
750
819
  end
751
820
 
821
+ # Whether a turn's +origin+ names a client that is no person's: false
822
+ # without one (an in-process turn is the owner's).
823
+ def automatic_origin?(origin)
824
+ client_id = origin.is_a?(Hash) ? origin[:client_id] : nil
825
+ !client_id.nil? && !ClientId.human?(client_id)
826
+ end
827
+
752
828
  # The running turn's record so far, as end_turn would make it for a
753
829
  # turn a worker died in (#persist's running_turn). Its open generation
754
830
  # (none at an iteration boundary) and running tool calls are left out.
@@ -757,7 +833,7 @@ module Samagotchi
757
833
  {
758
834
  id: @turn.id, status: "canceled", started_at: @turn.started_at, completed_at: now.iso8601(3),
759
835
  duration_ms: elapsed_ms(@turn.started_monotonic), cancellation_reason: "worker_stopped",
760
- continue: @turn.continue, resumed: @turn.resumed, **{ author: @turn.author }.compact
836
+ continue: @turn.continue, resumed: @turn.resumed, **{ author: @turn.author, automatic: @turn.automatic || nil }.compact
761
837
  }.merge(turn_token_fields(@turn))
762
838
  end
763
839
 
@@ -1237,6 +1313,9 @@ module Samagotchi
1237
1313
  def reset_totals
1238
1314
  @totals = Totals.zero
1239
1315
  @segments = []
1316
+ # A participant's finished turns: author => {turns:, cost:} (dollars,
1317
+ # reported and estimated), the owner's not kept.
1318
+ @author_turns = {}
1240
1319
  @last_model_ref = nil
1241
1320
  # ms: the finished calls' time by tool (#usage's active_ms).
1242
1321
  @tool_tallies = { by_tool: {}, aliased: {}, errors: 0, ms: {} }
@@ -1244,6 +1323,7 @@ module Samagotchi
1244
1323
 
1245
1324
  def count_turn(record)
1246
1325
  @totals = @totals.add(record)
1326
+ count_author(record)
1247
1327
  if ModelSegment.splits?(@segments.last, record)
1248
1328
  @segments << ModelSegment.open(record)
1249
1329
  else
@@ -1254,6 +1334,13 @@ module Samagotchi
1254
1334
  @last_model_ref = record[:model_ref].to_s unless record[:model_ref].to_s.empty?
1255
1335
  end
1256
1336
 
1337
+ def count_author(record)
1338
+ author = Steer.sender_author(record[:author]) or return
1339
+
1340
+ row = @author_turns[author] || { turns: 0, cost: 0.0 }
1341
+ @author_turns[author] = { turns: row[:turns] + 1, cost: row[:cost] + SessionMetrics.record_cost(record) }
1342
+ end
1343
+
1257
1344
  def count_tool(record)
1258
1345
  @tool_tallies[:errors] += 1 if record[:status] == "error"
1259
1346
  tally_into(@tool_tallies[:by_tool], [record])
@@ -0,0 +1,28 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Samagotchi
4
+ # A review session's own field (chi review, the web's Start review): the
5
+ # files under review, project-relative (the session's work tree top),
6
+ # and, for a review fork (chi review --from), the session it started from.
7
+ # A session without one isn't a review session; its file has no "review"
8
+ # key at all (Session::OPTIONAL_FIELDS), so other session files stay as
9
+ # they were. Kept by continues; never by forks or delegate children.
10
+ # See docs/sessions.md (Review sessions).
11
+ SessionReview = Data.define(:subjects, :from) do
12
+ def initialize(subjects: [], from: nil)
13
+ super(subjects: Array(subjects).map(&:to_s).reject(&:empty?).uniq.freeze, from: from&.to_s)
14
+ end
15
+
16
+ # A SessionReview from the session file's form ({"subjects" => […],
17
+ # "from" => id}), a SessionReview, or nil (nil for nil or a non-hash).
18
+ def self.of(value)
19
+ case value
20
+ when SessionReview then value
21
+ when Hash then new(subjects: value["subjects"] || value[:subjects], from: value["from"] || value[:from])
22
+ end
23
+ end
24
+
25
+ # The session file's form: "from" only when there is one.
26
+ def to_file = { "subjects" => subjects, "from" => from }.compact
27
+ end
28
+ end
@@ -22,46 +22,60 @@ module Samagotchi
22
22
  include CLI::Command
23
23
 
24
24
  USAGE = <<~TEXT
25
- Usage: chi share ID --name NAME [--agent] [--expires 3d]
25
+ Usage: chi share ID --name NAME [--agent] [--expires 3d] [--cap 2]
26
26
  chi share ls [ID] [--format text|json]
27
+ chi share cap ID PARTICIPANT DOLLARS
27
28
  chi share revoke ID [PARTICIPANT] | --all
28
29
  ID --name NAME invite NAME to review session ID: prints the link they open (chi web on
29
30
  the LAN, web.host: lan) and its QR code at a terminal. The link is shown
30
31
  once; chi keeps only a digest of its token.
31
32
  --agent the participant is an agent (the same link, used as a Bearer token)
32
- --expires N Nh or Nd, 1h to 30d (default 7d)
33
+ --expires N Nh or Nd, 1h to 30d (default 7d, web.participants.expires)
34
+ --cap DOLLARS what their turns may cost you, $0 to $1000 (default $2, web.participants.cap)
33
35
  ls [ID] the participants of ID, or of every session (never a token)
36
+ cap ID P D set participant P's cap to D dollars, from their next turn
34
37
  revoke ID [P] end participant P's link, or every link to ID; --all every session's
35
- Archiving or deleting a session revokes its links. A participant sees the session's title
36
- and status; comments come in a later chi.
38
+ Archiving or deleting a session revokes its links. A participant's comments run as
39
+ review turns: you pay for them, and they may only read.
37
40
  TEXT
38
41
 
39
- SUBCOMMANDS = %w[ls revoke].freeze
42
+ SUBCOMMANDS = %w[ls cap revoke].freeze
43
+
44
+ # What the run changed, for the attached TUI's /share and /participants
45
+ # revoke (whose worker announces the same change a few seconds later):
46
+ # [[:joined, participant id]] for an invite, [[:left, id], …] for a
47
+ # revoke; [] otherwise.
48
+ attr_reader :changes
40
49
 
41
50
  # The invite's flags (chi share ID …), and ls's and revoke's.
42
51
  FLAGS = CLI::Flags.new(help: HELP_WORDS) do |f|
43
52
  f.value "--name"
44
53
  f.switch "--agent"
45
54
  f.value "--expires"
55
+ f.value "--cap"
46
56
  end
47
57
  SUB_FLAGS = {
48
58
  "ls" => CLI::Flags.new(help: HELP_WORDS) { |f| f.value "--format" },
59
+ "cap" => CLI::Flags.new(help: HELP_WORDS) { |_f| nil },
49
60
  "revoke" => CLI::Flags.new(help: HELP_WORDS) { |f| f.switch "--all" }
50
61
  }.freeze
51
62
 
52
- EXPIRES_RE = /\A(\d+)([hd])\z/
53
63
  TIME_FORMAT = "%m-%d %H:%M"
54
64
 
55
65
  # @param access [SessionAccess::Local, SessionAccess::Remote, nil]
56
66
  # where the sessions are; default this machine's, in +state_dir+
57
67
  # @param tty [Boolean, nil] print the QR code (default: stdout is a TTY)
58
- def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, state_dir: nil, access: nil, tty: nil)
68
+ # @param name [String, nil] what its error lines are led by, when not
69
+ # "chi share …" (the attached TUI's /share and /participants)
70
+ def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, state_dir: nil, access: nil, tty: nil, name: nil)
59
71
  @argv = argv.dup
60
72
  @stdin = stdin
61
73
  @stdout = stdout
62
74
  @stderr = stderr
63
75
  @access = access || SessionAccess::Local.new(state_dir: state_dir)
64
76
  @tty = tty.nil? ? @stdout.respond_to?(:tty?) && @stdout.tty? : tty
77
+ @name = name
78
+ @changes = []
65
79
  end
66
80
 
67
81
  # @return [Integer] exit status: 0 done, 1 refused or failed, 2 usage
@@ -79,6 +93,9 @@ module Samagotchi
79
93
  send(:"run_#{@sub || "invite"}", parsed.options, parsed.args)
80
94
  rescue SessionAccess::BadRequest => e
81
95
  usage_error(e.message)
96
+ rescue Web::Grants::Corrupt => e
97
+ error_line("#{command_name}: #{e.message}")
98
+ CLI::Exit::FAILED
82
99
  rescue ArgumentError => e
83
100
  error_line("#{command_name}: #{e.is_a?(Session::AmbiguousId) ? e.message : e.message.sub(/\ASession not found: /, "no session ")}")
84
101
  CLI::Exit::FAILED
@@ -86,19 +103,23 @@ module Samagotchi
86
103
 
87
104
  private
88
105
 
89
- def command_name = @sub ? "chi share #{@sub}" : "chi share"
106
+ def command_name = @name || (@sub ? "chi share #{@sub}" : "chi share")
90
107
  def usage_on_error = nil
91
108
 
92
109
  def run_invite(options, args)
93
110
  return usage_error("give one session ID") unless args.size == 1
94
111
  return usage_error("--name NAME: who the link is for") if options[:name].to_s.strip.empty?
95
112
 
96
- ttl = expires(options[:expires])
113
+ ttl = Web::Grants.parse_ttl(options[:expires])
97
114
  return usage_error("--expires takes Nh or Nd, 1h to 30d (e.g. 3d)") if ttl == false
98
115
 
116
+ cap = options[:cap] && dollars(options[:cap])
117
+ return usage_error(CAP_USAGE) if cap == false
118
+
99
119
  id = @access.resolve(args.first)
100
- invitation = @access.invite(id, name: options[:name], kind: options[:agent] ? "agent" : "human", ttl: ttl)
120
+ invitation = @access.invite(id, name: options[:name], kind: options[:agent] ? "agent" : "human", ttl: ttl, cap: cap)
101
121
  print_invitation(id, invitation)
122
+ @changes = [[:joined, invitation.participant.id]]
102
123
  0
103
124
  end
104
125
 
@@ -120,6 +141,34 @@ module Samagotchi
120
141
  0
121
142
  end
122
143
 
144
+ CAP_USAGE = "a cap is dollars, $0 to $#{Web::Grants::MAX_CAP.to_i} (e.g. --cap 5)".freeze
145
+
146
+ def run_cap(_options, args)
147
+ return usage_error("give a session ID, a participant and dollars (chi share cap ID p_… 5)") unless args.size == 3
148
+
149
+ participant = args[1]
150
+ return usage_error("not a participant: #{participant} (chi share ls lists them)") unless Web::Grants::ID_RE.match?(participant)
151
+
152
+ cap = dollars(args[2])
153
+ return usage_error(CAP_USAGE) if cap == false
154
+
155
+ id = @access.resolve(args.first)
156
+ row = @access.set_participant_cap(id, participant: participant, cap: cap)
157
+ @stdout.puts("#{row.id} #{row.name} cap #{money(row.cap)}")
158
+ 0
159
+ end
160
+
161
+ # A Float for "5", "2.50" or "$3" in the cap's range; false otherwise.
162
+ def dollars(words)
163
+ text = words.to_s.strip.delete_prefix("$")
164
+ return false unless text.match?(/\A\d+(?:\.\d+)?\z/)
165
+
166
+ value = text.to_f
167
+ Web::Grants.cap?(value) ? value : false
168
+ end
169
+
170
+ def money(value) = value.nil? ? "-" : format("$%.2f", value)
171
+
123
172
  def run_revoke(options, args)
124
173
  if options[:all]
125
174
  return usage_error("--all takes no session ID") unless args.empty?
@@ -132,36 +181,32 @@ module Samagotchi
132
181
  id = args.first && @access.resolve(args.first)
133
182
  revoked = @access.revoke_participants(id, participant: participant)
134
183
  revoked.each { |row| @stdout.puts("#{row.id} #{row.name} revoked") }
184
+ @changes = revoked.map { |row| [:left, row.id] }
135
185
  @stdout.puts("nothing to revoke") if revoked.empty?
136
186
  0
137
187
  end
138
188
 
139
- # Seconds, nil for the default, false for words that aren't Nh/Nd.
140
- def expires(words)
141
- return nil if words.nil?
142
-
143
- match = EXPIRES_RE.match(words.to_s.strip) or return false
144
- seconds = match[1].to_i * (match[2] == "h" ? 3600 : Web::Grants::DAY)
145
- seconds.between?(3600, Web::Grants::MAX_TTL) ? seconds : false
146
- end
147
-
148
189
  def print_invitation(id, invitation)
149
190
  row = invitation.participant
150
- @stdout.puts("#{row.id} #{row.name} (#{row.kind}, #{row.role}) · session #{id[0, 8]} · expires #{local(row.expires_at, "%Y-%m-%d %H:%M")}")
191
+ @stdout.puts("#{row.id} #{row.name} (#{row.kind}, #{row.role}) · session #{id[0, 8]} · expires " \
192
+ "#{local(row.expires_at, "%Y-%m-%d %H:%M")} · cap #{money(row.cap)}")
151
193
  @stdout.puts(invitation.link)
152
194
  @stdout.puts("(shown once: chi keeps only its digest; chi share revoke #{id[0, 8]} #{row.id} ends it)")
195
+ if invitation.warning
196
+ error_line("#{command_name}: warning: #{invitation.warning} (#{@access.invocation.command("review --from #{id[0, 8]}")} starts one)")
197
+ end
153
198
  unless invitation.lan
154
- @stdout.puts("chi web isn't on the LAN there (web.host: lan): this link opens on that machine only")
199
+ @stdout.puts("chi web isn't on the LAN there (web.host: lan): this link opens on that machine only, as the participant")
155
200
  end
156
201
  @stdout.puts(Web::QR.lines(invitation.link)) if @tty
157
202
  end
158
203
 
159
- COLUMNS = ["SESSION", "PARTICIPANT", "NAME", "KIND", "ROLE", "CREATED", "EXPIRES", "LAST USED", "STATE"].freeze
204
+ COLUMNS = ["SESSION", "PARTICIPANT", "NAME", "KIND", "ROLE", "CREATED", "EXPIRES", "LAST USED", "CAP", "STATE"].freeze
160
205
 
161
206
  def print_table(rows)
162
207
  cells = rows.map do |row|
163
208
  [row.session_id[0, 8], row.id, row.name, row.kind, row.role, local(row.created_at), local(row.expires_at),
164
- row.last_used_at ? local(row.last_used_at) : "-", row.state]
209
+ row.last_used_at ? local(row.last_used_at) : "-", money(row.cap), row.state]
165
210
  end
166
211
  widths = COLUMNS.each_index.map { |i| ([COLUMNS[i]] + cells.map { |c| c[i] }).map(&:length).max }
167
212
  [COLUMNS, *cells].each do |line|
@@ -16,10 +16,12 @@ module Samagotchi
16
16
  # usage.cost), nil when not reported
17
17
  # @!attribute price [ModelPrice, nil] the target host's price for the
18
18
  # model (IdleTarget#price), what the cost is estimated from
19
+ # @!attribute author [String, nil] the participant whose turn caused it
20
+ # ("p:<id>", Engine#note_side_usage stamps it), nil for the owner
19
21
  SideUsage = Data.define(:kind, :model, :prompt_tokens, :completion_tokens, :cached_tokens, :cache_write_tokens,
20
- :reasoning_tokens, :cost, :price) do
22
+ :reasoning_tokens, :cost, :price, :author) do
21
23
  def initialize(kind:, model: nil, prompt_tokens: 0, completion_tokens: 0, cached_tokens: 0, cache_write_tokens: 0,
22
- reasoning_tokens: 0, cost: nil, price: nil)
24
+ reasoning_tokens: 0, cost: nil, price: nil, author: nil)
23
25
  super
24
26
  end
25
27