samagotchi 0.182.0 → 0.183.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 (161) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +68 -1
  3. data/bin/chi +3 -1
  4. data/docs/architecture.md +16 -6
  5. data/docs/bundle-authoring.md +1 -1
  6. data/docs/bundles.md +103 -4
  7. data/docs/cli.md +28 -6
  8. data/docs/configuration.md +2 -1
  9. data/docs/guardrails.md +16 -1
  10. data/docs/internals/block-renderers.md +58 -3
  11. data/docs/internals/bridge.md +13 -5
  12. data/docs/internals/bundles.md +21 -4
  13. data/docs/internals/engine.md +18 -8
  14. data/docs/internals/remote-sessions.md +24 -5
  15. data/docs/internals/web-frontend.md +88 -28
  16. data/docs/internals/working-set.md +1 -1
  17. data/docs/mcp-server.md +80 -0
  18. data/docs/plugins.md +308 -21
  19. data/docs/sessions.md +3 -3
  20. data/docs/sub-agent.md +9 -0
  21. data/docs/testing.md +3 -1
  22. data/docs/thin-clients.md +146 -0
  23. data/lib/samagotchi/bridge/pending_card.rb +4 -3
  24. data/lib/samagotchi/bridge/sse_writer.rb +16 -15
  25. data/lib/samagotchi/bridge.rb +59 -68
  26. data/lib/samagotchi/bundle_command/api_calls.rb +1 -1
  27. data/lib/samagotchi/bundle_command/check.rb +36 -19
  28. data/lib/samagotchi/bundle_command.rb +50 -21
  29. data/lib/samagotchi/bundle_manifest.rb +101 -4
  30. data/lib/samagotchi/bundles/dev/manifest.yml +2 -2
  31. data/lib/samagotchi/bundles/mcp/client.rb +260 -0
  32. data/lib/samagotchi/bundles/mcp/content.rb +107 -0
  33. data/lib/samagotchi/bundles/mcp/http_client.rb +407 -0
  34. data/lib/samagotchi/bundles/mcp/manifest.yml +13 -5
  35. data/lib/samagotchi/bundles/mcp/oauth.rb +814 -0
  36. data/lib/samagotchi/bundles/mcp/plugin.rb +556 -574
  37. data/lib/samagotchi/bundles/mcp/tools.rb +232 -0
  38. data/lib/samagotchi/bundles/system/config_modification_protocol.md +10 -2
  39. data/lib/samagotchi/bundles/system/manifest.yml +2 -2
  40. data/lib/samagotchi/cli/parent_wait.rb +5 -3
  41. data/lib/samagotchi/command_intake.rb +7 -0
  42. data/lib/samagotchi/commands/registry.rb +8 -3
  43. data/lib/samagotchi/continue_offer.rb +24 -15
  44. data/lib/samagotchi/engine/block_fix.rb +4 -4
  45. data/lib/samagotchi/engine/cards.rb +14 -5
  46. data/lib/samagotchi/engine/events.rb +10 -15
  47. data/lib/samagotchi/engine/models.rb +1 -1
  48. data/lib/samagotchi/engine/plugins.rb +3 -0
  49. data/lib/samagotchi/engine/recap.rb +1 -1
  50. data/lib/samagotchi/engine/side_requests.rb +1 -1
  51. data/lib/samagotchi/engine/sign_in.rb +142 -0
  52. data/lib/samagotchi/engine/turn_end.rb +3 -3
  53. data/lib/samagotchi/engine.rb +43 -27
  54. data/lib/samagotchi/engine_snapshots.rb +1 -1
  55. data/lib/samagotchi/guardrail_wiring.rb +3 -1
  56. data/lib/samagotchi/guardrails/protected_paths.rb +51 -2
  57. data/lib/samagotchi/guardrails/verdict.rb +3 -2
  58. data/lib/samagotchi/hold_stop.rb +4 -4
  59. data/lib/samagotchi/idle_recap.rb +19 -11
  60. data/lib/samagotchi/idle_reminders.rb +7 -5
  61. data/lib/samagotchi/idle_scheduler.rb +7 -10
  62. data/lib/samagotchi/installed_bundles/dir.rb +37 -0
  63. data/lib/samagotchi/installed_bundles/manifest.rb +7 -1
  64. data/lib/samagotchi/installed_bundles/plugin_ref.rb +9 -5
  65. data/lib/samagotchi/installed_bundles/record.rb +3 -2
  66. data/lib/samagotchi/installed_bundles/standing.rb +3 -1
  67. data/lib/samagotchi/llm/http.rb +96 -5
  68. data/lib/samagotchi/mcp_command.rb +110 -0
  69. data/lib/samagotchi/mcp_server/http.rb +112 -0
  70. data/lib/samagotchi/mcp_server/protocol.rb +244 -0
  71. data/lib/samagotchi/mcp_server/stdio.rb +92 -0
  72. data/lib/samagotchi/mcp_server/text.rb +155 -0
  73. data/lib/samagotchi/mcp_server/tools.rb +245 -0
  74. data/lib/samagotchi/memory_bundle/asset_installer.rb +40 -12
  75. data/lib/samagotchi/memory_bundle/builder.rb +20 -2
  76. data/lib/samagotchi/memory_bundle/installed_copy.rb +1 -1
  77. data/lib/samagotchi/memory_bundle/installer.rb +16 -3
  78. data/lib/samagotchi/memory_bundle/provenance.rb +18 -1
  79. data/lib/samagotchi/memory_bundle/shas.rb +6 -4
  80. data/lib/samagotchi/memory_bundle/shipped_update.rb +7 -3
  81. data/lib/samagotchi/memory_bundle/status.rb +15 -6
  82. data/lib/samagotchi/memory_bundle/uninstaller.rb +9 -4
  83. data/lib/samagotchi/plugin/api.rb +6 -1
  84. data/lib/samagotchi/plugin/card.rb +36 -11
  85. data/lib/samagotchi/plugin/context.rb +63 -6
  86. data/lib/samagotchi/plugin/http.rb +40 -15
  87. data/lib/samagotchi/plugin/http_errors.rb +15 -0
  88. data/lib/samagotchi/plugin/http_stream.rb +86 -0
  89. data/lib/samagotchi/plugin/http_transport.rb +58 -16
  90. data/lib/samagotchi/plugin/loader.rb +18 -11
  91. data/lib/samagotchi/plugin/secrets.rb +266 -0
  92. data/lib/samagotchi/plugin/sign_in.rb +392 -0
  93. data/lib/samagotchi/plugin/sse_reader.rb +103 -0
  94. data/lib/samagotchi/queued_command.rb +28 -4
  95. data/lib/samagotchi/recap_setup.rb +13 -4
  96. data/lib/samagotchi/ref.rb +3 -2
  97. data/lib/samagotchi/relay_verifier.rb +8 -7
  98. data/lib/samagotchi/relay_watcher.rb +4 -4
  99. data/lib/samagotchi/run_options.rb +2 -1
  100. data/lib/samagotchi/send_command.rb +54 -41
  101. data/lib/samagotchi/session_access/ask.rb +244 -0
  102. data/lib/samagotchi/session_access/contract.rb +5 -0
  103. data/lib/samagotchi/session_access/exchange/token.rb +101 -0
  104. data/lib/samagotchi/session_access/exchange.rb +173 -0
  105. data/lib/samagotchi/session_access/local.rb +25 -6
  106. data/lib/samagotchi/session_access/remote.rb +4 -1
  107. data/lib/samagotchi/session_command_catalog.rb +10 -0
  108. data/lib/samagotchi/session_commands.rb +17 -0
  109. data/lib/samagotchi/session_config.rb +4 -4
  110. data/lib/samagotchi/session_observer.rb +27 -0
  111. data/lib/samagotchi/steer_cut.rb +4 -3
  112. data/lib/samagotchi/terminal_ui/attached_loop/sending.rb +4 -1
  113. data/lib/samagotchi/terminal_ui/formatting.rb +15 -0
  114. data/lib/samagotchi/testing/boundary.rb +4 -0
  115. data/lib/samagotchi/testing/bundle.rb +48 -2
  116. data/lib/samagotchi/testing/fake_http.rb +60 -15
  117. data/lib/samagotchi/testing/host.rb +4 -1
  118. data/lib/samagotchi/testing/recorder.rb +45 -5
  119. data/lib/samagotchi/tools/tool_index.rb +14 -3
  120. data/lib/samagotchi/version.rb +1 -1
  121. data/lib/samagotchi/web/app.rb +8 -6
  122. data/lib/samagotchi/web/ask_routes.rb +292 -0
  123. data/lib/samagotchi/web/mcp_route.rb +88 -0
  124. data/lib/samagotchi/web/public/app.js +2 -3
  125. data/lib/samagotchi/web/public/block_frame.js +72 -11
  126. data/lib/samagotchi/web/public/block_host.js +44 -8
  127. data/lib/samagotchi/web/public/block_regions.js +126 -0
  128. data/lib/samagotchi/web/public/card.js +22 -9
  129. data/lib/samagotchi/web/public/card_actions.js +21 -0
  130. data/lib/samagotchi/web/public/card_kinds.js +1 -1
  131. data/lib/samagotchi/web/public/card_registry.js +3 -2
  132. data/lib/samagotchi/web/public/data.js +15 -12
  133. data/lib/samagotchi/web/public/delete_sheet.js +222 -162
  134. data/lib/samagotchi/web/public/diagram_wiring.js +28 -0
  135. data/lib/samagotchi/web/public/format.js +3 -0
  136. data/lib/samagotchi/web/public/index.html +52 -7
  137. data/lib/samagotchi/web/public/more_sheet.js +6 -4
  138. data/lib/samagotchi/web/public/picture_regions.js +243 -0
  139. data/lib/samagotchi/web/public/picture_viewer.js +113 -12
  140. data/lib/samagotchi/web/public/refs.js +5 -3
  141. data/lib/samagotchi/web/public/region_hit.js +144 -0
  142. data/lib/samagotchi/web/public/removal_sheet_model.js +275 -0
  143. data/lib/samagotchi/web/public/running_tasks.js +6 -4
  144. data/lib/samagotchi/web/public/session_actions.js +105 -100
  145. data/lib/samagotchi/web/session_access_routes.rb +14 -11
  146. data/lib/samagotchi/web/session_control.rb +31 -9
  147. data/lib/samagotchi/web/session_create.rb +2 -2
  148. data/lib/samagotchi/worker/child_side.rb +3 -2
  149. data/lib/samagotchi/worker/command_queue.rb +13 -13
  150. data/lib/samagotchi/worker/leave.rb +3 -3
  151. data/lib/samagotchi/worker/scratch.rb +6 -6
  152. data/lib/samagotchi/worker/signal_grace.rb +6 -5
  153. data/lib/samagotchi/worker/startup.rb +3 -3
  154. data/lib/samagotchi/worker/wake_turns.rb +4 -4
  155. data/lib/samagotchi/worker.rb +32 -21
  156. data/lib/samagotchi/worker_exit_claim.rb +1 -1
  157. data/lib/samagotchi/worker_idle_exit.rb +18 -9
  158. data/lib/samagotchi/worker_inbound.rb +12 -7
  159. data/lib/samagotchi/worker_participant_gate.rb +9 -7
  160. data/lib/samagotchi/worker_task_wakes.rb +7 -5
  161. metadata +31 -1
@@ -54,7 +54,7 @@ module Samagotchi
54
54
  # turn via HTTP POST.
55
55
  #
56
56
  # Design invariants (see multi_ui_architecture):
57
- # * Reuses `Engine#subscribe` for SSE fan-out — never a second Engine, never
57
+ # * Reuses the Engine's event log (`event_log:`) for SSE fan-out — never a second Engine, never
58
58
  # `run_turn` across the thread/process boundary. POST reuses the
59
59
  # `SessionInbox` file-IPC input path.
60
60
  # * One capture observer fills a shared ring buffer; each connection gets a
@@ -69,33 +69,18 @@ module Samagotchi
69
69
  include BlockFixRoute
70
70
 
71
71
  ENGINE_CALLS = {
72
- active_cancel_controller: "turn-state monitor",
73
- annotate_question: "question-desk control",
74
- announce: "event-log monitor",
75
- answer_question: "question-desk control",
76
- cancel_current_turn!: "turn cancellation",
77
- cancel_question: "question-desk control",
78
72
  command_registry: "startup-built registry",
79
- cut_for_steer: "steer-cut coordination",
80
- drop_enqueued_id: "turn-state monitor",
81
- enqueued_id?: "turn-state monitor",
82
73
  fix_block: "block-fix mutex; replace-only session messages",
83
- event_count: "observer-registry monitor",
84
- forget_enqueued_id: "turn-state monitor",
85
- generation_snapshot: "generation-phase snapshot",
86
74
  guardrail_warning: "startup-set warning reader",
87
75
  init_tasks: "plugin-task monitor",
88
- input_epoch: "waiting-steer monitor",
89
76
  last_answer_message: "message snapshot under event lock",
90
77
  messages_checkpoint: "replace-only message copy",
91
78
  objectives_view: "objectives snapshot under event lock",
92
- pending_question: "question-desk monitor",
93
79
  plugin_warning: "warning-state reader",
94
80
  recap: "recap-job reference",
95
81
  recap_override: "session-setting reader",
96
82
  relay_desk: "relay-store reference; status is monitor-protected",
97
83
  request_recap: "idle-recap monitor",
98
- reserve_enqueued_id: "turn-state monitor",
99
84
  working_set_snapshot: "idle working-set snapshot under event lock",
100
85
  working_set_item: "turn view under its mutex, else session messages under event lock",
101
86
  "running_turn_messages=": "callback writer; Bridge lifecycle",
@@ -103,11 +88,7 @@ module Samagotchi
103
88
  session: "session reference; messages are replace-only",
104
89
  session_state_snapshot: "snapshot; event lock for consistency",
105
90
  stats_snapshot: "stats snapshot; may probe model",
106
- steer_cut_after: "per-read model setting",
107
- subscribe: "observer-registry monitor",
108
- synchronize_events: "event-log monitor",
109
- turn_running?: "turn-state monitor",
110
- unsubscribe: "observer-registry monitor"
91
+ steer_cut_after: "per-read model setting"
111
92
  }.freeze
112
93
 
113
94
  DEFAULT_BIND = "127.0.0.1"
@@ -136,6 +117,10 @@ module Samagotchi
136
117
  SECRET_BYTES = 32
137
118
  # @param engine [Samagotchi::Engine] the owning engine (must already live
138
119
  # in this process)
120
+ # @param event_log [SessionObserver] that engine's event log (Engine#event_log)
121
+ # @param turn_state [TurnState] that engine's turn state (Engine#turn_state)
122
+ # @param question_desk [QuestionDesk] that engine's question desk (Engine#question_desk)
123
+ # @param steer_cut [SteerCut] that engine's steer cut (Engine#steer_cut)
139
124
  # @param state_dir [String] the session state directory root
140
125
  # @param session_id [String] this bridge's session id
141
126
  # @param bind [String] bind address (127.0.0.1 only)
@@ -176,12 +161,16 @@ module Samagotchi
176
161
  # @param on_activity [#call, nil] what the worker is busy with right now
177
162
  # (Worker#activity_snapshot: the same signals WorkerIdleExit#hold reads)
178
163
  # for GET /activity; without one that route answers 501
179
- def initialize(engine:, state_dir:, session_id:, bind: DEFAULT_BIND,
164
+ def initialize(engine:, event_log:, turn_state:, question_desk:, steer_cut:, state_dir:, session_id:, bind: DEFAULT_BIND,
180
165
  port: 0, ring_capacity: DEFAULT_RING_CAPACITY,
181
166
  heartbeat_interval: DEFAULT_HEARTBEAT_INTERVAL, input_format: nil, on_input: nil,
182
167
  on_command: nil, on_exit_request: nil, exit_discards: nil, exit_stopped: nil,
183
168
  on_holds: nil, on_holds_stop: nil, on_activity: nil)
184
169
  @engine = engine
170
+ @event_log = event_log
171
+ @turn_state = turn_state
172
+ @question_desk = question_desk
173
+ @steer_cut = steer_cut
185
174
  @on_input = on_input
186
175
  @on_command = on_command
187
176
  @on_exit_request = on_exit_request
@@ -288,15 +277,15 @@ module Samagotchi
288
277
  def start
289
278
  @server = TCPServer.new(@bind, @port)
290
279
  @port = @server.local_address.ip_port
291
- @capture_handle = @engine.subscribe(observer: capture_observer)
292
- @accumulator_handle = @engine.subscribe(observer: @accumulator)
293
- @drawings_handle = @engine.subscribe(observer: @drawings)
280
+ @capture_handle = @event_log.subscribe(observer: capture_observer)
281
+ @accumulator_handle = @event_log.subscribe(observer: @accumulator)
282
+ @drawings_handle = @event_log.subscribe(observer: @drawings)
294
283
  # A plugin's ctx.messages mid-turn holds the turn so far (plan O1).
295
284
  @engine.running_turn_messages = -> { @accumulator.current_messages }
296
- @cards_handle = @engine.subscribe(observer: @cards)
285
+ @cards_handle = @event_log.subscribe(observer: @cards)
297
286
  # One a worker that died left is not open.
298
287
  @pending_card.clear
299
- @pending_card_handle = @engine.subscribe(observer: @pending_card)
288
+ @pending_card_handle = @event_log.subscribe(observer: @pending_card)
300
289
  # #stop and #close_intake wake the acceptor through it: closing the
301
290
  # listen socket doesn't cut a select on it short on Linux.
302
291
  @wake_reader, @wake_writer = IO.pipe
@@ -400,12 +389,12 @@ module Samagotchi
400
389
  # guardrail_warning:, plugin_warning:, init_tasks:, cards:, commands:, chi_version:, event_seq:, event_id:, last_turn_drawing:,
401
390
  # objectives:, idle_working_set:}
402
391
  def snapshot
403
- @engine.synchronize_events do
404
- seq = @engine.event_count
392
+ @event_log.synchronize do
393
+ seq = @event_log.event_count
405
394
  messages = @engine.messages_checkpoint
406
395
  drawing = last_turn_drawing(messages)
407
396
  idle_working_set_unavailable = Object.new
408
- idle_working_set = if @engine.turn_running?
397
+ idle_working_set = if @turn_state.running?
409
398
  idle_working_set_unavailable
410
399
  else
411
400
  Degrade.call(:bridge, "working_set_snapshot_failed", fallback: idle_working_set_unavailable) do
@@ -425,7 +414,7 @@ module Samagotchi
425
414
  recap: @accumulator.recap,
426
415
  saved_recap: @engine.saved_recap,
427
416
  continue_offer: @accumulator.continue_offer,
428
- pending_question: @engine.pending_question&.to_h,
417
+ pending_question: @question_desk.pending&.to_h,
429
418
  guardrail_warning: @engine.guardrail_warning,
430
419
  plugin_warning: @engine.plugin_warning,
431
420
  init_tasks: @engine.init_tasks,
@@ -481,7 +470,7 @@ module Samagotchi
481
470
  # snapshot or reset frame (SSEWriter) and GET snapshot carry.
482
471
  # @return [Hash] {snapshot:, session_state_snapshot:}
483
472
  def snapshot_frame
484
- @engine.synchronize_events do
473
+ @event_log.synchronize do
485
474
  snap = snapshot
486
475
  state = @engine.session_state_snapshot.merge(event_seq: snap[:event_seq], event_id: snap[:event_id])
487
476
  { snapshot: snap, session_state_snapshot: state }
@@ -498,8 +487,8 @@ module Samagotchi
498
487
  # @return [Hash] {session_id:, working_directory:, session_state_snapshot:, answer:, cards:, event_seq:, event_id:}
499
488
  # +turn_id+: that turn's answer, not the newest (Engine#last_answer_message).
500
489
  def tail_frame(turn_id: nil)
501
- @engine.synchronize_events do
502
- seq = @engine.event_count
490
+ @event_log.synchronize do
491
+ seq = @event_log.event_count
503
492
  state = @engine.session_state_snapshot.merge(event_seq: seq, event_id: event_id(seq))
504
493
  { session_id: @session_id, working_directory: @engine.session&.working_directory,
505
494
  session_state_snapshot: state, answer: @engine.last_answer_message(turn_id: turn_id),
@@ -517,9 +506,10 @@ module Samagotchi
517
506
  # A card's action (the step-limit question's answer): the UIs leave
518
507
  # its line out. +enqueued_id+: a file-delivered command's input, whose
519
508
  # sender's wait its command_ran settles. +author+: its input's.
520
- command = QueuedCommand.mint(line.to_s.strip, client_id: client_id, card: card, author: author)
509
+ line = line.to_s.strip
510
+ command = QueuedCommand.mint(line, client_id: client_id, card: card, author: author, private_args: command_registry.private_args?(line))
521
511
  .with(enqueued_id: enqueued_id)
522
- @engine.synchronize_events { queue_command_locked(command, after_file: after_file) }
512
+ @event_log.synchronize { queue_command_locked(command, after_file: after_file) }
523
513
  command.command_id
524
514
  end
525
515
 
@@ -534,11 +524,11 @@ module Samagotchi
534
524
 
535
525
  # The turn in progress (TurnAccumulator#current_turn) with the running
536
526
  # generation's phase as generation: {thinking_only:, age:}
537
- # (Engine#generation_snapshot), so a page joining mid-generation can
527
+ # (SteerCut#generation_snapshot), so a page joining mid-generation can
538
528
  # clock its delivery line and say whether a cut can land.
539
529
  def current_turn_with_generation
540
530
  turn = @accumulator.current_turn
541
- gen = turn && @engine.generation_snapshot
531
+ gen = turn && @steer_cut.generation_snapshot
542
532
  gen ? turn.merge(generation: gen.to_h) : turn
543
533
  end
544
534
 
@@ -694,7 +684,7 @@ module Samagotchi
694
684
  end
695
685
 
696
686
  writer = SSEWriter.new(
697
- engine: @engine,
687
+ event_log: @event_log,
698
688
  ring: @ring,
699
689
  session_id: @session_id,
700
690
  last_event_id: last_event_id,
@@ -702,7 +692,7 @@ module Samagotchi
702
692
  frame_provider: -> { snapshot_frame },
703
693
  # A reconnect (with a cursor) replays; only a fresh join snapshots.
704
694
  join_with_snapshot: snapshot && last_event_id.nil?,
705
- bridge: self,
695
+ stopped: method(:stopped?),
706
696
  heartbeat_interval: @heartbeat_interval,
707
697
  raw: raw
708
698
  )
@@ -903,10 +893,10 @@ module Samagotchi
903
893
  turn_id = nil if turn_id && turn_id.empty?
904
894
  end
905
895
 
906
- if @engine.turn_running? && @engine.active_cancel_controller
907
- # With a turn_id the engine compares it to the running turn's under
908
- # its lock; clients that send none (older ones) cancel whichever runs.
909
- ok = turn_id ? @engine.cancel_current_turn!(reason, turn_id: turn_id) : @engine.cancel_current_turn!(reason)
896
+ if @turn_state.running? && @turn_state.controller
897
+ # With a turn_id the turn state compares it to the running turn's under
898
+ # its lock; clients that send none (older ones, nil) cancel whichever runs.
899
+ ok = @turn_state.cancel!(reason, turn_id: turn_id)
910
900
  if ok == :turn_mismatch
911
901
  return [{}, 409, { error: "turn_mismatch", detail: "the running turn is not the one named", session_id: @session_id }]
912
902
  end
@@ -980,9 +970,9 @@ module Samagotchi
980
970
  return deadline_passed("answer") if expired?("answer_expired", deadline, sid: session_id, id: qid)
981
971
 
982
972
  begin
983
- result = @engine.answer_question(id: qid, selected: selected, freeform: freeform, client_id: client_id)
973
+ result = @question_desk.answer(id: qid, selected: selected, freeform: freeform, client_id: client_id)
984
974
  [{}, 200, { status: "answered", session_id: session_id, answer: result.to_h }]
985
- rescue Engine::QuestionNotPending => e
975
+ rescue QuestionDesk::NotPending => e
986
976
  # Another client answered first, or the question was cancelled.
987
977
  [{}, 409, { error: "question_not_pending", detail: e.message }]
988
978
  rescue QuestionDesk::Refused => e
@@ -1045,7 +1035,7 @@ module Samagotchi
1045
1035
  reason = fetched(parsed, "reason").to_s
1046
1036
  relay_closed(qid, relay_id, RELAY_CLOSE_REASONS.include?(reason) ? reason : "closed")
1047
1037
  else
1048
- RelayVerifier.new(engine: @engine, state_dir: @state_dir, session_id: session_id)
1038
+ RelayVerifier.new(question_desk: @question_desk, state_dir: @state_dir, session_id: session_id)
1049
1039
  .answer(relay_id: relay_id, question_id: qid)
1050
1040
  end
1051
1041
  end
@@ -1053,7 +1043,7 @@ module Samagotchi
1053
1043
  # Dismiss the pending question (an empty answer at a terminal): the
1054
1044
  # tool returns without an answer and every UI gets :question_cancelled.
1055
1045
  # Only the question the client saw, and only while nobody has answered
1056
- # it: Engine#cancel_question checks both under the question lock. A past
1046
+ # it: QuestionDesk#cancel checks both under the question lock. A past
1057
1047
  # +deadline+ (dismissing an approval denies it): 408, as for an answer.
1058
1048
  # Returns [headers, status, body].
1059
1049
  def handle_dismiss_question(session_id, body)
@@ -1068,7 +1058,7 @@ module Samagotchi
1068
1058
  return deadline_passed("dismissal") if expired?("dismiss_expired", deadline, sid: session_id, id: qid)
1069
1059
 
1070
1060
  begin
1071
- dismissed = @engine.cancel_question("dismissed", id: qid)
1061
+ dismissed = @question_desk.cancel("dismissed", id: qid)
1072
1062
  rescue QuestionDesk::NotDismissable => e
1073
1063
  # A step-limit question: its answer is Continue or Stop.
1074
1064
  return [{}, 409, { error: "not_dismissable", detail: e.message }]
@@ -1124,8 +1114,8 @@ module Samagotchi
1124
1114
  # /turn's (a /word sent as a message).
1125
1115
  def queue_command_request(session_id, line, client_id:, deadline: nil, card: false, author: nil)
1126
1116
  # A card's action: the UIs leave its line out (the card is the echo).
1127
- command = QueuedCommand.mint(line, client_id: client_id, card: card, author: author)
1128
- queued = @engine.synchronize_events do
1117
+ command = QueuedCommand.mint(line, client_id: client_id, card: card, author: author, private_args: command_registry.private_args?(line))
1118
+ queued = @event_log.synchronize do
1129
1119
  raise IntakeClosed if stopped?
1130
1120
  next false if expired?("command_expired", deadline, sid: session_id, client_id: command.client_id)
1131
1121
 
@@ -1149,7 +1139,7 @@ module Samagotchi
1149
1139
  when :queue then { waits: "turn_end" }
1150
1140
  else {}
1151
1141
  end
1152
- @engine.announce(type: :command_queued, **command.event_fields, **marks)
1142
+ @event_log.announce(type: :command_queued, **command.event_fields, **marks)
1153
1143
  end
1154
1144
 
1155
1145
  # A client asks the worker to exit now (`/exit` in the attached TUI), or
@@ -1190,7 +1180,7 @@ module Samagotchi
1190
1180
  return BAD_DEADLINE unless deadline_valid?(deadline)
1191
1181
 
1192
1182
  stopped = nil
1193
- hold = @engine.synchronize_events do
1183
+ hold = @event_log.synchronize do
1194
1184
  raise IntakeClosed if stopped?
1195
1185
  next :expired if expired?("exit_expired", deadline, sid: session_id, client_id: client_id)
1196
1186
 
@@ -1359,6 +1349,7 @@ module Samagotchi
1359
1349
  return [{}, 403, { error: CommandIntake::REFUSED_ERROR, detail: CommandIntake::REFUSED }]
1360
1350
  end
1361
1351
  end
1352
+ return CommandIntake::PRIVATE_REFUSED if command_registry.private_args?(prompt.to_s) # never a message
1362
1353
 
1363
1354
  enqueued_id = fetched(parsed, "enqueued_id")
1364
1355
  enqueued_id = SessionInbox.new_enqueued_id unless SessionInbox.valid_enqueued_id?(enqueued_id)
@@ -1371,7 +1362,7 @@ module Samagotchi
1371
1362
  pending_limit:, enqueued_id:)
1372
1363
  # Before it is queued: a drain after this may have taken it (#cut_for_steer).
1373
1364
  @post_turn_mutex.synchronize do
1374
- epoch = @engine.input_epoch
1365
+ epoch = @steer_cut.input_epoch
1375
1366
  # Whether a queue waits for a running turn: read with the write under
1376
1367
  # the event log, so no :turn_started or :turn_completed falls between.
1377
1368
  # To an idle worker the queued file simply runs as the next turn.
@@ -1379,17 +1370,17 @@ module Samagotchi
1379
1370
  # Write and announce with the event log held: the worker can't emit
1380
1371
  # this turn's :turn_started (or merge it mid-turn) before
1381
1372
  # :turn_enqueued, and a failed write announces nothing.
1382
- enqueued = @engine.synchronize_events do
1373
+ enqueued = @event_log.synchronize do
1383
1374
  raise IntakeClosed if stopped?
1384
1375
 
1385
1376
  existing = @enqueued_requests[enqueued_id]
1386
1377
  if existing
1387
1378
  next(existing[:prompt] == prompt.to_s ? :duplicate : :conflict)
1388
1379
  end
1389
- next :duplicate if @engine.enqueued_id?(enqueued_id)
1380
+ next :duplicate if @turn_state.enqueued_id?(enqueued_id)
1390
1381
  next :expired if expired?("turn_expired", deadline, sid: sid, client_id: client_id)
1391
1382
  next :too_many if pending_limit && pending_turns(author) >= pending_limit
1392
- next :duplicate unless @engine.reserve_enqueued_id(enqueued_id)
1383
+ next :duplicate unless @turn_state.reserve_enqueued_id(enqueued_id)
1393
1384
 
1394
1385
  # Input goes into a running turn only of its own author: the
1395
1386
  # owner's never into a participant's turn (a steer, a cut), a
@@ -1399,7 +1390,7 @@ module Samagotchi
1399
1390
  queued_behind_turn = Delivery.queue?(delivery) && !@accumulator.current_turn.nil?
1400
1391
  unless enqueue_turn(prompt: prompt, client_id: client_id, enqueued_id: enqueued_id,
1401
1392
  no_interrupt: no_interrupt, images: images, delivery: delivery, author: author, anchors: anchors)
1402
- @engine.forget_enqueued_id(enqueued_id)
1393
+ @turn_state.forget_enqueued_id(enqueued_id)
1403
1394
  next false
1404
1395
  end
1405
1396
 
@@ -1407,7 +1398,7 @@ module Samagotchi
1407
1398
  enqueued_event[:images] = images unless images.empty?
1408
1399
  enqueued_event[:delivery] = Delivery::QUEUE if queued_behind_turn
1409
1400
  enqueued_event[:author] = author if author
1410
- @engine.announce(enqueued_event)
1401
+ @event_log.announce(enqueued_event)
1411
1402
  @on_input&.call
1412
1403
  true
1413
1404
  end
@@ -1431,7 +1422,7 @@ module Samagotchi
1431
1422
  # that says nothing (an older client, the web composer) goes in at
1432
1423
  # the running turn's next step.
1433
1424
  cut = nil
1434
- cut = @engine.cut_for_steer(Steer.source_for_client(client_id), epoch: epoch) if images.empty? && Delivery.cut?(delivery)
1425
+ cut = @steer_cut.cut_for_steer(Steer.source_for_client(client_id), epoch: epoch) if images.empty? && Delivery.cut?(delivery)
1435
1426
  # A queue to an idle worker is a turn now: the ack says next_step.
1436
1427
  ack_delivery = Delivery.queue?(delivery) && !queued_behind_turn ? Delivery::NEXT_STEP : delivery
1437
1428
  ack = { status: "accepted", enqueued_id: enqueued_id, session_id: @session_id, delivery: ack_delivery }
@@ -1472,14 +1463,14 @@ module Samagotchi
1472
1463
  return BAD_DEADLINE unless deadline_valid?(deadline)
1473
1464
 
1474
1465
  client_id = fetched(parsed, "client_id")
1475
- taken, input = @engine.synchronize_events do
1466
+ taken, input = @event_log.synchronize do
1476
1467
  raise IntakeClosed if stopped?
1477
1468
  next [:expired, nil] if expired?("dequeue_expired", deadline, sid: session_id, enqueued_id: id)
1478
1469
 
1479
1470
  SessionInbox.take_queued_input(session_dir, id).tap do |status, _|
1480
1471
  if status == :removed
1481
- @engine.drop_enqueued_id(id)
1482
- @engine.announce(type: :turn_dequeued, enqueued_id: id, client_id: client_id)
1472
+ @turn_state.drop_enqueued_id(id)
1473
+ @event_log.announce(type: :turn_dequeued, enqueued_id: id, client_id: client_id)
1483
1474
  end
1484
1475
  end
1485
1476
  end
@@ -1532,7 +1523,7 @@ module Samagotchi
1532
1523
  # from here. Read under the event lock, as snapshot_frame and tail_frame:
1533
1524
  # the state and its event_seq/event_id are one step of the event log.
1534
1525
  def handle_state(_session_id, _body = nil)
1535
- state = @engine.synchronize_events do
1526
+ state = @event_log.synchronize do
1536
1527
  snap = @engine.session_state_snapshot
1537
1528
  snap.merge(event_id: event_id(snap[:event_seq]))
1538
1529
  end
@@ -1801,10 +1792,10 @@ module Samagotchi
1801
1792
  return [{}, 422, { error: "relay_unverified", detail: "this session has no parent" }] unless parent_id
1802
1793
 
1803
1794
  marker = { parent_id: parent_id, parent_short: parent_id[0, 8], relay_id: relay_id }
1804
- return [{}, 409, { error: "question_not_pending", detail: "no pending question #{qid}" }] unless @engine.annotate_question(qid, relayed_to: marker)
1795
+ return [{}, 409, { error: "question_not_pending", detail: "no pending question #{qid}" }] unless @question_desk.annotate(qid, relayed_to: marker)
1805
1796
 
1806
1797
  Log.info(:bridge, "relay_opened", sid: @session_id, id: qid, parent: parent_id[0, 8])
1807
- watch = RelayWatcher.start(engine: @engine, question_id: qid, relay_id: relay_id,
1798
+ watch = RelayWatcher.start(question_desk: @question_desk, question_id: qid, relay_id: relay_id,
1808
1799
  parent_dir: Session.session_dir(parent_id, state_dir: @state_dir))
1809
1800
  @mutex.synchronize { @relay_watchers = (@relay_watchers || []).select(&:alive?) << watch }
1810
1801
  [{}, 200, { status: "opened", question_id: qid }]
@@ -1813,12 +1804,12 @@ module Samagotchi
1813
1804
  # The parent's relay card closed unanswered: the mark goes, if it is
1814
1805
  # still that relay's.
1815
1806
  def relay_closed(qid, relay_id, reason)
1816
- pending = @engine.pending_question
1807
+ pending = @question_desk.pending
1817
1808
  relay = pending&.relayed_to
1818
1809
  unless pending && pending.id.to_s == qid && relay && (relay[:relay_id] || relay["relay_id"]).to_s == relay_id
1819
1810
  return [{}, 409, { error: "question_not_pending", detail: "no question #{qid} relayed by #{relay_id}" }]
1820
1811
  end
1821
- return [{}, 409, { error: "question_not_pending", detail: "no pending question #{qid}" }] unless @engine.annotate_question(qid, relayed_to: nil, reason: reason)
1812
+ return [{}, 409, { error: "question_not_pending", detail: "no pending question #{qid}" }] unless @question_desk.annotate(qid, relayed_to: nil, reason: reason)
1822
1813
 
1823
1814
  Log.info(:bridge, "relay_closed", sid: @session_id, id: qid, reason: reason)
1824
1815
  [{}, 200, { status: "closed", question_id: qid }]
@@ -26,7 +26,7 @@ module Samagotchi
26
26
  "Plugin::Api" => { ctx: "Plugin::Context" },
27
27
  "Plugin::Context" => { sessions: "Plugin::Sessions", context: "Plugin::AttachedContext", http: "Plugin::Http",
28
28
  judgments: "Plugin::Judgments", cost: "SessionMetrics::Cost", usage: "SessionMetrics::Usage",
29
- log: "Plugin::Context::Logger" }
29
+ log: "Plugin::Context::Logger", secrets: "Plugin::Secrets" }
30
30
  }.freeze
31
31
  ROOTS = { ctx: "Plugin::Context", chi: "Plugin::Api" }.freeze
32
32
 
@@ -199,6 +199,7 @@ module Samagotchi
199
199
  case key
200
200
  when "files.description" then "a files: entry given as a mapping"
201
201
  when "session_settings.types", "settings.types" then "#{key.split(".").first}: as a mapping of keys to types"
202
+ when "plugin.parts" then "plugin: parts:"
202
203
  else "#{key}:"
203
204
  end
204
205
  end
@@ -207,7 +208,7 @@ module Samagotchi
207
208
 
208
209
  # @return [Boolean] whether a listed file is missing
209
210
  def check_files(manifest)
210
- listed = manifest.files.keys + Array(manifest.plugin && manifest.plugin[:file]) +
211
+ listed = manifest.files.keys + manifest.plugin_files.map(&:first) +
211
212
  manifest.scripts.keys.map { |s| File.join("scripts", s) }
212
213
  missing = listed.reject { |rel| File.file?(path(rel)) }
213
214
  missing.each do |rel|
@@ -225,8 +226,14 @@ module Samagotchi
225
226
  memories.include?(name) || MemoryBundle::MemoryFiles.repo_meta?(name)
226
227
  end
227
228
  loose.each { |name| unlisted(name, "files:") }
228
- plugin = manifest.plugin && manifest.plugin[:file]
229
- unlisted("plugin.rb", "plugin:") if File.file?(path("plugin.rb")) && plugin != "plugin.rb"
229
+ if manifest.plugin
230
+ plugin_files = manifest.plugin_files.map(&:first)
231
+ Dir.glob(path("*.rb")).map { |f| File.basename(f) }.sort.each do |name|
232
+ unlisted(name, "plugin: parts:") unless plugin_files.include?(name)
233
+ end
234
+ elsif File.file?(path("plugin.rb"))
235
+ unlisted("plugin.rb", "plugin:")
236
+ end
230
237
  Dir.glob(path("scripts/*")).sort.each do |file|
231
238
  unlisted("scripts/#{File.basename(file)}", "scripts:") unless manifest.scripts.key?(File.basename(file))
232
239
  end
@@ -278,20 +285,24 @@ module Samagotchi
278
285
  check_floor(manifest, line) if manifest.plugin && manifest.requires_chi && !@too_new && !@installed
279
286
  end
280
287
 
281
- # The plugin calls an API newer than the oldest chi requires_chi admits.
288
+ # The plugin calls an API newer than the oldest chi requires_chi admits:
289
+ # the newest call across all of the plugin's files.
282
290
  def check_floor(manifest, line)
283
291
  floor = lower_bound(manifest.requires_chi)
284
- return unless floor && File.file?(path(manifest.plugin[:file]))
292
+ return unless floor
285
293
 
286
- source = File.read(path(manifest.plugin[:file]))
287
- calls = source.scan(API_CALL).flat_map { |call| [call, call.split(".").first(2).join(".")] }
288
- calls = (calls + ApiCalls.new(source).keywords).uniq.select { |call| Plugin::Api::SINCE.key?(call) }
289
- call = calls.max_by { |c| Gem::Version.new(Plugin::Api::SINCE[c]) } or return
294
+ found = plugin_sources(manifest).flat_map do |file, source|
295
+ calls = source.scan(API_CALL).flat_map { |call| [call, call.split(".").first(2).join(".")] }
296
+ (calls + ApiCalls.new(source).keywords).uniq.select { |call| Plugin::Api::SINCE.key?(call) }.map { |call| [file, call] }
297
+ end
298
+ return if found.empty?
299
+
300
+ file, call = found.max_by { |_, c| Gem::Version.new(Plugin::Api::SINCE[c]) }
290
301
  version = Plugin::Api::SINCE[call]
291
302
  return unless Gem::Version.new(version) > floor
292
303
 
293
304
  add(:warn, :"requires-chi-floor", "manifest.yml",
294
- "requires_chi #{manifest.requires_chi.inspect} admits chi #{floor}, but #{manifest.plugin[:file]} uses " \
305
+ "requires_chi #{manifest.requires_chi.inspect} admits chi #{floor}, but #{file} uses " \
295
306
  "#{call}, which needs chi #{version}", line: line,
296
307
  fix: "requires_chi: \">= #{version}\"")
297
308
  end
@@ -445,25 +456,31 @@ module Samagotchi
445
456
  # A warning, as a name past the boundary is: the plugin may be written
446
457
  # for a newer chi, and a call on a path that never runs breaks nothing.
447
458
  def check_api(manifest)
448
- file = manifest.plugin && manifest.plugin[:file]
449
- return unless file && File.file?(path(file))
450
-
451
- ApiCalls.new(File.read(path(file))).findings.each do |finding|
452
- add(:warn, :api, file, finding.message, line: finding.line, fix: finding.fix)
459
+ plugin_sources(manifest).each do |file, source|
460
+ ApiCalls.new(source).findings.each do |finding|
461
+ add(:warn, :api, file, finding.message, line: finding.line, fix: finding.fix)
462
+ end
453
463
  end
454
464
  end
455
465
 
466
+ # [[file, text]] for each of the plugin's files on disk, parts first
467
+ # (BundleManifest#plugin_files' order); [] without a plugin.
468
+ def plugin_sources(manifest)
469
+ manifest.plugin_files.filter_map { |file, _| [file, File.read(path(file))] if File.file?(path(file)) }
470
+ end
471
+
456
472
  # A chi.on(..., on_error: :fail_closed) guard denies the call it raises
457
473
  # on; only the manifest's plugin: required: true makes its failing to
458
474
  # load deny every call (chi knows it before the plugin registers).
459
475
  FAIL_CLOSED = /on_error:\s*(?::fail_closed\b|["']fail_closed["'])/
460
476
 
461
477
  def check_fail_closed(manifest)
462
- file = manifest.plugin && manifest.plugin[:file]
463
- return if !file || manifest.plugin[:required] || !File.file?(path(file))
478
+ return if manifest.plugin.nil? || manifest.plugin[:required]
479
+
480
+ file, source = plugin_sources(manifest).find { |_, text| text.match?(FAIL_CLOSED) }
481
+ return unless source
464
482
 
465
- source = File.read(path(file))
466
- return unless (index = source =~ FAIL_CLOSED)
483
+ index = source =~ FAIL_CLOSED
467
484
 
468
485
  add(:warn, :"fail-closed", file, "a fail-closed chi.on hook, but the manifest's plugin: has no required: true: " \
469
486
  "if the plugin fails to load, tool calls still run",