samagotchi 0.142.0 → 0.143.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 (118) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +66 -7
  3. data/README.md +1 -0
  4. data/docs/architecture.md +13 -6
  5. data/docs/bundle-authoring.md +6 -6
  6. data/docs/bundles.md +1232 -0
  7. data/docs/cli.md +36 -6
  8. data/docs/configuration.md +11 -12
  9. data/docs/context.md +10 -10
  10. data/docs/guardrails.md +7 -9
  11. data/docs/hooks.md +19 -2
  12. data/docs/internals/attached-context.md +2 -3
  13. data/docs/internals/bundles.md +5 -3
  14. data/docs/internals/engine.md +9 -3
  15. data/docs/internals/prompt-caching.md +12 -12
  16. data/docs/internals/web-push.md +1 -1
  17. data/docs/memory.md +2 -2
  18. data/docs/plugins.md +26 -1251
  19. data/docs/sessions.md +2 -2
  20. data/docs/sub-agent.md +6 -6
  21. data/docs/system-one.md +2 -2
  22. data/lib/samagotchi/bundle_command/api_calls.rb +132 -0
  23. data/lib/samagotchi/bundle_command/check.rb +50 -34
  24. data/lib/samagotchi/bundle_command/installed_check.rb +86 -0
  25. data/lib/samagotchi/bundle_command/scaffold.rb +1 -0
  26. data/lib/samagotchi/bundle_settings_check.rb +58 -0
  27. data/lib/samagotchi/bundles/agents-md/manifest.yml +4 -2
  28. data/lib/samagotchi/bundles/agents-md/plugin.rb +1 -1
  29. data/lib/samagotchi/bundles/btw/manifest.yml +4 -2
  30. data/lib/samagotchi/bundles/btw/plugin.rb +1 -1
  31. data/lib/samagotchi/bundles/check-in/manifest.yml +7 -6
  32. data/lib/samagotchi/bundles/check-in/plugin.rb +7 -14
  33. data/lib/samagotchi/bundles/claude-peer/manifest.yml +3 -3
  34. data/lib/samagotchi/bundles/claude-peer/plugin.rb +1 -1
  35. data/lib/samagotchi/bundles/claude-peer/scripts/pair +1 -1
  36. data/lib/samagotchi/bundles/codex-peer/manifest.yml +2 -2
  37. data/lib/samagotchi/bundles/codex-peer/plugin.rb +1 -1
  38. data/lib/samagotchi/bundles/coordinator/manifest.yml +2 -2
  39. data/lib/samagotchi/bundles/coordinator/plugin.rb +1 -1
  40. data/lib/samagotchi/bundles/core/manifest.yml +2 -2
  41. data/lib/samagotchi/bundles/cost-cap/manifest.yml +6 -3
  42. data/lib/samagotchi/bundles/cost-cap/plugin.rb +5 -7
  43. data/lib/samagotchi/bundles/github-pr/manifest.yml +3 -1
  44. data/lib/samagotchi/bundles/known-names/manifest.yml +3 -1
  45. data/lib/samagotchi/bundles/loop-guard/manifest.yml +4 -2
  46. data/lib/samagotchi/bundles/loop-guard/plugin.rb +1 -1
  47. data/lib/samagotchi/bundles/mcp/manifest.yml +4 -2
  48. data/lib/samagotchi/bundles/mcp/plugin.rb +2 -2
  49. data/lib/samagotchi/bundles/ruby/manifest.yml +2 -2
  50. data/lib/samagotchi/bundles/ruby/plugin.rb +1 -1
  51. data/lib/samagotchi/bundles/skills/manifest.yml +4 -2
  52. data/lib/samagotchi/bundles/skills/plugin.rb +1 -1
  53. data/lib/samagotchi/bundles/slow-commands/manifest.yml +4 -2
  54. data/lib/samagotchi/bundles/slow-commands/plugin.rb +1 -1
  55. data/lib/samagotchi/bundles/source-links/manifest.yml +3 -1
  56. data/lib/samagotchi/bundles/system/config_modification_protocol.md +1 -1
  57. data/lib/samagotchi/bundles/system/manifest.yml +3 -3
  58. data/lib/samagotchi/bundles/system/self_map.md +2 -2
  59. data/lib/samagotchi/bundles/work-cap/manifest.yml +6 -3
  60. data/lib/samagotchi/bundles/work-cap/plugin.rb +11 -13
  61. data/lib/samagotchi/context_candidate_choice.rb +12 -3
  62. data/lib/samagotchi/context_candidates.rb +4 -1
  63. data/lib/samagotchi/context_candidates_log.rb +11 -0
  64. data/lib/samagotchi/context_status.rb +1 -2
  65. data/lib/samagotchi/engine.rb +33 -68
  66. data/lib/samagotchi/extension_load.rb +8 -2
  67. data/lib/samagotchi/hook_routes.rb +37 -2
  68. data/lib/samagotchi/hooks/bundle_loader.rb +20 -4
  69. data/lib/samagotchi/hooks/registry.rb +23 -5
  70. data/lib/samagotchi/host_model.rb +3 -3
  71. data/lib/samagotchi/host_registry.rb +14 -7
  72. data/lib/samagotchi/kernel_loop.rb +7 -2
  73. data/lib/samagotchi/llm/chat_loop.rb +5 -0
  74. data/lib/samagotchi/llm/stray_tool_call.rb +23 -16
  75. data/lib/samagotchi/memory_bundle/builder.rb +4 -2
  76. data/lib/samagotchi/memory_bundle/installed_bundle.rb +9 -2
  77. data/lib/samagotchi/memory_bundle/installed_copy.rb +92 -0
  78. data/lib/samagotchi/memory_bundle/installer.rb +2 -0
  79. data/lib/samagotchi/memory_bundle/manifest.rb +23 -13
  80. data/lib/samagotchi/memory_bundle/provenance.rb +4 -1
  81. data/lib/samagotchi/memory_bundle/shipped_update.rb +13 -1
  82. data/lib/samagotchi/model_catalog.rb +3 -2
  83. data/lib/samagotchi/models_command.rb +1 -1
  84. data/lib/samagotchi/plugin/api.rb +14 -11
  85. data/lib/samagotchi/plugin/context.rb +10 -0
  86. data/lib/samagotchi/plugin/loader.rb +4 -2
  87. data/lib/samagotchi/plugin/peer.rb +17 -22
  88. data/lib/samagotchi/plugin_session_state.rb +32 -5
  89. data/lib/samagotchi/prompt_warmup.rb +1 -9
  90. data/lib/samagotchi/session_access/local.rb +1 -1
  91. data/lib/samagotchi/session_access/remote.rb +3 -3
  92. data/lib/samagotchi/session_archive_command.rb +3 -3
  93. data/lib/samagotchi/session_commands.rb +4 -4
  94. data/lib/samagotchi/session_config.rb +9 -3
  95. data/lib/samagotchi/session_continue.rb +1 -1
  96. data/lib/samagotchi/session_manager.rb +15 -6
  97. data/lib/samagotchi/system_one/judgments.rb +8 -25
  98. data/lib/samagotchi/system_one/log.rb +21 -0
  99. data/lib/samagotchi/system_one/recording.rb +1 -1
  100. data/lib/samagotchi/terminal_ui/attach_link.rb +2 -2
  101. data/lib/samagotchi/terminal_ui/attached_loop/exit_commands.rb +1 -1
  102. data/lib/samagotchi/terminal_ui/attached_loop.rb +1 -1
  103. data/lib/samagotchi/terminal_ui/local_link.rb +1 -1
  104. data/lib/samagotchi/terminal_ui/remote_link.rb +1 -2
  105. data/lib/samagotchi/testing/judgments.rb +0 -9
  106. data/lib/samagotchi/update_command.rb +49 -16
  107. data/lib/samagotchi/version.rb +1 -1
  108. data/lib/samagotchi/web/app.rb +1 -0
  109. data/lib/samagotchi/web/auto_update.rb +79 -49
  110. data/lib/samagotchi/web/auto_update_record.rb +59 -0
  111. data/lib/samagotchi/web/public/app.js +8 -4
  112. data/lib/samagotchi/web/public/hash_intent.js +24 -0
  113. data/lib/samagotchi/web/public/index.html +3 -1
  114. data/lib/samagotchi/web/public/revise_stack.js +14 -5
  115. data/lib/samagotchi/web/session_control.rb +3 -3
  116. data/lib/samagotchi/web/update_check.rb +7 -6
  117. data/lib/samagotchi/web/update_ops.rb +80 -25
  118. metadata +8 -1
@@ -82,13 +82,22 @@ module Samagotchi
82
82
  ContextCandidatesLog.records_for(log, session_id).any? { |line| line["kind"] == "carded" && line["name"] == name }
83
83
  end
84
84
 
85
+ # Replace an open offer card with what became of it. Typed in off or audit
86
+ # mode no card is open: #choose answers without one rather than raising a
87
+ # "closed" card out of nowhere.
88
+ def close_open_card(candidate, session_id, state_dir, show_card, body)
89
+ return unless carded?(ContextCandidatesLog.log_for(state_dir), session_id, candidate.name)
90
+
91
+ show_card.call(**closed_card(candidate, body))
92
+ end
93
+
85
94
  def judge_attach(candidate, job:, p:, state_dir:, log:, show_card:)
86
95
  own = ContextSources.session_location(job.session_id, state_dir: state_dir)
87
96
  own.add(ContextCandidates.source_for(candidate, why: JUDGE_WHY))
88
97
  Log.info(:context, "candidate_attached", name: candidate.name, trigger: "judge")
89
98
  ContextCandidatesLog.event("judge_attached", session_id: job.session_id, name: candidate.name, log: log, p: p)
90
99
  # A card from an earlier ask loses its buttons.
91
- show_card.call(**closed_card(candidate, "Attached: #{JUDGE_WHY}.")) if carded?(log, job.session_id, candidate.name)
100
+ close_open_card(candidate, job.session_id, state_dir, show_card, "Attached: #{JUDGE_WHY}.")
92
101
  :attached
93
102
  rescue ContextSources::Invalid, ContextProviders::Invalid => e
94
103
  Log.warn(:context, "candidate_not_attached", name: candidate.name, error: e.message.to_s[0, 200])
@@ -134,7 +143,7 @@ module Samagotchi
134
143
  Log.info(:context, "candidate_attached", name: candidate.name, trigger: "command")
135
144
  ContextCandidatesLog.event("attached", session_id: session.id, name: candidate.name, state_dir: state_dir, by: "command")
136
145
  label_run(session, candidate, "attached", state_dir)
137
- show_card.call(**closed_card(candidate, "Attached."))
146
+ close_open_card(candidate, session.id, state_dir, show_card, "Attached.")
138
147
  [:ok, "attached #{candidate.name}: its text comes with your next message"]
139
148
  rescue ContextSources::Invalid, ContextProviders::Invalid => e
140
149
  [:error, "#{candidate.name} not attached: #{e.message}"]
@@ -155,7 +164,7 @@ module Samagotchi
155
164
  ContextSources.session_location(session.id, state_dir: state_dir).decline(candidate.name, candidate.url.to_s)
156
165
  ContextCandidatesLog.event("declined", session_id: session.id, name: candidate.name, state_dir: state_dir, by: "command")
157
166
  label_run(session, candidate, "declined", state_dir)
158
- show_card.call(**closed_card(candidate, "Not attached here."))
167
+ close_open_card(candidate, session.id, state_dir, show_card, "Not attached here.")
159
168
  [:ok, "declined #{candidate.name}: not proposed again in this session"]
160
169
  end
161
170
  end
@@ -33,7 +33,10 @@ module Samagotchi
33
33
  BRANCH_MIN_CHARS = 6
34
34
  NUMBER_MIN = 10
35
35
  # A fenced code block's opening line (up to 3 spaces, then ``` or ~~~).
36
- FENCE_OPEN = /\A {0,3}(`{3,}|~{3,})/
36
+ # A backtick fence's info string carries no backtick, so nothing after the
37
+ # marker on that line may be one: "```foo``` first" is inline code, and
38
+ # reading it as a fence leaves it unclosed and blanks the rest of the text.
39
+ FENCE_OPEN = /\A {0,3}(`{3,}(?![^\n]*`)|~{3,})/
37
40
  # What may sit around a word-like mention without joining it.
38
41
  WORD_BEFORE = %r{(?<![\w./#-])}
39
42
  WORD_AFTER = %r{(?![\w/-])(?!\.[\w/-])}
@@ -60,6 +60,17 @@ module Samagotchi
60
60
  # +session_id+'s lines, oldest first.
61
61
  def records_for(log, session_id) = log.records.select { |line| line["session_id"] == session_id.to_s }
62
62
 
63
+ # Explicit `chi sessions delete`: everything the session left in the log
64
+ # goes with it, including the `judged` lines that keep 200 characters of
65
+ # its prompts. Never raises.
66
+ # @return [Integer] how many lines were dropped
67
+ def purge_session(session_id, state_dir: nil)
68
+ log_for(state_dir).prune { |line| line["session_id"] != session_id.to_s }
69
+ rescue StandardError => e
70
+ Log.warn(:context, "context_candidates_log_failed", error: e.class.name, msg: e.message.to_s[0, 200])
71
+ 0
72
+ end
73
+
63
74
  # The status the lines last left each candidate in, by name (a
64
75
  # withdrawn one is gone).
65
76
  # @return [Hash{String => String}]
@@ -13,8 +13,7 @@ module Samagotchi
13
13
  # - the status line's value (#display), every request and again from the
14
14
  # server's final counts after each generation;
15
15
  # - a :context_status stream event (#observe's return), on every request,
16
- # so the web and the attached TUI get a fresh estimate each time (the
17
- # context.status_cadence setting no longer throttles this event);
16
+ # so the web and the attached TUI get a fresh estimate each time;
18
17
  # - the model's own short line (#take_guidance), once per rise into a
19
18
  # bucket whose guidance asks for a change (the second threshold up).
20
19
  #
@@ -34,6 +34,7 @@ require_relative "peer_sources"
34
34
  require_relative "session_commands"
35
35
  require_relative "plugin/loader"
36
36
  require_relative "plugin/card"
37
+ require_relative "bundle_settings_check"
37
38
  require_relative "extension_load"
38
39
  require_relative "log"
39
40
  require_relative "log_subscriber"
@@ -170,7 +171,6 @@ module Samagotchi
170
171
  @chat_backend_mutex = Mutex.new
171
172
  @side_judgments = SideJudgments.new
172
173
  @judgments = build_judgments
173
- @context_judge_after_turn = nil
174
174
  # On mode's cards an answer brought while a turn ran: shown once it
175
175
  # has ended (#show_context_cards_after_turn).
176
176
  @context_cards_after_turn = []
@@ -296,7 +296,12 @@ module Samagotchi
296
296
  # toolkit, the tool index, peer sources), then the plugins themselves
297
297
  # unless +load+ is false (see #initialize for when).
298
298
  def build_tools_and_plugins(load:, task_finish_notes:)
299
- @extension_load = ExtensionLoad.new(hook_failures: @guardrail_failures)
299
+ # The routes are built already (#initialize), so a bundle's hook file
300
+ # that raises at fire time is told the same way a chi.on handler is:
301
+ # once per hook in this worker. The guard covers a hook that raises
302
+ # before the routes are there (nothing in the Engine's path does).
303
+ @extension_load = ExtensionLoad.new(hook_failures: @guardrail_failures,
304
+ hook_failed: ->(hook, failed, effect: nil) { @hook_routes&.plugin_hook_failed(hook, failed, effect: effect) })
300
305
  @hooks = @extension_load.hooks
301
306
  # The tools this session offers (the prompts' declarations and the
302
307
  # kernel's dispatch): the built-ins, per Engine. execute.description
@@ -1549,9 +1554,11 @@ module Samagotchi
1549
1554
  @guardrail_failures.message if @guardrail_failures_announced
1550
1555
  end
1551
1556
 
1552
- # The plugins' load warning the first turn announced, likewise.
1557
+ # The plugins' load warning the first turn announced, likewise, and what
1558
+ # their failed chi.on handlers told (HookRoutes#plugin_hook_failed).
1553
1559
  def plugin_warning
1554
- @plugin_failures.message if @guardrail_failures_announced
1560
+ loaded = @plugin_failures.message if @guardrail_failures_announced
1561
+ [loaded, @hook_routes.hook_failures_message].compact.join("; ").then { |text| text unless text.empty? }
1555
1562
  end
1556
1563
 
1557
1564
  # Ask the user to approve a call the gate voted `ask` on
@@ -2321,10 +2328,7 @@ module Samagotchi
2321
2328
  pending_input: pending_input)
2322
2329
  publish_used_memories(session, on_event)
2323
2330
  complete_turn(turn, result)
2324
- # The candidate judge's asks a shared local server kept for the
2325
- # turn's end go first; the warm-up follows them and re-warms the
2326
- # prefix they evicted.
2327
- warm_up_next_turn(turn, result, after: run_context_judge_after_turn)
2331
+ warm_up_next_turn(turn, result)
2328
2332
  result
2329
2333
  rescue Interrupt => e
2330
2334
  # After the end event (in the after_turn/session_end hooks) the
@@ -2352,7 +2356,6 @@ module Samagotchi
2352
2356
  ensure
2353
2357
  release_turn(probe_cancel_before)
2354
2358
  show_context_cards_after_turn
2355
- run_context_judge_after_turn
2356
2359
  end
2357
2360
  end
2358
2361
 
@@ -2453,8 +2456,7 @@ module Samagotchi
2453
2456
  # On mode: the suggested kit, before anything is declared (a Stop
2454
2457
  # during the wait is caught by the check below).
2455
2458
  settle_toolkit_suggestion(turn, toolkit_suggestion)
2456
- # The candidate judge: its asks run beside the turn on a remote
2457
- # System 1 host, after it on the model's own local one; on mode's
2459
+ # The candidate judge: its asks run beside the turn; on mode's
2458
2460
  # attaches reach the model at the next between-turn delivery.
2459
2461
  start_context_judge(turn)
2460
2462
  apply_toolkit!(session, turn.on_event)
@@ -2534,7 +2536,7 @@ module Samagotchi
2534
2536
  # start differs anyway or starts at once: a reminder due, a continue
2535
2537
  # offer (the turn ran out of steps), a carried steer or queued input.
2536
2538
  # Never fails the turn.
2537
- def warm_up_next_turn(turn, result, after: nil)
2539
+ def warm_up_next_turn(turn, result)
2538
2540
  return if result.canceled? || result.resumable?
2539
2541
 
2540
2542
  model = effective_model
@@ -2549,7 +2551,7 @@ module Samagotchi
2549
2551
  return unless prompt
2550
2552
 
2551
2553
  started = @prompt_warmup.start(client: client, prompt: prompt, model: @kernel.turn_settings.model_name,
2552
- slot: @kernel.last_slot, images: images, after: after)
2554
+ slot: @kernel.last_slot, images: images)
2553
2555
  @kernel.warmed_up! if started
2554
2556
  rescue StandardError => e
2555
2557
  Log.warn(:model, "warmup_skipped", error: e.class.name, msg: e.message.to_s[0, 200])
@@ -2930,13 +2932,27 @@ module Samagotchi
2930
2932
  peer_sources: @peer_sources,
2931
2933
  prompt_sections: @prompt_sections,
2932
2934
  prompt_changed: -> { prompt_changed! },
2933
- judgments: @judgments
2935
+ judgments: @judgments,
2936
+ hook_failed: ->(hook, failed) { @hook_routes.plugin_hook_failed(hook, failed) }
2934
2937
  )
2935
2938
  # What plugins show while they load (an MCP server that didn't
2936
2939
  # start) waits for the first turn, beside the load warnings: no UI
2937
2940
  # is there yet, and the Engine isn't built.
2938
- @extension_load.load_plugins(registries, failures: @plugin_failures) { warn_undeclared_judgments }
2941
+ @extension_load.load_plugins(registries, failures: @plugin_failures) do
2942
+ warn_undeclared_judgments
2943
+ warn_bundle_settings
2944
+ end
2945
+ end
2946
+
2947
+ # config.yml bundles: names and keys that do nothing (BundleSettingsCheck),
2948
+ # held like the judgments' line, for the same reason.
2949
+ def warn_bundle_settings
2950
+ BundleSettingsCheck.warnings(@extension_load.bundle_settings).each do |line|
2951
+ Log.warn(:config, "bundle_setting_unknown", msg: line)
2952
+ hook_notify(line, :warn, "config")
2953
+ end
2939
2954
  end
2955
+ private :warn_bundle_settings
2940
2956
 
2941
2957
  # Held with the plugins' own notices, so every UI gets it: a worker's
2942
2958
  # stderr goes nowhere.
@@ -3075,15 +3091,6 @@ module Samagotchi
3075
3091
  ToolkitSuggest::JUDGMENT, session, mode: Config.get("toolkit.suggest.mode").to_s)
3076
3092
  return unless client
3077
3093
 
3078
- # D7: on a shared single-slot server audit's free ask would compete
3079
- # with the turn's prefill, and any ask evicts the session's cached
3080
- # prefix: on mode asks only on a first turn there (nothing is cached
3081
- # yet worth keeping), never on the deferred path.
3082
- if (!joined || ToolkitSuggest.model_reply?(session.messages)) && system_one_shares_local_host?(client.host)
3083
- Log.info(:toolkit, "toolkit_suggest_shared_host_skipped", session_id: session.id, host: client.host)
3084
- return
3085
- end
3086
-
3087
3094
  # The warm-up's only value is the cache: the real ask never queues
3088
3095
  # behind it.
3089
3096
  stop_toolkit_warmup
@@ -3202,9 +3209,6 @@ module Samagotchi
3202
3209
 
3203
3210
  client = SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :toolkit)
3204
3211
  return unless client
3205
- # D7: on the model's own single-slot server it would evict the
3206
- # session's cached prefix for a question that may never come.
3207
- return if system_one_shares_local_host?(client.host)
3208
3212
 
3209
3213
  project = File.basename(session.project_root.to_s)
3210
3214
  @toolkit_warmup_thread = Thread.new do
@@ -3259,7 +3263,6 @@ module Samagotchi
3259
3263
  runs: -> { @session&.scratch ? SystemOne::Runs.new : system_one_runs },
3260
3264
  where: -> { @session && SystemOne::Recording::Context.of(@session, session_model: effective_model_name) },
3261
3265
  side: @side_judgments,
3262
- shared_host_busy: ->(host) { turn_running? && system_one_shares_local_host?(host) },
3263
3266
  participant: -> { !turn_author.nil? }
3264
3267
  )
3265
3268
  end
@@ -3269,19 +3272,6 @@ module Samagotchi
3269
3272
  def system_one_runs = SystemOne::Runs.for_sessions_dir(session_state_dir)
3270
3273
  private :system_one_runs
3271
3274
 
3272
- # D7: System 1's host is the session's model server, and a local one
3273
- # (a single-slot Splash or llama.cpp): the same name, or two hosts:
3274
- # entries for one server root (scheme, host, port).
3275
- def system_one_shares_local_host?(judge_name)
3276
- model_host, = @host_registry.host_for_model(effective_model_name)
3277
- return false if model_host.nil? || model_host.remote?
3278
- return true if judge_name.to_s.strip.casecmp?(model_host.name.to_s)
3279
-
3280
- judge = @host_registry.find_entry(judge_name)
3281
- !judge.nil? && judge.root_url.downcase == model_host.root_url.downcase
3282
- end
3283
- private :system_one_shares_local_host?
3284
-
3285
3275
  # The candidate judge (ContextJudge) at an owner turn's start, after
3286
3276
  # the toolkit's ask settled: the session's candidates' status changes
3287
3277
  # are logged (ContextCandidatesLog#look) and, unless
@@ -3309,10 +3299,7 @@ module Samagotchi
3309
3299
  private :judge_late_candidates
3310
3300
 
3311
3301
  # One look at +session+'s candidates; the asks go to SideJudgments'
3312
- # :context kind, one thread asking each due candidate in turn. On the
3313
- # model's own local server (#system_one_shares_local_host?) the asks
3314
- # wait for the running turn's end (#run_context_judge_after_turn),
3315
- # never competing with its prefill; any other host is asked now.
3302
+ # :context kind, one thread asking each due candidate in turn.
3316
3303
  def context_judge_pass(session, texts, phase:)
3317
3304
  return if session.id.nil? || session.scratch
3318
3305
 
@@ -3333,14 +3320,7 @@ module Samagotchi
3333
3320
  ContextJudge::JUDGMENT, session, mode: settings.mode)
3334
3321
  return unless client
3335
3322
 
3336
- choice = context_choice(session, log, settings)
3337
- ask = -> { start_context_asks(client, jobs, log, settings, choice) }
3338
- if turn_running? && system_one_shares_local_host?(client.host)
3339
- Log.info(:context, "context_judge_after_turn", session_id: session.id, host: client.host)
3340
- @context_judge_after_turn = ask
3341
- else
3342
- ask.call
3343
- end
3323
+ start_context_asks(client, jobs, log, settings, context_choice(session, log, settings))
3344
3324
  rescue StandardError => e
3345
3325
  ContextJudge.warn(e)
3346
3326
  end
@@ -3398,21 +3378,6 @@ module Samagotchi
3398
3378
  end
3399
3379
  private :show_context_cards_after_turn
3400
3380
 
3401
- # The asks a shared local host kept for the turn's end: a completed
3402
- # turn starts them before its warm-up (which waits for them,
3403
- # PromptWarmup#start's after:); a turn that ended otherwise, from
3404
- # #run_turn's ensure.
3405
- # @return [Thread, nil] the asks' thread
3406
- def run_context_judge_after_turn
3407
- ask = @context_judge_after_turn or return nil
3408
- @context_judge_after_turn = nil
3409
- ask.call
3410
- rescue StandardError => e
3411
- ContextJudge.warn(e)
3412
- nil
3413
- end
3414
- private :run_context_judge_after_turn
3415
-
3416
3381
  # A delegate child's parent's sources, by title (else name): the
3417
3382
  # judge's started_from. nil for any other session (a chi send --new
3418
3383
  # session has no parent; a fork isn't a delegate).
@@ -13,8 +13,14 @@ module Samagotchi
13
13
  # turn (Engine#announce_load_events!).
14
14
  class ExtensionLoad
15
15
  # @param hook_failures [Guardrails::LoadFailures] where hooks that fail to load go
16
- def initialize(hook_failures:)
16
+ # @param hook_failed [#call, nil] (label, "Class: message", effect:) when
17
+ # an installed bundle's hook file raises at fire time: the Engine's
18
+ # HookRoutes, so the user is told once per hook. nil where there is no
19
+ # UI to tell (the test kit's sandbox): a hook that raises then says
20
+ # nothing, and raises nothing.
21
+ def initialize(hook_failures:, hook_failed: nil)
17
22
  @hook_failures = hook_failures
23
+ @hook_failed = hook_failed
18
24
  @loading = false
19
25
  @held_events = []
20
26
  end
@@ -87,7 +93,7 @@ module Samagotchi
87
93
  begin
88
94
  Hooks::BundleLoader.load(bundle_name: bundle_name, hooks_dir: hooks_dir, metadata: bundle.hooks, registry: registry,
89
95
  failures: @hook_failures, settings: settings[bundle_name.to_s] || {},
90
- requires_chi: bundle.requires_chi)
96
+ requires_chi: bundle.requires_chi, hook_failed: @hook_failed)
91
97
  rescue Exception => e # rubocop:disable Lint/RescueException -- a hook's SyntaxError or exit must not stop chi
92
98
  raise if e.is_a?(SignalException) # Ctrl-C and kill signals are the user's
93
99
 
@@ -18,6 +18,15 @@ module Samagotchi
18
18
  class HookRoutes
19
19
  # What a notice may stand in for (#notify's fallback_for:).
20
20
  NOTICE_FALLBACKS = %i[display editor].freeze
21
+ # How much of a failed hook's error #plugin_hook_failed shows.
22
+ HOOK_FAILURE_CHARS = 300
23
+ # What the notice says the hook now does, by the policy Hooks.wrap gave it
24
+ # (a chi.on handler is always :log; a bundle's hook file any of the three).
25
+ HOOK_FAILURE_EFFECTS = {
26
+ log: "it's skipped, and only the log has its next failures",
27
+ skip: "it's skipped, and its next failures are silent",
28
+ deny: "it denies every tool call it guards, and its next failures are in each denial's reason"
29
+ }.freeze
21
30
 
22
31
  # @param event_routes [EventRoutes] where a notice goes
23
32
  # @param question_desk [#call] → QuestionDesk
@@ -31,6 +40,8 @@ module Samagotchi
31
40
  @steer = steer
32
41
  @turn_author = turn_author
33
42
  @unknown_fallbacks = Set.new
43
+ @hook_failures = {}
44
+ @hook_failures_lock = Mutex.new
34
45
  end
35
46
 
36
47
  # The things a hook can do beyond reading its event. Each gets the
@@ -81,11 +92,35 @@ module Samagotchi
81
92
  # load failures show): a running turn's event, else announced or held for
82
93
  # the caller (EventRoutes#route_by_turn: never held while the plugins
83
94
  # load, never an anytime command's, unmarked).
84
- def guardrail_notify(message)
85
- @event_routes.route_by_turn({ type: :guardrail_warning, message: message.to_s })
95
+ # @param label [String, nil] whose line ("plugins"); nil for the guardrails
96
+ def guardrail_notify(message, label: nil)
97
+ @event_routes.route_by_turn({ type: :guardrail_warning, message: message.to_s, label: label }.compact)
86
98
  nil
87
99
  end
88
100
 
101
+ # A bundle hook file or a chi.on handler raised (Hooks.wrap; the log has
102
+ # every firing of a :log one). Its first failure on this Engine, so in
103
+ # this worker, tells the user, as a plugin that failed to load does; then
104
+ # only the log. One line per label — file, bundle and event — so a
105
+ # handler on a stream can't nag.
106
+ # @param hook [String] "<file> (bundle <name>) <event> hook"
107
+ # @param failed [String] "Class: message"
108
+ # @param effect [Symbol] the hook's policy, for what the line says it does
109
+ def plugin_hook_failed(hook, failed, effect: :log)
110
+ line = "#{hook} failed (#{failed.lines.first.to_s.strip[0, HOOK_FAILURE_CHARS]}): " \
111
+ "#{HOOK_FAILURE_EFFECTS[effect] || HOOK_FAILURE_EFFECTS[:log]}"
112
+ first = @hook_failures_lock.synchronize { @hook_failures.key?(hook) ? false : (@hook_failures[hook] = line) }
113
+ guardrail_notify(line, label: "plugins") if first
114
+ nil
115
+ end
116
+
117
+ # What #plugin_hook_failed told, for a UI that joins later; nil for none.
118
+ # @return [String, nil]
119
+ def hook_failures_message
120
+ lines = @hook_failures_lock.synchronize { @hook_failures.values }
121
+ lines.empty? ? nil : lines.join("; ")
122
+ end
123
+
89
124
  # A question through the question flow (REPL sync handler, attached TUI,
90
125
  # web), single-select, kind "hook". A --non-interactive run has no one
91
126
  # to ask: nil at once. Anything but an answer (a sync handler's text, no
@@ -40,6 +40,9 @@ module Samagotchi
40
40
  # the tool call (fail-closed).
41
41
  # - "log": warn to stderr and continue.
42
42
  # - "skip" (default): silently continue.
43
+ # Whatever the policy, a hook file that raises is told to the user once
44
+ # per hook (its +hook_failed+ callback, the Engine's
45
+ # HookRoutes#plugin_hook_failed): :skip would otherwise leave no trace.
43
46
  module BundleLoader
44
47
  class << self
45
48
  # Load all hook plugins for a bundle into the given registry.
@@ -57,8 +60,11 @@ module Samagotchi
57
60
  # @param requires_chi [String, nil] the bundle's requirement; when
58
61
  # this chi doesn't meet it no hook loads (each is reported, as the
59
62
  # plugin loader does)
63
+ # @param hook_failed [#call, nil] (label, "Class: message", effect:)
64
+ # when a hook file raises at fire time — the Engine's HookRoutes;
65
+ # nil when there is no UI to tell (the test kit)
60
66
  # @return [Integer] number of hooks successfully registered
61
- def load(bundle_name:, hooks_dir:, metadata:, registry:, failures: nil, settings: {}, requires_chi: nil)
67
+ def load(bundle_name:, hooks_dir:, metadata:, registry:, failures: nil, settings: {}, requires_chi: nil, hook_failed: nil)
62
68
  return 0 unless metadata.is_a?(Hash)
63
69
 
64
70
  too_old = MemoryBundle::Manifest.requires_chi_failure(requires_chi, Samagotchi::VERSION)
@@ -85,7 +91,7 @@ module Samagotchi
85
91
  end
86
92
 
87
93
  begin
88
- load_hook_file(bundle_name, basename, file, hook, registry, settings: settings)
94
+ load_hook_file(bundle_name, basename, file, hook, registry, settings: settings, hook_failed: hook_failed)
89
95
  loaded += 1
90
96
  rescue Exception => e # rubocop:disable Lint/RescueException -- a hook's SyntaxError or exit must not stop chi
91
97
  raise if e.is_a?(SignalException) # Ctrl-C and kill signals are the user's
@@ -107,9 +113,12 @@ module Samagotchi
107
113
  # @param hook [MemoryBundle::BundleHook] its manifest entry
108
114
  # @param namespace [Module, nil] the module the file is evaluated
109
115
  # in (default: the bundle's, #namespace_for)
116
+ # @param hook_failed [#call, nil] (label, "Class: message", effect:)
117
+ # on every raise at fire time, whatever the policy; nil gives no
118
+ # notice (the log still has a :log hook's failures)
110
119
  # @raise [Exception] what loading or building the file raised;
111
120
  # nothing is registered then
112
- def load_hook_file(bundle_name, basename, file, hook, registry, settings: {}, namespace: nil)
121
+ def load_hook_file(bundle_name, basename, file, hook, registry, settings: {}, namespace: nil, hook_failed: nil)
113
122
  plugin = instantiate(bundle_name, basename, file, settings: settings, namespace: namespace)
114
123
  hook.events.each do |event_name|
115
124
  event_sym = event_name.to_sym
@@ -119,8 +128,15 @@ module Samagotchi
119
128
  else :skip
120
129
  end
121
130
  label = "#{"guardrail " if fail_closed}#{basename} (bundle #{bundle_name})"
131
+ # Every policy tells, once per label: a hook file under the
132
+ # default :skip would raise with no trace anywhere. The label
133
+ # names the file, the bundle and the event, so one label per
134
+ # hook and a stream hook can't nag.
135
+ on_failure = hook_failed && lambda { |hook_label, failed|
136
+ hook_failed.call("#{hook_label} #{event_sym} hook", failed, effect: policy)
137
+ }
122
138
  handler = Hooks.wrap(label: label, event: event_sym, policy: policy, log: [:hooks, "bundle_hook_failed"],
123
- fields: { bundle: bundle_name }) { |event| plugin.call(event) }
139
+ fields: { bundle: bundle_name }, on_failure: on_failure) { |event| plugin.call(event) }
124
140
  registry.register_bundle(bundle_name, event_sym, hook_name: basename, priority: hook.priority, &handler)
125
141
  end
126
142
  nil
@@ -84,12 +84,18 @@ module Samagotchi
84
84
  # :log warns (a stream hook at most once a minute, failure_log_gate)
85
85
  # :skip is silent
86
86
  # :log and :skip rescue StandardError and ScriptError.
87
+ # Whatever the policy, +on_failure+ is called, so a hook file that raises
88
+ # under :skip (a bundle's own hooks/*.rb, chi-nah among them) is not
89
+ # simply invisible: the loader hands it the Engine's notice.
87
90
  # @param label [String] the hook, for the deny reason and the warning
88
91
  # @param event [Symbol] the hook's event
89
92
  # @param log [Array(Symbol, String)] the warning's tag and record name
90
93
  # @param echo [Boolean] the warning also goes to stderr
91
94
  # @param fields [Hash] more fields for the warning's record
92
- def self.wrap(label:, event:, policy:, log: [:hooks, "hook_failed"], echo: true, fields: {}, &block)
95
+ # @param on_failure [#call, nil] (label, "Class: message") on every
96
+ # failure the rescue takes, under every policy, logged or not;
97
+ # whatever it raises stays here, so it can't change the policy
98
+ def self.wrap(label:, event:, policy:, log: [:hooks, "hook_failed"], echo: true, fields: {}, on_failure: nil, &block)
93
99
  log_failure = failure_log_gate(event)
94
100
  lambda do |payload|
95
101
  yield(payload)
@@ -102,14 +108,26 @@ module Samagotchi
102
108
  failed = "#{e.class}: #{e.message}"
103
109
  if policy == :deny
104
110
  payload[:guardrail]&.deny!("#{label} raised #{failed}", rule: "guardrail-load", source: "core", decided_by: "core") if payload.is_a?(Hash)
105
- elsif policy == :log && log_failure.call
106
- text = "#{label} failed: #{failed}"
107
- Log.warn(log[0], log[1], echo: echo ? "[samagotchi:hooks] #{text}" : nil, hook: label, event: event.to_s,
108
- error: e.class.name, msg: text, **fields)
111
+ elsif policy == :log
112
+ if log_failure.call
113
+ text = "#{label} failed: #{failed}"
114
+ Log.warn(log[0], log[1], echo: echo ? "[samagotchi:hooks] #{text}" : nil, hook: label, event: event.to_s,
115
+ error: e.class.name, msg: text, **fields)
116
+ end
109
117
  end
118
+ # The notice, whatever the policy: :skip logs nothing, so without it a
119
+ # broken bundle hook file would fail with no trace at all.
120
+ tell_failure(on_failure, label, failed)
110
121
  end
111
122
  end
112
123
 
124
+ def self.tell_failure(on_failure, label, failed)
125
+ on_failure&.call(label, failed)
126
+ rescue StandardError => e
127
+ Log.debug(:hooks, "hook_failure_not_told", hook: label, error: e.class.name)
128
+ end
129
+ private_class_method :tell_failure
130
+
113
131
  # What a hook can do beyond reading its event: the Engine's
114
132
  # callables, each given the hook's label. +notify+ takes
115
133
  # (text:, level:, hook:, and fallback_for: when the hook gave one: what
@@ -81,18 +81,18 @@ module Samagotchi
81
81
  # A host that errored keeps only its declared ids, marked unavailable
82
82
  # (still pickable; the listings warn it's unreachable); [] when it
83
83
  # declares none.
84
- # @param results [Hash{String => Hash}] host name => {models: [ModelInfo], error:}
84
+ # @param results [Hash{String => HostRegistry::HostListing}] host name => the listing
85
85
  # @param entries [Hash{String => HostRegistry::HostEntry}]
86
86
  # @return [Hash{String => Array<Row>}] for every host in +results+
87
87
  def self.rows(results, entries)
88
88
  results.each_with_object({}) do |(name, data), out|
89
89
  declared = entries[name]&.models || {}
90
- if data[:error]
90
+ if data.error
91
91
  out[name] = declared.values.map { |m| HostModel::Row.new(id: m.id, configured: true, info: nil, unavailable: true) }
92
92
  next
93
93
  end
94
94
 
95
- infos = Array(data[:models])
95
+ infos = Array(data.models)
96
96
  by_id = infos.group_by { |info| info.id.to_s.downcase }
97
97
  out[name] = declared.values.map do |m|
98
98
  info = by_id[m.id.downcase]&.first
@@ -29,6 +29,13 @@ module Samagotchi
29
29
  # free model on OpenRouter can send only keep-alives for minutes).
30
30
  REMOTE_FIRST_TOKEN_TIMEOUT = 120
31
31
 
32
+ # One host's answer in list_all_models: the host it was listed from and
33
+ # its port; models: the LLM::ModelInfo list it served ([] when it failed
34
+ # or declared none); error: the listing failure text, nil when it answered.
35
+ HostListing = Data.define(:host, :port, :models, :error) do
36
+ def initialize(host: nil, port: nil, models: [], error: nil) = super
37
+ end
38
+
32
39
  # url: the configured url, when the entry has one (host, port and scheme
33
40
  # come from it); api_key_env: the variable holding the host's API key;
34
41
  # auth: the header it goes in (LLM::ApiKey::SCHEMES), nil for the api's own default;
@@ -341,7 +348,7 @@ module Samagotchi
341
348
  end
342
349
 
343
350
  # List models on all hosts in parallel. On error per-host, skip with error entry (no failover).
344
- # Returns { host_name => { host:, port:, models: [LLM::ModelInfo], error: nil|String } }
351
+ # Returns { host_name => HostListing }
345
352
  # Also populates the model index. Unless forced, a host's list is reused
346
353
  # for its TTL (60s; 10 minutes for a remote host).
347
354
  #
@@ -361,12 +368,12 @@ module Samagotchi
361
368
  Thread.new do
362
369
  begin
363
370
  models = list_models_for(entry)
364
- data = { host: entry.host, port: entry.port, models: models, error: nil }
371
+ data = HostListing.new(host: entry.host, port: entry.port, models: models, error: nil)
365
372
  @mutex.synchronize { @host_lists[name] = { data: data, at: @clock.call } }
366
373
  save_model_list(name, models)
367
374
  rescue StandardError => e
368
375
  Log.warn(:model, "list_failed", host: name, error: e.class.name, msg: e.message.to_s[0, 500])
369
- data = { host: entry.host, port: entry.port, models: [], error: list_error(e) }
376
+ data = HostListing.new(host: entry.host, port: entry.port, models: [], error: list_error(e))
370
377
  end
371
378
  results_mutex.synchronize { results[name] = data }
372
379
  end
@@ -380,8 +387,8 @@ module Samagotchi
380
387
  @entries.each_with_object({}) do |(name, entry), acc|
381
388
  acc[name] = results.fetch(name) do
382
389
  partial = true
383
- { host: entry.host, port: entry.port, models: [],
384
- error: "no answer in #{wait == wait.to_i ? wait.to_i : wait} s" }
390
+ HostListing.new(host: entry.host, port: entry.port, models: [],
391
+ error: "no answer in #{wait == wait.to_i ? wait.to_i : wait} s")
385
392
  end
386
393
  end
387
394
  end
@@ -395,9 +402,9 @@ module Samagotchi
395
402
  index = Hash.new { |h, k| h[k] = [] }
396
403
  @entries.each_key do |hname|
397
404
  data = results[hname]
398
- next if data.nil? || data[:error]
405
+ next if data.nil? || data.error
399
406
 
400
- Array(data[:models]).each do |m|
407
+ Array(data.models).each do |m|
401
408
  down = m.id.to_s.strip.downcase
402
409
  index[down] << hname unless down.empty? || index[down].include?(hname)
403
410
  end
@@ -693,9 +693,14 @@ module Samagotchi
693
693
  # asking again. A second one fails the turn. Returns :next.
694
694
  def after_malformed(turn, generation, reason)
695
695
  response = generation.response.to_s
696
+ # The fields ChatLoop's generation_malformed has too (iteration, served_model,
697
+ # finish_reason, retried, payload); retried is true when this reply is the
698
+ # one asked again, as there.
696
699
  Log.warn(:model, "generation_malformed", iteration: turn.iteration, reason: reason, id_slot: @last_slot,
697
- cache_n: generation.cache&.dig(:cached), finish_reason: generation.finish_reason,
698
- retried: turn.malformed_retried ? true : false,
700
+ cache_n: generation.cache&.dig(:cached),
701
+ served_model: generation.served_model,
702
+ finish_reason: generation.finish_reason,
703
+ retried: !turn.malformed_retried,
699
704
  payload: response[-MALFORMED_TAIL_CHARS..] || response)
700
705
  turn.buffer.slice!(generation.buffer_mark..)
701
706
  if turn.malformed_retried
@@ -663,6 +663,11 @@ module Samagotchi
663
663
  retried: retry_stray,
664
664
  payload: LLM::StrayToolCall.tail(last_text))
665
665
  unless retry_stray
666
+ # A Stop that lands on the first stray reply is not the second
667
+ # one in a row: the retry is off because the turn is stopping.
668
+ # Cancelled means cancelled, not a failed turn.
669
+ return canceled(iteration, @cancel_controller.reason) if @cancel_controller&.cancelled?
670
+
666
671
  # The second one in a row is no answer and runs no tool: the
667
672
  # turn fails, and its earlier steps stay (FailedTurn's
668
673
  # partial conversation, as for any provider error here).