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
@@ -112,7 +112,8 @@ module Samagotchi
112
112
  # What `chi bundle status NAME` says after a plugin's state
113
113
  # (MemoryBundle::Status.plugin_status) that keeps it from loading.
114
114
  PLUGIN_NOTES = { "modified" => " (edited after install: not loaded; reinstall the bundle)",
115
- "unrecorded" => " (no sha256 recorded: not loaded; reinstall the bundle)" }.freeze
115
+ "unrecorded" => " (no sha256 recorded: not loaded; reinstall the bundle)",
116
+ "parts missing" => " (its manifest names plugin parts the install has none of: not loaded; reinstall the bundle)" }.freeze
116
117
 
117
118
  # The subcommands' flags: --help only; a word not starting with -- is
118
119
  # a positional (install's source, -h included). --scope takes whatever
@@ -213,7 +214,7 @@ module Samagotchi
213
214
  return 1 if installed_under_another_name?(expanded_source, bundle_name, prepared, "Install")
214
215
 
215
216
  installer = installer_for(expanded_source, bundle_name, prepared: prepared, scope: scope, force: force, dev: dev)
216
- run_installer(installer, failed: "Install") do |manifest|
217
+ run_installer(installer, bundle_name, failed: "Install") do |manifest|
217
218
  print_plugin(manifest)
218
219
  print_provenance(bundle_name, manifest)
219
220
  end
@@ -252,7 +253,7 @@ module Samagotchi
252
253
  @stderr.puts "Bundle '#{bundle_name}' not installed — falling back to install"
253
254
  # (no Plugin line here)
254
255
  installer = installer_for(expanded_source, bundle_name, prepared: prepared, scope: scope, force: force, dry_run: dry_run)
255
- return run_installer(installer, failed: "Install") do |manifest|
256
+ return run_installer(installer, bundle_name, failed: "Install") do |manifest|
256
257
  next dry_run_done if dry_run
257
258
 
258
259
  print_provenance(bundle_name, manifest)
@@ -263,7 +264,7 @@ module Samagotchi
263
264
  # reads which plugin the run touched.
264
265
  before = Samagotchi::MemoryBundle::Provenance.new(name: bundle_name).record
265
266
  manifest = nil
266
- status = run_installer(installer, failed: "Upgrade") do |run_manifest|
267
+ status = run_installer(installer, bundle_name, failed: "Upgrade") do |run_manifest|
267
268
  manifest = run_manifest
268
269
  print_plugin(manifest, plugin: !dry_run)
269
270
  next dry_run_done if dry_run
@@ -326,15 +327,23 @@ module Samagotchi
326
327
  refuse_mismatch: true, **)
327
328
  end
328
329
 
329
- # Runs +installer+, prints its summary, then yields the manifest.
330
- # Ensures the extracted source dir is cleaned up even if an exception
331
- # occurs between installer.run and the block (e.g. summary,
330
+ # Runs +installer+, prints the version line and its summary, then yields
331
+ # the manifest. Ensures the extracted source dir is cleaned up even if an
332
+ # exception occurs between installer.run and the block (e.g. summary,
332
333
  # print_plugin). The block (upgrade_conflicts) still sees
333
334
  # the files because cleanup happens after the block returns or raises.
334
335
  # @return [Integer] the block's exit status, or 1 after "<failed> failed: …"
335
- def run_installer(installer, failed:)
336
+ def run_installer(installer, bundle_name, failed:)
337
+ # The version installed before, read before the run rewrites the record.
338
+ old = Samagotchi::MemoryBundle::Provenance.new(name: bundle_name).record&.version.to_s
336
339
  _nd, manifest = installer.run
337
- @stdout.puts installer.summary
340
+ version = manifest&.version.to_s
341
+ # Current: the same version, and the run wrote nothing.
342
+ current = !version.empty? && old == version && installer.current?
343
+ line = version_line(bundle_name, old, version, current: current)
344
+ @stdout.puts line if line
345
+ summary = installer.summary(current: current)
346
+ @stdout.puts summary unless summary.empty?
338
347
  yield manifest
339
348
  rescue Samagotchi::MemoryBundle::Installer::InstallError => e
340
349
  @stderr.puts "#{failed} failed: #{e.message}"
@@ -343,12 +352,28 @@ module Samagotchi
343
352
  installer.cleanup_source!
344
353
  end
345
354
 
355
+ # The bundle and its version, first in an install's or upgrade's output
356
+ # (a dry run's too: what would be): "mcp 0.8.0 → 0.9.0" when it changes,
357
+ # "mcp 0.9.0" when it doesn't (or for a new install), "mcp 0.9.0 (already
358
+ # current)" when the run wrote nothing either (the summary leaves out its
359
+ # "Up to date" line then). Nil without a manifest version.
360
+ # @param old [String] the installed record's version, "" for none
361
+ # @return [String, nil]
362
+ def version_line(bundle_name, old, version, current:)
363
+ return if version.empty?
364
+ return "#{bundle_name} #{old} → #{version}" unless old.empty? || old == version
365
+
366
+ "#{bundle_name} #{version}#{" (already current)" if current}"
367
+ end
368
+
346
369
  def print_plugin(manifest, plugin: true)
347
370
  return unless plugin && manifest&.plugin
348
371
 
349
372
  # Installed with --force past its requires_chi: the Engine won't load it.
350
373
  failure = Samagotchi::BundleManifest.requires_chi_failure(manifest.requires_chi, Samagotchi::VERSION)
351
- @stdout.puts "Plugin: #{manifest.plugin[:file]} (#{failure ? "won't load on this chi: #{failure}" : "loads at the next chi start"})"
374
+ parts = manifest.plugin_parts.size
375
+ @stdout.puts "Plugin: #{manifest.plugin[:file]}#{" + #{parts} part#{"s" unless parts == 1}" if parts.positive?} " \
376
+ "(#{failure ? "won't load on this chi: #{failure}" : "loads at the next chi start"})"
352
377
  end
353
378
 
354
379
  # @return [Integer] 0
@@ -382,7 +407,7 @@ module Samagotchi
382
407
  def restart_hint(before, manifest = nil, installer = nil)
383
408
  return if before.nil? || before.error?
384
409
 
385
- plugin_files = [before.plugin&.file, manifest&.plugin&.dig(:file)].compact.uniq
410
+ plugin_files = ([before.plugin&.file, *before.plugin&.parts&.keys] + (manifest&.plugin_files || []).map(&:first)).compact.uniq
386
411
  changed = if installer
387
412
  plugin_files.any? { |file| CHANGED_WORDS.include?(installer.results[file]&.word) }
388
413
  else
@@ -590,6 +615,9 @@ module Samagotchi
590
615
  if (plugin = st.plugin)
591
616
  note = PLUGIN_NOTES.fetch(plugin[:state], "")
592
617
  @stdout.puts " Plugin: #{plugin[:file]} [#{plugin[:state]}]#{note}"
618
+ plugin[:parts].reject { |part| part[:state] == "ok" }.each do |part|
619
+ @stdout.puts " part #{part[:file]} [#{part[:state]}]#{PLUGIN_NOTES.fetch(part[:state], "")}"
620
+ end
593
621
  @stdout.puts " requires_chi: #{plugin[:requires_chi]}" if plugin[:requires_chi]
594
622
  @stdout.puts " not loaded: #{plugin[:requires_failure]}" if plugin[:requires_failure]
595
623
  end
@@ -607,7 +635,7 @@ module Samagotchi
607
635
  st = Samagotchi::MemoryBundle::Status.bundle_status(bname)
608
636
  mods = st.files.values.count { |v| v[:behind] || v[:missing] || v[:unreadable] }
609
637
  plugin = st.plugin
610
- mods += 1 if plugin && (plugin[:state] != "ok" || plugin[:requires_failure])
638
+ mods += 1 if plugin && (plugin[:state] != "ok" || plugin[:requires_failure] || plugin[:parts].any? { |part| part[:state] != "ok" })
611
639
  # A rule that is missing or edited doesn't load; a script runs edited.
612
640
  mods += st.rules.values.count { |state| state != "ok" } + st.scripts.values.count("missing")
613
641
  mods += 1 if st.scope_error
@@ -672,13 +700,14 @@ module Samagotchi
672
700
  @stderr.puts "Bundle '#{bname}': #{e.message}"; return 1
673
701
  end
674
702
  plugin_path = prov.plugin_path(record)
675
- plugin_file = plugin_path && File.basename(plugin_path)
703
+ # The plugin's files, its parts first (the load order).
704
+ plugin_files = plugin_path ? [*record.plugin.parts.keys, File.basename(plugin_path)] : []
676
705
  if file_arg
677
706
  # A memory first, then the plugin (an older chi's hook is no file of the bundle's)
678
707
  if record.owns?(file_arg)
679
708
  diff_memory(prov, target_dir, file_arg)
680
- elsif plugin_file && [plugin_file, "plugin/#{plugin_file}"].include?(file_arg)
681
- diff_plugin(prov, record, plugin_path)
709
+ elsif (plugin_file = plugin_files.find { |file| [file, "plugin/#{file}"].include?(file_arg) })
710
+ diff_plugin(prov, record, plugin_file)
682
711
  elsif (asset = asset_states(prov, record).find { |a| a.label == file_arg })
683
712
  diff_asset(asset)
684
713
  else
@@ -691,8 +720,8 @@ module Samagotchi
691
720
  diff_memory(prov, target_dir, key)
692
721
  @stdout.puts ""
693
722
  end
694
- if plugin_file
695
- diff_plugin(prov, record, plugin_path)
723
+ plugin_files.each do |file|
724
+ diff_plugin(prov, record, file)
696
725
  @stdout.puts ""
697
726
  end
698
727
  asset_states(prov, record).select(&:edited?).each do |a|
@@ -747,11 +776,11 @@ module Samagotchi
747
776
  end
748
777
  end
749
778
 
750
- def diff_plugin(prov, record, plugin_path)
751
- file = File.basename(plugin_path)
752
- print_base_and_current("plugin/#{file}", prov.plugin_base_path(file), plugin_path)
779
+ # One file of the plugin (+file+: the plugin file or a part, by name).
780
+ def diff_plugin(prov, record, file)
781
+ print_base_and_current("plugin/#{file}", prov.plugin_base_path(file), File.join(prov.plugin_dir, file))
753
782
  requires_chi = record.manifest.requires_chi
754
- @stdout.puts "--- metadata: sha256=#{record.plugin.sha256}#{" requires_chi=#{requires_chi}" if requires_chi}"
783
+ @stdout.puts "--- metadata: sha256=#{record.plugin_shas[file]}#{" requires_chi=#{requires_chi}" if requires_chi}"
755
784
  end
756
785
 
757
786
  def print_base_and_current(heading, base, current)
@@ -26,6 +26,9 @@ module Samagotchi
26
26
  # sha256: sha256:0a1b...
27
27
  # required: true # optional: a guardrail; when it fails to load
28
28
  # # chi denies every tool call (docs/hooks.md)
29
+ # parts: # optional — more .rb files of the plugin, each
30
+ # client.rb: sha256:… # evaluated in this order before file:, into
31
+ # # the same namespace (#plugin_files)
29
32
  # requires_chi: ">= 0.1.28" # optional — a Gem::Requirement for chi's VERSION
30
33
  # requires_chi_next: true # optional, shipped bundles — ignored here:
31
34
  # # `rake release:bump` raises requires_chi to
@@ -92,6 +95,8 @@ module Samagotchi
92
95
 
93
96
  # A plugin file is a plain .rb name in the bundle's top directory.
94
97
  PLUGIN_FILE = /\A[A-Za-z0-9_][A-Za-z0-9_.-]*\.rb\z/
98
+ # The most plugin parts (plugin: parts:) a manifest may list.
99
+ MAX_PLUGIN_PARTS = 16
95
100
  # A script is a plain file name in the bundle's scripts/.
96
101
  SCRIPT_FILE = /\A[A-Za-z0-9_][A-Za-z0-9_.-]*\z/
97
102
  # A need is a plain executable name: no path, no spaces.
@@ -126,7 +131,8 @@ module Samagotchi
126
131
  "settings.types" => "0.92.0",
127
132
  "settings" => "0.143.0",
128
133
  "block_renderers" => "0.151.0",
129
- "plugin.required" => "0.157.0"
134
+ "plugin.required" => "0.157.0",
135
+ "plugin.parts" => "0.183.0"
130
136
  }.freeze
131
137
 
132
138
  # files: name → "sha256:<hex>" (both forms); file_descriptions: name →
@@ -239,6 +245,32 @@ module Samagotchi
239
245
  sha.delete_prefix("sha256:")
240
246
  end
241
247
 
248
+ # @return [String, nil] a plugin part's sha256 hex, "sha256:" stripped,
249
+ # nil when the manifest gives none (or names no such part)
250
+ def checksum_for_part(name)
251
+ sha = plugin_parts[name.to_s].to_s
252
+ sha.empty? ? nil : sha.delete_prefix("sha256:")
253
+ end
254
+
255
+ # The plugin's parts (plugin: parts:), name => "sha256:<hex>" ("" when
256
+ # not given), in the manifest's order; {} without any.
257
+ def plugin_parts = @plugin&.dig(:parts) || {}
258
+
259
+ # The one wording of a part the manifest lists that the bundle's dir
260
+ # lacks (the install refuses it, chi bundle test/try raise it; callers
261
+ # add their context).
262
+ def self.missing_part(part) = "the manifest names plugin part #{part}, which the bundle doesn't have"
263
+
264
+ # Every file of the plugin with its sha, in load order: the parts as
265
+ # listed, then the plugin file; [] without a plugin. The one list the
266
+ # loader, the installer and chi bundle check walk.
267
+ # @return [Array(Array(String, String))]
268
+ def plugin_files
269
+ return [] unless @plugin
270
+
271
+ plugin_parts.to_a + [[@plugin[:file], @plugin[:sha256].to_s]]
272
+ end
273
+
242
274
  # Why chi +version+ can't load this bundle's plugin, or nil when it can
243
275
  # (or the bundle names no requirement).
244
276
  def self.requires_chi_failure(requirement, version)
@@ -273,6 +305,7 @@ module Samagotchi
273
305
  found["context_providers"] = SINCE["context_providers"] unless @context_providers.empty?
274
306
  found["block_renderers"] = SINCE["block_renderers"] unless @block_renderers.empty?
275
307
  found["plugin.required"] = SINCE["plugin.required"] if @plugin&.dig(:required) && SINCE.key?("plugin.required")
308
+ found["plugin.parts"] = SINCE["plugin.parts"] if @plugin&.dig(:parts) && SINCE.key?("plugin.parts")
276
309
  found["session_settings"] = SINCE["session_settings"] unless @session_settings.empty?
277
310
  found["settings"] = SINCE["settings"] unless @settings.nil?
278
311
  found["files.description"] = SINCE["files.description"] if raw["files"].is_a?(Hash) && raw["files"].values.any?(Hash)
@@ -302,6 +335,8 @@ module Samagotchi
302
335
  sha = plugin[:sha256].to_s
303
336
  manifest["plugin"] = { "file" => plugin[:file].to_s, "sha256" => sha.start_with?("sha256:") ? sha : "sha256:#{sha}" }
304
337
  manifest["plugin"]["required"] = true if plugin[:required]
338
+ parts = plugin[:parts] || {}
339
+ manifest["plugin"]["parts"] = parts.to_h { |part, part_sha| [part.to_s, prefixed_sha(part_sha)] } unless parts.empty?
305
340
  end
306
341
  manifest["requires_chi"] = requires_chi.to_s if requires_chi && !requires_chi.to_s.empty?
307
342
  needs = parse_needs(needs)
@@ -384,6 +419,13 @@ module Samagotchi
384
419
  end
385
420
  end
386
421
 
422
+ # +sha+ with the "sha256:" prefix (as the plugin's is written).
423
+ def self.prefixed_sha(sha)
424
+ sha = sha.to_s
425
+ sha.start_with?("sha256:") ? sha : "sha256:#{sha}"
426
+ end
427
+ private_class_method :prefixed_sha
428
+
387
429
  def self.optional_text(value)
388
430
  text = value.to_s.strip
389
431
  text.empty? ? nil : text
@@ -492,8 +534,9 @@ module Samagotchi
492
534
  end
493
535
  end
494
536
 
495
- # plugin: {file:, sha256:, required:} → {file:, sha256:} (sha "" when
496
- # not given) with required: true when it says so, or nil; a file that
537
+ # plugin: {file:, sha256:, required:, parts:} → {file:, sha256:} (sha ""
538
+ # when not given) with required: true when it says so and parts: {name
539
+ # => sha} (#parse_plugin_parts) when it lists any, or nil; a file that
497
540
  # isn't a plain .rb name, or a required: that isn't true or false, is a
498
541
  # validation error.
499
542
  def parse_plugin(raw)
@@ -510,7 +553,61 @@ module Samagotchi
510
553
  required = raw.key?("required") ? raw["required"] : raw[:required]
511
554
  raise ValidationError, "plugin required: must be true or false, not #{required.inspect}" unless [nil, true, false].include?(required)
512
555
 
513
- required ? { file: file, sha256: sha, required: true } : { file: file, sha256: sha }
556
+ parsed = required ? { file: file, sha256: sha, required: true } : { file: file, sha256: sha }
557
+ parts = parse_plugin_parts(raw.key?("parts") ? raw["parts"] : raw[:parts], file)
558
+ parts.empty? ? parsed : parsed.merge(parts: parts)
559
+ end
560
+
561
+ # plugin: parts: {name => sha256} → the same, in the order listed (never
562
+ # sorted: it is the load order), each sha "sha256:" prefixed ("" kept);
563
+ # {} when absent. A name that isn't a plain .rb file name in the top
564
+ # directory, the plugin file's own name, a name the plugin file or an
565
+ # earlier part has in another case (one file on a case-insensitive disk:
566
+ # Plugin.rb beside plugin.rb), a name listed twice (#duplicate_part) or
567
+ # more than MAX_PLUGIN_PARTS entries is a ValidationError naming it.
568
+ def parse_plugin_parts(raw, plugin_file)
569
+ return {} if raw.nil?
570
+ raise ValidationError, "plugin parts: must be a mapping of file names to sha256" unless raw.is_a?(Hash)
571
+ if raw.size > MAX_PLUGIN_PARTS
572
+ raise ValidationError, "plugin parts: lists #{raw.size} files, at most #{MAX_PLUGIN_PARTS}"
573
+ end
574
+
575
+ twice = duplicate_part
576
+ raise ValidationError, "plugin parts: #{twice} is listed twice" if twice
577
+
578
+ raw.each_with_object({}) do |(name, sha), parts|
579
+ name = name.to_s.strip
580
+ unless name.match?(PLUGIN_FILE)
581
+ raise ValidationError, "plugin parts: #{name.inspect} isn't a .rb file name in the bundle's top directory"
582
+ end
583
+ raise ValidationError, "plugin parts: #{name} is the plugin file itself" if name == plugin_file
584
+
585
+ twin = [plugin_file, *parts.keys].find { |other| other.casecmp?(name) }
586
+ raise ValidationError, "plugin parts: #{name} and #{twin} differ only in case (one file on a case-insensitive disk)" if twin
587
+
588
+ sha = sha.to_s.strip
589
+ parts[name] = sha.empty? || sha.start_with?("sha256:") ? sha : "sha256:#{sha}"
590
+ end
591
+ end
592
+
593
+ # The first part name manifest.yml's plugin: parts: mapping lists twice,
594
+ # or nil. YAML.load keeps the last of two equal keys silently, so this
595
+ # reads the file's node tree (only for a manifest that has parts).
596
+ def duplicate_part
597
+ return nil unless @path && File.file?(@path)
598
+
599
+ parts = yaml_value(yaml_value(Psych.parse_file(@path)&.root, "plugin"), "parts")
600
+ return nil unless parts.is_a?(Psych::Nodes::Mapping)
601
+
602
+ keys = parts.children.each_slice(2).map { |key, _| key.respond_to?(:value) ? key.value.to_s.strip : nil }.compact
603
+ keys.find { |key| keys.count(key) > 1 }
604
+ end
605
+
606
+ # A YAML mapping node's value node under the scalar +key+, or nil.
607
+ def yaml_value(node, key)
608
+ return nil unless node.is_a?(Psych::Nodes::Mapping)
609
+
610
+ node.children.each_slice(2).find { |k, _| k.is_a?(Psych::Nodes::Scalar) && k.value == key }&.last
514
611
  end
515
612
 
516
613
  # scripts: {file => sha256} → the same, "sha256:" prefixed; {} when absent.
@@ -1,10 +1,10 @@
1
1
  ---
2
2
  name: dev
3
- version: 0.7.8
3
+ version: 0.7.9
4
4
  scope: system
5
5
  description: "Developer tools"
6
6
  trust_level: reviewed
7
- requires_chi: ">= 0.155.0"
7
+ requires_chi: ">= 0.183.0"
8
8
  includes:
9
9
  - known-names
10
10
  - mcp
@@ -0,0 +1,260 @@
1
+ # frozen_string_literal: true
2
+
3
+ # The mcp bundle's first plugin part (manifest.yml plugin: parts:, loaded
4
+ # before http_client.rb and plugin.rb): the stdio JSON-RPC client and the
5
+ # error classes HttpClient's subclass. The constants it reads at run time
6
+ # (PROTOCOL_VERSION) are plugin.rb's.
7
+ require "json"
8
+ require "open3"
9
+ require "samagotchi/process_group"
10
+
11
+ class Plugin
12
+ # A JSON-RPC client for one MCP server over stdio: newline-delimited JSON
13
+ # on the process's stdin and stdout; stderr goes to the log.
14
+ class Client
15
+ # The request failed: an error answer, a timeout, or the server is gone.
16
+ class Error < StandardError; end
17
+ class Timeout < Error; end
18
+ class Cancelled < Error; end
19
+ # The server's process ended (or never started); an HTTP server that
20
+ # can't be reached.
21
+ class Dead < Error; end
22
+ # An HTTP server's answer isn't MCP's (a status, a content type).
23
+ class Unavailable < Error; end
24
+
25
+ POLL_SECONDS = 0.1
26
+ # How long close waits for the server after closing its stdin, after
27
+ # TERM, and after KILL.
28
+ STOP_GRACE_SECONDS = 1
29
+ # The server's watchdog (#start_watchdog), a shell in its process group
30
+ # whose stdin is a pipe only chi holds. A line on it (#close) lets it
31
+ # go; EOF means chi ended without closing the server (kill -9, a crash
32
+ # past Ruby), whose stdin then hit EOF too: a grace for the server to
33
+ # leave by itself, then TERM and KILL to the group, the way #close stops
34
+ # it. `kill 0` signals the shell's own group: while it runs, that group
35
+ # (and so its id) can't be anyone else's.
36
+ WATCHDOG = "trap '' TERM; read -r _ && exit 0; sleep #{STOP_GRACE_SECONDS}; " \
37
+ "kill -TERM 0; sleep #{STOP_GRACE_SECONDS}; kill -KILL 0".freeze
38
+
39
+ attr_reader :pid
40
+
41
+ # @param command [Array<String>]
42
+ # @param env [Hash] added to the environment
43
+ # @param cwd [String]
44
+ # @param log [#call] (event, fields) for stderr lines and protocol noise
45
+ # @param on_exit [#call, nil] called once, with the reason, when the
46
+ # process ends while the client is open
47
+ # @param on_notification [#call, nil] (method, params) for each
48
+ # notification from the server, on the reader thread: it must not
49
+ # wait for an answer there
50
+ def initialize(command, env: {}, cwd: Dir.pwd, log: ->(*) {}, on_exit: nil, on_notification: nil)
51
+ @log = log
52
+ @on_exit = on_exit
53
+ @on_notification = on_notification
54
+ @mutex = Mutex.new
55
+ @write_mutex = Mutex.new
56
+ @pending = {}
57
+ @next_id = 0
58
+ @dead = nil
59
+ @closing = false
60
+ @stdin, @stdout, @stderr, @wait = Open3.popen3(env.to_h { |k, v| [k.to_s, v&.to_s] }, *command,
61
+ chdir: cwd, pgroup: true)
62
+ @pid = @wait.pid
63
+ start_watchdog
64
+ @reader = Thread.new { read_loop }
65
+ @err_reader = Thread.new { stderr_loop }
66
+ rescue SystemCallError => e
67
+ raise Dead, "can't start #{command.first}: #{e.message.sub(/ - .*\z/m, "")}"
68
+ end
69
+
70
+ # @return [String, nil] why the server is gone, or nil while it runs
71
+ def dead = @mutex.synchronize { @dead }
72
+
73
+ # What /mcp's running line shows for it.
74
+ def label = "pid #{pid}"
75
+
76
+ # initialize, then notifications/initialized.
77
+ # @return [Hash] initialize's result
78
+ def handshake(timeout:, cancelled:)
79
+ result = request("initialize", { protocolVersion: PROTOCOL_VERSION, capabilities: {},
80
+ clientInfo: { name: "chi", version: Samagotchi::VERSION } },
81
+ timeout: timeout, cancelled: cancelled)
82
+ notify("notifications/initialized")
83
+ result
84
+ end
85
+
86
+ # Send a request and wait for its answer.
87
+ # @param cancelled [#call, nil] polled while waiting; true sends
88
+ # notifications/cancelled and raises Cancelled
89
+ # @return [Hash] the result
90
+ def request(method, params = nil, timeout:, cancelled: nil)
91
+ queue = Queue.new
92
+ id = @mutex.synchronize do
93
+ raise Dead, @dead if @dead
94
+
95
+ @next_id += 1
96
+ @pending[@next_id] = queue
97
+ @next_id
98
+ end
99
+ write({ jsonrpc: "2.0", id: id, method: method, params: params }.compact)
100
+ deadline = monotonic + timeout
101
+ loop do
102
+ left = deadline - monotonic
103
+ if left <= 0
104
+ cancel(id, "timed out")
105
+ raise Timeout, "#{method} timed out after #{format("%g", timeout)}s"
106
+ end
107
+ if cancelled&.call
108
+ cancel(id, "cancelled by the user")
109
+ raise Cancelled, "#{method} was cancelled"
110
+ end
111
+ message = queue.pop(timeout: [left, POLL_SECONDS].min)
112
+ next unless message
113
+ raise Dead, message[:dead] if message[:dead]
114
+ if (error = message["error"])
115
+ raise Error, "#{error["message"] || "error"} (#{error["code"]})"
116
+ end
117
+
118
+ return message["result"] || {}
119
+ end
120
+ ensure
121
+ @mutex.synchronize { @pending.delete(id) } if id
122
+ end
123
+
124
+ def notify(method, params = nil)
125
+ write({ jsonrpc: "2.0", method: method, params: params }.compact)
126
+ end
127
+
128
+ # End the process: stdin closed first (most servers leave then), then
129
+ # TERM and KILL to its process group (chi's ProcessGroup), a second's
130
+ # grace each. Then the watchdog is let go.
131
+ def close
132
+ @mutex.synchronize { @closing = true }
133
+ [@stdin].each { |io| io.close unless io.closed? }
134
+ unless @wait.join(STOP_GRACE_SECONDS)
135
+ Samagotchi::ProcessGroup.stop(@pid, grace: STOP_GRACE_SECONDS, poll: STOP_GRACE_SECONDS,
136
+ stopped: -> { !@wait.alive? }, wait: ->(seconds) { @wait.join(seconds) })
137
+ @wait.join(STOP_GRACE_SECONDS)
138
+ end
139
+ release_watchdog
140
+ [@stdout, @stderr].each { |io| io.close unless io.closed? }
141
+ [@reader, @err_reader].each { |t| t.join(1) }
142
+ nil
143
+ rescue IOError
144
+ nil
145
+ end
146
+
147
+ private
148
+
149
+ # A server outlives a chi killed without #close when it ignores its
150
+ # stdin's EOF (a Node server with another live handle does): the
151
+ # watchdog (WATCHDOG) stops its group then. One that can't start (the
152
+ # server already left its group) is logged and skipped.
153
+ def start_watchdog
154
+ reader, @watchdog_pipe = IO.pipe
155
+ watchdog = Process.spawn("/bin/sh", "-c", WATCHDOG, in: reader, out: File::NULL, err: File::NULL, pgroup: @pid)
156
+ @watchdog = Process.detach(watchdog)
157
+ rescue SystemCallError => e
158
+ @log.call("watchdog_failed", error: e.class.name)
159
+ @watchdog_pipe&.close
160
+ @watchdog_pipe = nil
161
+ ensure
162
+ reader&.close
163
+ end
164
+
165
+ # A line tells the watchdog chi stopped the server itself.
166
+ def release_watchdog
167
+ return unless @watchdog_pipe
168
+
169
+ begin
170
+ @watchdog_pipe.write("\n")
171
+ rescue IOError, SystemCallError # gone already: the group's KILL reached it
172
+ nil
173
+ end
174
+ @watchdog_pipe.close unless @watchdog_pipe.closed?
175
+ @watchdog&.join(STOP_GRACE_SECONDS)
176
+ end
177
+
178
+ def write(message)
179
+ line = JSON.generate(message)
180
+ @write_mutex.synchronize do
181
+ @stdin.write(line, "\n")
182
+ @stdin.flush
183
+ end
184
+ rescue IOError, SystemCallError => e
185
+ raise Dead, dead || "the server's stdin is closed (#{e.class})"
186
+ end
187
+
188
+ def cancel(id, reason)
189
+ notify("notifications/cancelled", { requestId: id, reason: reason })
190
+ rescue Dead
191
+ nil
192
+ end
193
+
194
+ def read_loop
195
+ @stdout.each_line do |line|
196
+ next if line.strip.empty?
197
+
198
+ message = begin
199
+ JSON.parse(line)
200
+ rescue JSON::ParserError
201
+ @log.call("bad_line", line: line[0, 200])
202
+ next
203
+ end
204
+ dispatch(message) if message.is_a?(Hash)
205
+ end
206
+ rescue IOError
207
+ nil
208
+ ensure
209
+ ended
210
+ end
211
+
212
+ def dispatch(message)
213
+ if message.key?("method")
214
+ # A request from the server (ping, roots/list, …): ping is answered,
215
+ # the rest aren't supported. A notification is logged and handed on.
216
+ unless message.key?("id")
217
+ @log.call("server_notification", method: message["method"])
218
+ return @on_notification&.call(message["method"], message["params"])
219
+ end
220
+
221
+ answer = if message["method"] == "ping"
222
+ { jsonrpc: "2.0", id: message["id"], result: {} }
223
+ else
224
+ { jsonrpc: "2.0", id: message["id"], error: { code: -32_601, message: "not supported by chi" } }
225
+ end
226
+ begin
227
+ write(answer)
228
+ rescue Dead
229
+ nil
230
+ end
231
+ else
232
+ queue = @mutex.synchronize { @pending[message["id"]] }
233
+ queue&.push(message)
234
+ end
235
+ end
236
+
237
+ def stderr_loop
238
+ @stderr.each_line { |line| @log.call("stderr", line: line.chomp[0, 500]) }
239
+ rescue IOError
240
+ nil
241
+ end
242
+
243
+ def ended
244
+ status = @wait.value
245
+ reason = if status.nil?
246
+ "the server exited"
247
+ else
248
+ "the server exited (#{status.exitstatus ? "status #{status.exitstatus}" : "signal #{status.termsig}"})"
249
+ end
250
+ waiting, closing = @mutex.synchronize do
251
+ @dead ||= reason
252
+ [@pending.values, @closing]
253
+ end
254
+ waiting.each { |queue| queue.push({ dead: reason }) }
255
+ @on_exit&.call(reason) unless closing
256
+ end
257
+
258
+ def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
259
+ end
260
+ end