samagotchi 0.156.0 → 0.157.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 +44 -1
  3. data/bin/chi +1 -0
  4. data/docs/architecture.md +12 -7
  5. data/docs/bundles.md +3 -1
  6. data/docs/cli.md +9 -8
  7. data/docs/configuration.md +36 -4
  8. data/docs/guardrails.md +9 -5
  9. data/docs/hooks.md +11 -5
  10. data/docs/internals/bridge.md +83 -6
  11. data/docs/internals/bundles.md +28 -18
  12. data/docs/internals/context-telemetry.md +4 -3
  13. data/docs/internals/engine.md +16 -2
  14. data/docs/internals/participants.md +3 -2
  15. data/docs/internals/remote-sessions.md +5 -2
  16. data/docs/internals/web-frontend.md +3 -2
  17. data/docs/internals/working-set.md +1 -1
  18. data/docs/memory.md +13 -2
  19. data/docs/plugins.md +35 -2
  20. data/docs/sessions.md +9 -9
  21. data/docs/sub-agent.md +17 -2
  22. data/docs/testing.md +53 -2
  23. data/lib/samagotchi/answer_command.rb +2 -1
  24. data/lib/samagotchi/archive_store.rb +4 -3
  25. data/lib/samagotchi/bootstrap_command.rb +3 -2
  26. data/lib/samagotchi/bridge/card_places.rb +10 -4
  27. data/lib/samagotchi/bridge/card_store.rb +3 -0
  28. data/lib/samagotchi/bridge/turn_accumulator.rb +109 -9
  29. data/lib/samagotchi/bridge/turn_drawings.rb +265 -0
  30. data/lib/samagotchi/bridge.rb +31 -6
  31. data/lib/samagotchi/broadcast/recipients.rb +8 -8
  32. data/lib/samagotchi/broadcast/triage_model.rb +1 -1
  33. data/lib/samagotchi/bundle_command/check.rb +18 -0
  34. data/lib/samagotchi/bundle_command/try/sandbox.rb +1 -1
  35. data/lib/samagotchi/bundle_command/try/trace.rb +1 -1
  36. data/lib/samagotchi/bundle_command.rb +5 -2
  37. data/lib/samagotchi/bundles/known-names/manifest.yml +4 -7
  38. data/lib/samagotchi/bundles/known-names/{hooks/known_names.rb → plugin.rb} +17 -0
  39. data/lib/samagotchi/bundles/source-links/manifest.yml +4 -7
  40. data/lib/samagotchi/bundles/source-links/{hooks/source_links.rb → plugin.rb} +23 -4
  41. data/lib/samagotchi/bundles/system/manifest.yml +2 -2
  42. data/lib/samagotchi/bundles/system/memory_guide.md +1 -1
  43. data/lib/samagotchi/child_move.rb +6 -6
  44. data/lib/samagotchi/child_reports.rb +2 -2
  45. data/lib/samagotchi/children_status.rb +15 -21
  46. data/lib/samagotchi/cli/parent_wait.rb +8 -22
  47. data/lib/samagotchi/config.rb +3 -0
  48. data/lib/samagotchi/context_sources.rb +5 -4
  49. data/lib/samagotchi/context_window.rb +9 -12
  50. data/lib/samagotchi/effective_model.rb +57 -22
  51. data/lib/samagotchi/engine/plugins.rb +1 -1
  52. data/lib/samagotchi/engine/recap.rb +8 -4
  53. data/lib/samagotchi/engine.rb +29 -3
  54. data/lib/samagotchi/events.rb +3 -2
  55. data/lib/samagotchi/extension_load.rb +6 -3
  56. data/lib/samagotchi/guardrails_command.rb +1 -1
  57. data/lib/samagotchi/host_address.rb +52 -0
  58. data/lib/samagotchi/host_registry.rb +57 -45
  59. data/lib/samagotchi/kernel_loop.rb +7 -3
  60. data/lib/samagotchi/llm/chat_loop.rb +6 -3
  61. data/lib/samagotchi/llm_context_strategy.rb +27 -63
  62. data/lib/samagotchi/memory_bundle/asset_installer.rb +71 -76
  63. data/lib/samagotchi/memory_bundle/builder.rb +2 -1
  64. data/lib/samagotchi/memory_bundle/file_actions.rb +193 -0
  65. data/lib/samagotchi/memory_bundle/file_digest.rb +13 -0
  66. data/lib/samagotchi/memory_bundle/file_state.rb +152 -0
  67. data/lib/samagotchi/memory_bundle/installed_copy.rb +2 -1
  68. data/lib/samagotchi/memory_bundle/installed_manifest.rb +8 -1
  69. data/lib/samagotchi/memory_bundle/installer.rb +185 -169
  70. data/lib/samagotchi/memory_bundle/manifest.rb +14 -4
  71. data/lib/samagotchi/memory_bundle/merger.rb +69 -65
  72. data/lib/samagotchi/memory_bundle/plugin_ref.rb +6 -5
  73. data/lib/samagotchi/memory_bundle/profile.rb +5 -5
  74. data/lib/samagotchi/memory_bundle/provenance.rb +15 -1
  75. data/lib/samagotchi/memory_bundle/remerge.rb +25 -12
  76. data/lib/samagotchi/memory_bundle/shipped_update.rb +51 -6
  77. data/lib/samagotchi/memory_bundle/status.rb +14 -20
  78. data/lib/samagotchi/memory_bundle/system_bundle.rb +24 -6
  79. data/lib/samagotchi/memory_bundle/trash.rb +23 -8
  80. data/lib/samagotchi/memory_bundle/uninstaller.rb +16 -11
  81. data/lib/samagotchi/memory_usage.rb +1 -1
  82. data/lib/samagotchi/model_lookup.rb +75 -0
  83. data/lib/samagotchi/model_profile.rb +1 -0
  84. data/lib/samagotchi/models_command.rb +1 -1
  85. data/lib/samagotchi/note_command.rb +1 -1
  86. data/lib/samagotchi/participant_mode.rb +2 -1
  87. data/lib/samagotchi/plugin/api.rb +41 -6
  88. data/lib/samagotchi/plugin/loader.rb +33 -10
  89. data/lib/samagotchi/plugin/sessions.rb +1 -1
  90. data/lib/samagotchi/reasoning_history.rb +14 -20
  91. data/lib/samagotchi/recap_place.rb +27 -0
  92. data/lib/samagotchi/reply_wait/liveness.rb +38 -0
  93. data/lib/samagotchi/reply_wait/poll.rb +44 -15
  94. data/lib/samagotchi/reply_wait/target.rb +113 -0
  95. data/lib/samagotchi/reply_wait.rb +22 -2
  96. data/lib/samagotchi/sampling_settings.rb +9 -16
  97. data/lib/samagotchi/self_report.rb +34 -35
  98. data/lib/samagotchi/send_command.rb +17 -23
  99. data/lib/samagotchi/session.rb +321 -439
  100. data/lib/samagotchi/session_access/local.rb +5 -6
  101. data/lib/samagotchi/session_access/remote.rb +5 -3
  102. data/lib/samagotchi/session_field.rb +133 -0
  103. data/lib/samagotchi/session_inbox.rb +49 -1
  104. data/lib/samagotchi/session_manager/emptiness.rb +2 -1
  105. data/lib/samagotchi/session_manager/listing.rb +29 -100
  106. data/lib/samagotchi/session_manager.rb +2 -1
  107. data/lib/samagotchi/session_metrics.rb +7 -4
  108. data/lib/samagotchi/session_paths.rb +57 -0
  109. data/lib/samagotchi/session_retention.rb +2 -2
  110. data/lib/samagotchi/session_row.rb +200 -0
  111. data/lib/samagotchi/session_setup.rb +15 -12
  112. data/lib/samagotchi/sessions_command.rb +11 -129
  113. data/lib/samagotchi/steer_cut_after.rb +7 -14
  114. data/lib/samagotchi/terminal_ui/attached_loop.rb +6 -26
  115. data/lib/samagotchi/terminal_ui/join_replay.rb +86 -8
  116. data/lib/samagotchi/terminal_ui/local_link.rb +2 -2
  117. data/lib/samagotchi/terminal_ui.rb +3 -1
  118. data/lib/samagotchi/testing/install.rb +2 -1
  119. data/lib/samagotchi/thinking.rb +16 -21
  120. data/lib/samagotchi/tool_response.rb +5 -3
  121. data/lib/samagotchi/tool_runner.rb +18 -1
  122. data/lib/samagotchi/tools/delegate.rb +48 -43
  123. data/lib/samagotchi/tools/delegate_relay.rb +5 -5
  124. data/lib/samagotchi/tools/delegate_result.rb +1 -1
  125. data/lib/samagotchi/tools/delegate_wait.rb +41 -17
  126. data/lib/samagotchi/tools/list_sessions.rb +7 -7
  127. data/lib/samagotchi/update_command.rb +11 -7
  128. data/lib/samagotchi/verify_fresh.rb +7 -11
  129. data/lib/samagotchi/version.rb +1 -1
  130. data/lib/samagotchi/vision_support.rb +11 -14
  131. data/lib/samagotchi/web/app.rb +31 -21
  132. data/lib/samagotchi/web/message_display.rb +57 -7
  133. data/lib/samagotchi/web/participant_access.rb +1 -1
  134. data/lib/samagotchi/web/public/activity.js +16 -7
  135. data/lib/samagotchi/web/public/app.js +29 -8
  136. data/lib/samagotchi/web/public/bubbles.js +8 -3
  137. data/lib/samagotchi/web/public/cards_place.js +15 -0
  138. data/lib/samagotchi/web/public/commands.js +5 -1
  139. data/lib/samagotchi/web/public/data.js +4 -2
  140. data/lib/samagotchi/web/public/history_shape.js +220 -0
  141. data/lib/samagotchi/web/public/recap_stamp.js +17 -0
  142. data/lib/samagotchi/web/public/reload_check.js +71 -0
  143. data/lib/samagotchi/web/public/stage_model.js +7 -5
  144. data/lib/samagotchi/web/public/stage_view.js +7 -3
  145. data/lib/samagotchi/web/public/stream_handlers.js +8 -2
  146. data/lib/samagotchi/web/public/timing.js +43 -2
  147. data/lib/samagotchi/web/public/turn_block.js +215 -30
  148. data/lib/samagotchi/web/public/turn_drawing.js +43 -0
  149. data/lib/samagotchi/web/public/turn_events.js +10 -1
  150. data/lib/samagotchi/web/public/turn_pieces.js +29 -0
  151. data/lib/samagotchi/web/reload_check_route.rb +95 -0
  152. data/lib/samagotchi/web/server.rb +4 -2
  153. data/lib/samagotchi/web/session_access_routes.rb +3 -3
  154. data/lib/samagotchi/web/session_control.rb +1 -1
  155. data/lib/samagotchi/web/session_hub.rb +9 -17
  156. data/lib/samagotchi/web/session_show.rb +64 -2
  157. data/lib/samagotchi/web/session_summary.rb +36 -24
  158. data/lib/samagotchi/worker.rb +28 -5
  159. data/lib/samagotchi/worker_link.rb +3 -0
  160. metadata +20 -4
  161. data/lib/samagotchi/send_command/wait_target.rb +0 -85
@@ -4,8 +4,8 @@ require "fileutils"
4
4
  require "digest"
5
5
  require_relative "../memory_paths"
6
6
  require_relative "provenance"
7
+ require_relative "file_actions"
7
8
  require_relative "index_updater"
8
- require_relative "merger"
9
9
  require_relative "trash"
10
10
  require_relative "../model_overlay"
11
11
 
@@ -64,17 +64,22 @@ module Samagotchi
64
64
  [key, Provenance.claimants(key, scope: target_scope, except: @name)]
65
65
  end.reject { |_, others| others.empty? }
66
66
 
67
+ # Each file's UNINSTALL row (its source-less FileState): an edit
68
+ # refuses, unless --force (which moves it to the trash with the rest).
67
69
  blocked = []
68
- files.each do |file_key, _meta|
69
- file_key_str = file_key.to_s
70
- target_path = File.join(target_dir, file_key_str)
71
- base_path = provenance.base_path(file_key_str)
72
- next unless File.exist?(target_path)
73
- next if shared.key?(file_key_str)
74
-
75
- if !@force && File.exist?(base_path) && Merger.current_modified?(base_path, target_path)
76
- blocked << file_key_str
77
- @warnings << "Skipped #{file_key_str}: local edits detected (#{FileStanding::FORCE_MOVES})"
70
+ unless @force
71
+ files.each_key do |file_key|
72
+ key = file_key.to_s
73
+ state = FileState.of(key, record: bundle, provenance: provenance, target_dir: target_dir, source_dir: nil,
74
+ claimants: ->(k) { shared.fetch(k, []) })
75
+ next unless FileActions.for(:uninstall, state)&.do == :refuse
76
+ # Kept for another bundle, read or not.
77
+ next if state.shared_with.any?
78
+
79
+ # Whether it was edited can't be told: the read raises (nothing lost).
80
+ FileDigest.hex(state.paths[:current]) if state.kind == :unreadable
81
+ blocked << key
82
+ @warnings << "Skipped #{key}: local edits detected (#{FileStanding::FORCE_MOVES})"
78
83
  end
79
84
  end
80
85
 
@@ -89,7 +89,7 @@ module Samagotchi
89
89
  def self.load_sessions(state_dir: Session.default_state_dir)
90
90
  sessions = []
91
91
  unreadable = 0
92
- Dir.glob(File.join(state_dir, "*#{Session::FILE_EXT}")).sort.each do |path|
92
+ Dir.glob(File.join(state_dir, "*#{SessionPaths::FILE_EXT}")).sort.each do |path|
93
93
  data = JSON.parse(File.read(path, encoding: "UTF-8"))
94
94
  # A project_root that is not a path (a hand-edited file) makes every
95
95
  # later step raise, so the file counts as unreadable rather than
@@ -0,0 +1,75 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "config"
4
+
5
+ module Samagotchi
6
+ # The layered inputs a model's settings resolve from, in one value: the
7
+ # target (its host entry: the hosts: layer), the names its models: entry
8
+ # may be under (HostRegistry#lookup_names, most specific first), the
9
+ # models: map, and the env the CLI/env/file layers are read with.
10
+ # EffectiveModel builds one per read (with its registry's env); each
11
+ # setting module (Thinking, ReasoningHistory, SteerCutAfter,
12
+ # SamplingSettings, VisionSupport, ContextWindow, LLMContextStrategy) keeps
13
+ # its own ordered resolve over it, and ModelProfile takes its #models.
14
+ #
15
+ # The setting modules call it duck-typed and never name it, and it names
16
+ # none of them (only ModelSettings, ModelSetting, Config, ConfigFile): the
17
+ # modules' parsers are what ModelSettings calls, so either edge would close
18
+ # a cycle (spec/model_lookup_spec.rb checks this file's side).
19
+ #
20
+ # +given_models+ is a caller's models: map (one for a whole picker, or a
21
+ # spec's); without one, #models reads config.yml at each call, as every
22
+ # resolve always did.
23
+ ModelLookup = Data.define(:target, :names, :given_models, :env) do
24
+ # @param target [HostRegistry::ModelTarget, nil] nil: the global layers only
25
+ # @param names [Array<String>] HostRegistry#lookup_names
26
+ # @param models [Hash{String => ModelSettings}, nil] ModelSettings.all by default
27
+ # @param env [Hash] ENV, or another env whose config file and variables
28
+ # every layer reads (chi self's)
29
+ def self.for(target, names:, models: nil, env: ENV)
30
+ new(target: target, names: Array(names), given_models: models, env: env)
31
+ end
32
+
33
+ # The models: map: the one given, else ModelSettings.all for #env; {}
34
+ # when it can't be read.
35
+ # @return [Hash{String => ModelSettings}]
36
+ def models
37
+ return given_models if given_models
38
+
39
+ env.equal?(ENV) ? ModelSettings.all : ModelSettings.all(env: env)
40
+ rescue StandardError # degrade-ok: the setting resolves from its other layers, as it always did
41
+ {}
42
+ end
43
+
44
+ def entry = target&.entry
45
+
46
+ # The host's name, as a "hosts.NAME" label names it.
47
+ def host_name = entry&.name
48
+
49
+ # The first lookup name whose models: entry sets +field+ (a
50
+ # ModelSettings member): a ModelSetting (key, value), or nil.
51
+ # @return [ModelSetting, nil]
52
+ def model(field) = ModelSettings.find(names, field, models: models)
53
+
54
+ # The host entry's +field+ (a HostEntry member), nil when unset or
55
+ # without a host.
56
+ def host(field) = entry&.public_send(field)
57
+
58
+ # [value, origin] of the global config key +key+ (:cli, :env, :file or
59
+ # :default), as Config.get_with_origin gives it; for another env its
60
+ # variables and config file, with this process's CLI settings. Raises as
61
+ # that does.
62
+ # @return [Array(Object, Symbol)]
63
+ def global(key)
64
+ return Config.get_with_origin(key) if env.equal?(ENV)
65
+
66
+ file_data = ConfigFile.read_yaml(env: env, path: ConfigFile.global_path(env: env))
67
+ Config.resolve_with_origin(key, file_data: file_data, env: env, cli_overrides: Config.cli_overrides)
68
+ end
69
+
70
+ # The model and the names only: the default would print the env (it
71
+ # holds API keys) and the target's client.
72
+ def inspect = "#<Samagotchi::ModelLookup #{target&.model.inspect} host=#{host_name.inspect} names=#{names.inspect}>"
73
+ alias_method :to_s, :inspect
74
+ end
75
+ end
@@ -286,6 +286,7 @@ module Samagotchi
286
286
  def self.default_relist(hosts)
287
287
  lambda do |host_name, relist_env|
288
288
  require_relative "host_registry"
289
+ # Not .current: the caller's hosts, and a fresh listing is the point.
289
290
  registry = Samagotchi::HostRegistry.new(hosts_config: hosts, env: relist_env)
290
291
  answer = nil
291
292
  thread = Thread.new { answer = registry.list_models(host_name) }
@@ -73,7 +73,7 @@ module Samagotchi
73
73
 
74
74
  # @return [Array(Hash, Boolean)] the payload and whether any host listed
75
75
  def catalog(timeout)
76
- registry = @registry || HostRegistry.new
76
+ registry = @registry || HostRegistry.current
77
77
  results = registry.list_all_models(force: true, wait: timeout)
78
78
  listed = results.values.any? { |data| data.error.nil? }
79
79
  [ModelCatalog.payload(results, registry: registry, default_name: default_name), listed]
@@ -97,7 +97,7 @@ module Samagotchi
97
97
 
98
98
  # --all: every live session. @return [Integer] exit status
99
99
  def deliver_to_live(text, source)
100
- ids = @access.summaries(live: true, include_tests: Session.test_session_env?).map { |s| s[:id] }
100
+ ids = @access.summaries(live: true, include_tests: Session.test_session_env?).map(&:id)
101
101
  if ids.empty?
102
102
  error_line("chi note: no live sessions (chi sessions list --live --scope=all)")
103
103
  return 1
@@ -1,6 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require_relative "delivery"
4
+ require_relative "session_paths"
4
5
 
5
6
  module Samagotchi
6
7
  # The rules for a participant's turn: the one place that decides them.
@@ -75,7 +76,7 @@ module Samagotchi
75
76
 
76
77
  require_relative "session"
77
78
  require_relative "worker_link"
78
- dir = Session.session_dir(session.id, state_dir: state_dir || Session.default_state_dir)
79
+ dir = SessionPaths.session_dir(session.id, state_dir: state_dir || SessionPaths.default_state_dir)
79
80
  link = WorkerLink.resolve(dir, unlink: false)
80
81
  link.live? ? link.features : nil
81
82
  rescue StandardError
@@ -57,9 +57,14 @@ module Samagotchi
57
57
  "ctx.continues" => "0.141.0", "ctx.context.left_behind" => "0.141.0", "ctx.context.attach(movable:)" => "0.141.0",
58
58
  "ctx.session_dir" => "0.143.0", "ctx.session_dir(create:)" => "0.144.0",
59
59
  "ctx.objectives" => "0.149.0", "ctx.turn_running?" => "0.149.0",
60
- "ctx.last_answer" => "0.154.0"
60
+ "ctx.last_answer" => "0.154.0",
61
+ "chi.on(on_error:)" => "0.157.0"
61
62
  }.freeze
62
63
 
64
+ # chi.on's on_error: values. :log (the default) logs a raise and goes
65
+ # on; :fail_closed (before_tool_call only) denies the call it raised on.
66
+ ON_ERROR = %i[log fail_closed].freeze
67
+
63
68
  # @param bundle [String]
64
69
  # @param label [String] "<file> (bundle <name>)": what hooks and
65
70
  # failures are named by
@@ -222,14 +227,31 @@ module Samagotchi
222
227
  # logged and skipped; its first failure in this worker also tells the
223
228
  # user, once (Registries#hook_failed).
224
229
  # @param priority [Integer] lower runs first among bundle hooks
225
- def on(event, priority: 100, &block)
230
+ # @param on_error [Symbol] :log, or :fail_closed for a before_tool_call
231
+ # guard: a raise denies that call. A plugin that registers one is a
232
+ # guardrail (#fail_closed?): if it then fails to load, every tool call
233
+ # is denied (Loader; the manifest's plugin: required: true says so
234
+ # before it registers anything).
235
+ def on(event, priority: 100, on_error: :log, &block)
226
236
  raise ArgumentError, "on(#{event.inspect}) needs a block" unless block
227
237
  raise ArgumentError, "on: the event must be a Symbol or String" unless event.is_a?(Symbol) || event.is_a?(String)
228
238
 
229
- @hooks << { event: event.to_sym, priority: Integer(priority), block: block }
239
+ event = event.to_sym
240
+ policy = on_error.is_a?(String) ? on_error.to_sym : on_error
241
+ raise ArgumentError, "on(#{event.inspect}): on_error: must be :log or :fail_closed, not #{on_error.inspect}" unless ON_ERROR.include?(policy)
242
+ if policy == :fail_closed && event != :before_tool_call
243
+ raise ArgumentError, "on(#{event.inspect}): on_error: :fail_closed is for :before_tool_call only"
244
+ end
245
+
246
+ @hooks << { event: event, priority: Integer(priority), on_error: policy, block: block }
230
247
  nil
231
248
  end
232
249
 
250
+ # Whether #register staged a fail-closed hook (chi.on(on_error:
251
+ # :fail_closed)): the plugin is a guardrail, so its failing to load
252
+ # denies every tool call (Loader).
253
+ def fail_closed? = @hooks.any? { |hook| hook[:on_error] == :fail_closed }
254
+
233
255
  # A long-lived thing the plugin keeps (a server process): the block
234
256
  # starts it and returns what #value gives; in it, svc.on_stop { }
235
257
  # says how to stop it. It starts on first svc.value, or now with
@@ -451,10 +473,13 @@ module Samagotchi
451
473
  @tools.each { |tool| @registries.tools.register(tool.name, source: @bundle, **tool.entry_fields(context)) }
452
474
  @hooks.each do |hook|
453
475
  block = hook[:block]
454
- # Never stderr (echo: false): a turn's live region is on screen.
455
- handler = Hooks.wrap(label: "#{@label} #{hook[:event]} hook", event: hook[:event], policy: :log,
476
+ # Never stderr (echo: false): a turn's live region is on screen. A
477
+ # fail-closed one denies the call it raised on (Hooks.wrap's :deny).
478
+ policy = hook[:on_error] == :fail_closed ? :deny : :log
479
+ label = "#{"guardrail " if policy == :deny}#{@label} #{hook[:event]} hook"
480
+ handler = Hooks.wrap(label: label, event: hook[:event], policy: policy,
456
481
  log: [:plugins, "plugin_hook_failed"], echo: false, fields: { bundle: @bundle },
457
- on_failure: @registries.hook_failed) do |event|
482
+ on_failure: hook_failed(policy)) do |event|
458
483
  # ctx's helpers act as this event's while the block runs.
459
484
  context ? context.with_event(event) { block.call(event, context) } : block.call(event, context)
460
485
  end
@@ -478,6 +503,16 @@ module Samagotchi
478
503
  @committed = true
479
504
  end
480
505
 
506
+ # Registries#hook_failed for a hook under +policy+: a fail-closed one's
507
+ # notice says it denies (effect: :deny).
508
+ def hook_failed(policy)
509
+ told = @registries.hook_failed
510
+ return told unless told && policy == :deny
511
+
512
+ ->(label, failed) { told.call(label, failed, effect: :deny) }
513
+ end
514
+ private :hook_failed
515
+
481
516
  # @return [Hash] how many of each it registered (for the log)
482
517
  def counts = { commands: @commands.size, annotations: @annotations.size, tools: @tools.size, hooks: @hooks.size,
483
518
  services: @services.size, inits: @inits.size, toolkits: @toolkits.size,
@@ -25,7 +25,8 @@ module Samagotchi
25
25
  # +prompt_changed+ rebuilds its system prompts (chi.prompt_changed!),
26
26
  # +judgments+ the Engine's SystemOne::Judgments (chi.judgment),
27
27
  # +hook_failed+ is (label, "Class: message") when a chi.on handler
28
- # raises (HookRoutes#plugin_hook_failed).
28
+ # raises, with effect: :deny for a fail-closed one
29
+ # (HookRoutes#plugin_hook_failed).
29
30
  Registries = Struct.new(:commands, :tools, :hooks, :context_for, :tools_changed, :services, :stage_tools, :init,
30
31
  :toolkits, :tool_index, :peer_sources, :prompt_sections, :prompt_changed, :judgments,
31
32
  :hook_failed, keyword_init: true)
@@ -42,7 +43,12 @@ module Samagotchi
42
43
  # fails adds nothing.
43
44
  #
44
45
  # A failure is logged and added to +failures+ (not required: tool calls
45
- # still run), which the Engine announces once. Not fail-closed.
46
+ # still run), which the Engine announces once. A guardrail plugin's
47
+ # (the manifest's plugin: required: true, read from the kept manifest:
48
+ # InstalledManifest#plugin_required) goes to +guardrail_failures+ as
49
+ # required instead: every tool call is denied, as for a fail-closed
50
+ # config hook. Its chi.on(..., on_error: :fail_closed) hooks deny the
51
+ # call they raise on (Api#on).
46
52
  module Loader
47
53
  TAG = :plugins
48
54
 
@@ -50,12 +56,16 @@ module Samagotchi
50
56
 
51
57
  # @param registries [Registries]
52
58
  # @param failures [Guardrails::LoadFailures, nil]
59
+ # @param guardrail_failures [Guardrails::LoadFailures, nil] where a
60
+ # required plugin's failure goes (the Engine's guardrail failures);
61
+ # nil: +failures+, still required
53
62
  # @param settings [Hash{String => Hash}] config.yml `bundles:`
54
63
  # @return [Array<String>] the bundles whose plugin loaded
55
- def load_installed(registries, failures: nil, settings: {})
64
+ def load_installed(registries, failures: nil, guardrail_failures: nil, settings: {})
56
65
  loaded = []
57
66
  MemoryBundle::Provenance.each_installed(holding: :plugin) do |bundle_name, bundle|
58
- ok = load_bundle(bundle_name, bundle, registries, failures: failures, settings: settings[bundle_name.to_s] || {})
67
+ ok = load_bundle(bundle_name, bundle, registries, failures: failures, guardrail_failures: guardrail_failures,
68
+ settings: settings[bundle_name.to_s] || {})
59
69
  loaded << bundle_name if ok
60
70
  end
61
71
  loaded
@@ -66,22 +76,35 @@ module Samagotchi
66
76
  end
67
77
 
68
78
  # @return [Boolean] whether the plugin loaded
69
- def load_bundle(bundle_name, bundle, registries, failures: nil, settings: {})
79
+ def load_bundle(bundle_name, bundle, registries, failures: nil, guardrail_failures: nil, settings: {})
70
80
  file = MemoryBundle::Provenance.new(name: bundle_name).plugin_path(bundle) unless bundle.error?
71
81
  basename = file ? File.basename(file) : "plugin"
82
+ # Known before it registers anything: a guardrail that fails to load
83
+ # (its sha, requires_chi, a raise) denies every tool call.
84
+ required = !bundle.error? && bundle.manifest.plugin_required
85
+ into = required ? guardrail_failures || failures : failures
72
86
  reason = bundle.error || unloadable_reason(file, bundle)
73
- return failed(bundle_name, basename, reason, failures) if reason
87
+ return failed(bundle_name, basename, reason, into, required: required) if reason
74
88
 
75
89
  api = register_file(bundle_name, file, registries, settings: settings)
90
+ warn_unrequired(bundle_name, basename) if api.fail_closed? && !required
76
91
  Log.info(TAG, "plugin_loaded", bundle: bundle_name, file: basename, **api.counts)
77
92
  true
78
93
  rescue Exception => e # rubocop:disable Lint/RescueException -- a plugin's SyntaxError or exit must not stop chi
79
94
  raise if e.is_a?(SignalException) # Ctrl-C and kill signals are the user's
80
95
 
81
- failed(bundle_name, basename, "#{e.class}: #{e.message}", failures,
96
+ failed(bundle_name, basename, "#{e.class}: #{e.message}", into || failures, required: required == true,
82
97
  location: file && Guardrails::LoadFailures.location(e, File.dirname(file)))
83
98
  end
84
99
 
100
+ # A fail-closed hook from a plugin its manifest doesn't call required:
101
+ # it denies the call it raises on, but a load failure would not deny.
102
+ def warn_unrequired(bundle_name, basename)
103
+ text = "#{label(bundle_name, basename)} has a fail-closed hook but its manifest's plugin: has no required: true, " \
104
+ "so a failure to load it would not deny tool calls"
105
+ Log.warn(TAG, "plugin_fail_closed_unrequired", bundle: bundle_name, file: basename, msg: text)
106
+ end
107
+
85
108
  # Build +file+'s plugin with +settings+ and commit what its #register
86
109
  # staged into +registries+ (no sha or requires_chi check: #load_bundle
87
110
  # makes them; the test kit loads a bundle's source this way).
@@ -144,10 +167,10 @@ module Samagotchi
144
167
  end
145
168
  end
146
169
 
147
- def failed(bundle_name, basename, reason, failures, location: nil)
170
+ def failed(bundle_name, basename, reason, failures, required: false, location: nil)
148
171
  Log.warn(TAG, "plugin_not_loaded", echo: "[samagotchi:plugins] bundle '#{bundle_name}' plugin '#{basename}' not loaded: #{reason}",
149
- bundle: bundle_name, file: basename)
150
- failures&.add("plugin #{basename} (bundle #{bundle_name})", reason, required: false, location: location)
172
+ bundle: bundle_name, file: basename, required: required)
173
+ failures&.add("plugin #{basename} (bundle #{bundle_name})", reason, required: required, location: location)
151
174
  false
152
175
  end
153
176
  end
@@ -223,7 +223,7 @@ module Samagotchi
223
223
  return if running.size < max
224
224
 
225
225
  raise Error, "#{running.size} child sessions of this session are running (the most is #{max}, " \
226
- "#{Tools::Delegate::MAX_CHILDREN_KEY}): #{running.map { |s| s[:short_id] }.join(", ")}"
226
+ "#{Tools::Delegate::MAX_CHILDREN_KEY}): #{running.map(&:short_id).join(", ")}"
227
227
  end
228
228
 
229
229
  def live_snapshot(sid, state_dir)
@@ -63,38 +63,31 @@ module Samagotchi
63
63
  nil
64
64
  end
65
65
 
66
- # The level for +target+ and where it came from ("session",
66
+ # The level for +lookup+'s model and where it came from ("session",
67
67
  # "SAMAGOTCHI_REASONING_HISTORY", "models: qwen", "hosts.work"; nil for
68
68
  # the default).
69
- # @param target [HostRegistry::ModelTarget]
70
- # @param names [Array<String>] the model's lookup names (HostRegistry#lookup_names)
71
- # @param models [Hash{String => ModelSettings}, nil] ModelSettings.all (specs)
69
+ # @param lookup [ModelLookup] the model's layers (EffectiveModel#lookup)
72
70
  # @param session [Symbol, nil] the session's own level (Session#reasoning_history)
73
71
  # @return [Array(Symbol, String|nil)]
74
- def resolve(target, names:, models: nil, session: nil)
72
+ def resolve(lookup, session: nil)
75
73
  return [session, SESSION_SOURCE] if session
76
74
 
77
- env = env_level
75
+ env = env_level(lookup)
78
76
  return [env, ENV_NAME] if env
79
77
 
80
- models ||= begin
81
- ModelSettings.all
82
- rescue StandardError
83
- {}
84
- end
85
- setting = ModelSettings.find(names, :reasoning_history, models: models)
78
+ setting = lookup.model(:reasoning_history)
86
79
  return [setting.value, "models: #{setting.key}"] if setting
87
80
 
88
- host = target.entry&.reasoning_history
89
- return [host, "hosts.#{target.entry.name}"] if host
81
+ host = lookup.host(:reasoning_history)
82
+ return [host, "hosts.#{lookup.host_name}"] if host
90
83
 
91
- [API_DEFAULTS.fetch(target.entry&.api&.to_sym, DEFAULT), nil]
84
+ [API_DEFAULTS.fetch(lookup.entry&.api&.to_sym, DEFAULT), nil]
92
85
  end
93
86
 
94
87
  # #resolve, as a SettingExplained with the session's own level beside it.
95
88
  # @return [SettingExplained]
96
- def explain(target, names:, models: nil, session: nil)
97
- level, source = resolve(target, names: names, models: models, session: session)
89
+ def explain(lookup, session: nil)
90
+ level, source = resolve(lookup, session: session)
98
91
  SettingExplained.new(level: level, source: source, own: session)
99
92
  end
100
93
 
@@ -150,9 +143,10 @@ module Samagotchi
150
143
  # "drop (models: qwen)", "turn (default)".
151
144
  def label(level, source) = "#{level} (#{source || "default"})"
152
145
 
153
- # SAMAGOTCHI_REASONING_HISTORY as a level, nil when unset or unknown.
154
- def env_level
155
- raw, origin = Config.get_with_origin(KEY)
146
+ # SAMAGOTCHI_REASONING_HISTORY (read with +lookup+'s env) as a level,
147
+ # nil when unset or unknown.
148
+ def env_level(lookup)
149
+ raw, origin = lookup.global(KEY)
156
150
  origin == :env ? level(raw, ENV_NAME) : nil
157
151
  rescue StandardError
158
152
  nil
@@ -0,0 +1,27 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "steer"
4
+ require_relative "bridge/card_places"
5
+
6
+ module Samagotchi
7
+ # Where a saved recap sits among the turns a page draws: after the last
8
+ # turn opening it covers (Steer.turn_opening?, the rule its turns_since
9
+ # count goes by). Its stamp is that opening's id, as a card's is
10
+ # (Bridge::CardPlaces.stamp: a prompt's turn_id, a wake note's, a
11
+ # /continue no reason line's opening_id), so the page finds the bubble by
12
+ # id, not by counting back (a rollback or a check-in could make the count
13
+ # land a turn off). Read at read time from recap.json's `covered`: the file
14
+ # is unchanged, an old one gets a stamp too. Pure.
15
+ module RecapPlace
16
+ module_function
17
+
18
+ # @param messages [Array<Hash>] the session's messages (symbol or string keys)
19
+ # @param covered [Integer] how many of them the recap covers
20
+ # @return [String, nil] the id of the last opening in the covered
21
+ # messages; nil for none, or one with no id (a line an older chi wrote)
22
+ def opening_id(messages, covered)
23
+ opening = Array(messages).first([covered.to_i, 0].max).reverse_each.find { |message| Steer.turn_opening?(message) }
24
+ opening && Bridge::CardPlaces.stamp(opening)
25
+ end
26
+ end
27
+ end
@@ -0,0 +1,38 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "../session"
4
+ require_relative "../worker_link"
5
+
6
+ module Samagotchi
7
+ module ReplyWait
8
+ # Who runs the session, as one look of a wait reads it: one owner lock
9
+ # read and one WorkerLink resolve on it. Two readers on purpose:
10
+ # #owner? (any kind, a one-turn chi run's too: its turn is alive) for
11
+ # whether the worker is gone, #worker_owned? (a worker's lock) for
12
+ # whether a question waits for an answer (a one-turn run's is answered
13
+ # there; a dead worker's waits for no one).
14
+ class Liveness
15
+ def initialize(id, state_dir:)
16
+ @id = id
17
+ @state_dir = state_dir
18
+ end
19
+
20
+ # The lock's holder (SessionManager.session_owner).
21
+ # @return [OwnerLock::Owner, nil]
22
+ def owner
23
+ return @owner if defined?(@owner)
24
+
25
+ @owner = SessionManager.session_owner(@id, state_dir: @state_dir)
26
+ end
27
+
28
+ def owner? = !owner.nil?
29
+
30
+ def worker_owned?
31
+ return @worker_owned if defined?(@worker_owned)
32
+
33
+ @worker_owned = WorkerLink.resolve(Session.session_dir(@id, state_dir: @state_dir), unlink: false,
34
+ owner: owner).worker_owned?
35
+ end
36
+ end
37
+ end
38
+ end
@@ -5,7 +5,7 @@ require_relative "../session_inbox"
5
5
  require_relative "../turn_checkpoint"
6
6
  require_relative "../continue_offer"
7
7
  require_relative "../steer"
8
- require_relative "../worker_link"
8
+ require_relative "liveness"
9
9
 
10
10
  module Samagotchi
11
11
  module ReplyWait
@@ -72,13 +72,17 @@ module Samagotchi
72
72
  # @return [Result, nil]
73
73
  def look
74
74
  look_at_input
75
+ # Before the load: the turn it names began before what the load sees.
76
+ merge = merge_record
75
77
  session = Session.load(@id, state_dir: @state_dir)
78
+ # Who runs it, read once for this look's checks.
79
+ @live = Liveness.new(@id, state_dir: @state_dir)
76
80
  if (result = removed(session))
77
81
  return result
78
82
  end
79
83
 
80
84
  note_own_running(session)
81
- follow_merge(session)
85
+ follow_merge(session, merge)
82
86
  reply(session) || settled_turn(session) || status_end(session) || question(session) || held(session) || canceled ||
83
87
  ended_before_reply(session) || ended_before_turn(session) || turn_end(session) || owner_gone(session) ||
84
88
  message_waiting || timed_out
@@ -106,8 +110,11 @@ module Samagotchi
106
110
  Result.new(status: :no_reply, outcome: "removed", session: session)
107
111
  end
108
112
 
113
+ # Its turn ran, or a drain merged it (its merge record): a dequeue's
114
+ # tombstone that lost the claim to the drain is a stray too.
109
115
  def turn_ran?(session)
110
- session.last_turn&.enqueued_id == @turn || !SessionInbox.reply_for(@session_dir, @turn).nil?
116
+ session.last_turn&.enqueued_id == @turn || !SessionInbox.reply_for(@session_dir, @turn).nil? ||
117
+ !SessionInbox.merged_into(@session_dir, @turn).nil?
111
118
  end
112
119
 
113
120
  def note_own_running(session)
@@ -119,14 +126,37 @@ module Samagotchi
119
126
 
120
127
  # Taken but never run as a turn of its own: a running turn's drain
121
128
  # merged it as a steer, so that turn's reply (or question) is its
122
- # answer. Waited for as the next reply past the cursor, as without
123
- # turn:, never as a turn that will not come.
124
- def follow_merge(session)
125
- return unless @turn && @claimed && !@seen_own && !@own_turn_input &&
126
- ReplyWait.merged_elsewhere?(session, @turn, @baseline, @session_dir)
127
-
128
- @turn = nil
129
- @seen_running = running?(session)
129
+ # answer. With the drain's merge record (SessionInbox.mark_merged)
130
+ # the wait is that turn's from here on, as if it had been bound to it
131
+ # (#follow_into). Without one (a 0.156 worker, a turn with no id, a
132
+ # merge from before the update) the merge is inferred
133
+ # (ReplyWait.merged_elsewhere?) and waited for as the next reply past
134
+ # the cursor, as without turn:, never as a turn that will not come.
135
+ def follow_merge(session, merge)
136
+ return unless may_follow?
137
+
138
+ if merge
139
+ follow_into(session, merge)
140
+ elsif ReplyWait.merged_elsewhere?(session, @turn, @baseline, @session_dir)
141
+ @turn = nil
142
+ @seen_running = running?(session)
143
+ end
144
+ end
145
+
146
+ def may_follow? = @turn && @claimed && !@seen_own && !@own_turn_input
147
+
148
+ def merge_record = may_follow? ? SessionInbox.merged_into(@session_dir, @turn) : nil
149
+
150
+ # Bound to the turn that took it, once (its own input ran as its own
151
+ # turn). Not running in this look, which loaded after the record:
152
+ # that turn is over (its end, its reply, its settle say how), and a
153
+ # turn that ended after the merge with last_turn not its is past it
154
+ # (#own_turn_end).
155
+ def follow_into(session, merge)
156
+ @turn = merge.into
157
+ @own_turn_input = true
158
+ note_own_running(session)
159
+ @merged_at = merge.at unless @seen_own
130
160
  end
131
161
 
132
162
  def reply(session)
@@ -172,9 +202,7 @@ module Samagotchi
172
202
  end
173
203
 
174
204
  # A worker holds the session's lock (a one-turn chi run's question is its own).
175
- def worker_owned?
176
- WorkerLink.resolve(Session.session_dir(@id, state_dir: @state_dir), unlink: false).worker_owned?
177
- end
205
+ def worker_owned? = @live.worker_owned?
178
206
 
179
207
  # A participant's turn its worker holds while the owner's Continue
180
208
  # offer stands (Worker#run_input_files): it waits for the owner's
@@ -273,6 +301,7 @@ module Samagotchi
273
301
  # died), or it ended with no reply and a next turn ran and ended
274
302
  # between two looks. Waiting on would sit through those turns.
275
303
  return Result.new(status: :no_reply, session: session) if @seen_own && ReplyWait.past_own?(session, @turn, @own_base)
304
+ return Result.new(status: :no_reply, session: session) if @merged_at && ReplyWait.ended_after?(session, @merged_at)
276
305
 
277
306
  nil
278
307
  end
@@ -307,7 +336,7 @@ module Samagotchi
307
336
  def owner_gone(session)
308
337
  return nil unless @owner_grace
309
338
 
310
- if SessionManager.session_owner(@id, state_dir: @state_dir)
339
+ if @live.owner?
311
340
  @gone_since = nil
312
341
  elsif ReplyWait.monotonic - (@gone_since ||= ReplyWait.monotonic) > @owner_grace
313
342
  return Result.new(status: :worker_gone, session: session)