samagotchi 0.140.0 → 0.142.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 (109) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +64 -1
  3. data/README.md +1 -1
  4. data/bin/chi +2 -0
  5. data/docs/architecture.md +14 -285
  6. data/docs/bundle-authoring.md +1 -0
  7. data/docs/cli.md +15 -7
  8. data/docs/configuration.md +57 -18
  9. data/docs/context.md +68 -6
  10. data/docs/guardrails.md +20 -11
  11. data/docs/hooks.md +9 -7
  12. data/docs/internals/attached-context.md +226 -0
  13. data/docs/internals/background-tasks.md +1 -1
  14. data/docs/internals/bridge.md +380 -0
  15. data/docs/internals/bundles.md +1 -0
  16. data/docs/internals/context-telemetry.md +1 -1
  17. data/docs/internals/engine.md +24 -18
  18. data/docs/internals/participants.md +13 -12
  19. data/docs/internals/remote-sessions.md +5 -2
  20. data/docs/internals/{tool-guardrails.md → tool-output-limits.md} +21 -2
  21. data/docs/memory.md +31 -1
  22. data/docs/plugins.md +162 -2
  23. data/docs/sessions.md +53 -28
  24. data/docs/system-one.md +122 -0
  25. data/docs/testing.md +3 -1
  26. data/lib/samagotchi/bridge.rb +2 -0
  27. data/lib/samagotchi/bundles/check-in/manifest.yml +6 -3
  28. data/lib/samagotchi/bundles/check-in/plugin.rb +101 -4
  29. data/lib/samagotchi/bundles/claude-peer/manifest.yml +2 -2
  30. data/lib/samagotchi/bundles/claude-peer/scripts/chi-peer-SKILL.md +14 -0
  31. data/lib/samagotchi/bundles/codex-peer/manifest.yml +2 -2
  32. data/lib/samagotchi/bundles/codex-peer/scripts/chi-peer-SKILL.md +15 -1
  33. data/lib/samagotchi/bundles/core/manifest.yml +2 -2
  34. data/lib/samagotchi/bundles/system/config_modification_protocol.md +2 -2
  35. data/lib/samagotchi/bundles/system/manifest.yml +4 -4
  36. data/lib/samagotchi/bundles/system/memory_guide.md +1 -1
  37. data/lib/samagotchi/bundles/system/self_map.md +1 -1
  38. data/lib/samagotchi/config.rb +74 -14
  39. data/lib/samagotchi/context_candidate_choice.rb +8 -0
  40. data/lib/samagotchi/context_candidates_log.rb +25 -1
  41. data/lib/samagotchi/context_command.rb +32 -9
  42. data/lib/samagotchi/context_judge.rb +6 -2
  43. data/lib/samagotchi/context_move.rb +31 -0
  44. data/lib/samagotchi/context_sources.rb +248 -10
  45. data/lib/samagotchi/engine.rb +68 -7
  46. data/lib/samagotchi/extension_load.rb +3 -2
  47. data/lib/samagotchi/guardrail_wiring.rb +36 -31
  48. data/lib/samagotchi/guardrails/chi_dirs.rb +7 -4
  49. data/lib/samagotchi/guardrails/path_resolve.rb +1 -1
  50. data/lib/samagotchi/guardrails/protected_paths.rb +7 -4
  51. data/lib/samagotchi/guardrails_command.rb +3 -3
  52. data/lib/samagotchi/judgments_command.rb +155 -0
  53. data/lib/samagotchi/kernel_loop.rb +13 -1
  54. data/lib/samagotchi/llm/chat_loop.rb +74 -10
  55. data/lib/samagotchi/llm/errors.rb +7 -5
  56. data/lib/samagotchi/llm/stray_tool_call.rb +61 -0
  57. data/lib/samagotchi/log_line.rb +1 -1
  58. data/lib/samagotchi/memory_bundle/entry_size.rb +100 -0
  59. data/lib/samagotchi/plugin/api.rb +33 -2
  60. data/lib/samagotchi/plugin/attached_context.rb +14 -2
  61. data/lib/samagotchi/plugin/context.rb +54 -1
  62. data/lib/samagotchi/plugin/judgments.rb +72 -0
  63. data/lib/samagotchi/plugin/loader.rb +3 -2
  64. data/lib/samagotchi/plugin/peer.rb +53 -0
  65. data/lib/samagotchi/plugin/sessions.rb +9 -2
  66. data/lib/samagotchi/run_options.rb +1 -0
  67. data/lib/samagotchi/self_report.rb +36 -0
  68. data/lib/samagotchi/send_command.rb +3 -1
  69. data/lib/samagotchi/session.rb +4 -0
  70. data/lib/samagotchi/session_access/contract.rb +3 -1
  71. data/lib/samagotchi/session_access/local.rb +24 -3
  72. data/lib/samagotchi/session_access/remote.rb +19 -8
  73. data/lib/samagotchi/session_access.rb +26 -6
  74. data/lib/samagotchi/session_commands.rb +3 -0
  75. data/lib/samagotchi/session_continue.rb +9 -2
  76. data/lib/samagotchi/session_manager.rb +13 -2
  77. data/lib/samagotchi/session_retention.rb +10 -0
  78. data/lib/samagotchi/side_judgments.rb +12 -1
  79. data/lib/samagotchi/system_one/answer.rb +63 -11
  80. data/lib/samagotchi/system_one/approval_label.rb +56 -0
  81. data/lib/samagotchi/system_one/approval_question.rb +2 -0
  82. data/lib/samagotchi/system_one/client.rb +43 -17
  83. data/lib/samagotchi/system_one/fake_backend.rb +1 -1
  84. data/lib/samagotchi/system_one/http_backend.rb +12 -4
  85. data/lib/samagotchi/system_one/judgment_settings.rb +61 -0
  86. data/lib/samagotchi/system_one/judgments.rb +260 -0
  87. data/lib/samagotchi/system_one/log.rb +4 -2
  88. data/lib/samagotchi/system_one/recording.rb +117 -0
  89. data/lib/samagotchi/system_one/runs.rb +179 -0
  90. data/lib/samagotchi/system_one/runs_store.rb +230 -0
  91. data/lib/samagotchi/system_one.rb +9 -0
  92. data/lib/samagotchi/testing/boundary.rb +5 -1
  93. data/lib/samagotchi/testing/bundle.rb +9 -2
  94. data/lib/samagotchi/testing/host.rb +2 -1
  95. data/lib/samagotchi/testing/judgments.rb +185 -0
  96. data/lib/samagotchi/testing/recorder.rb +5 -0
  97. data/lib/samagotchi/testing/recording_api.rb +1 -1
  98. data/lib/samagotchi/tool_output_cut.rb +26 -6
  99. data/lib/samagotchi/tool_response.rb +1 -1
  100. data/lib/samagotchi/tool_runner.rb +63 -4
  101. data/lib/samagotchi/toolkit_suggest.rb +11 -2
  102. data/lib/samagotchi/tools/memory.rb +28 -0
  103. data/lib/samagotchi/turn_note.rb +9 -0
  104. data/lib/samagotchi/version.rb +1 -1
  105. data/lib/samagotchi/web/app.rb +14 -8
  106. data/lib/samagotchi/web/public/chains.js +10 -2
  107. data/lib/samagotchi/web/session_access_routes.rb +7 -2
  108. data/lib/samagotchi/web/session_create.rb +1 -0
  109. metadata +17 -2
@@ -23,13 +23,14 @@ module Samagotchi
23
23
  # sessions/<id>/muted/<name> a marker: this session ignores <name>
24
24
  # sessions/<id>/declined/<name> a marker (its hint inside): the user removed <name>
25
25
  # sessions/<id>/candidates/<name>.json a Candidate: a source a plugin proposed here (ctx.context.propose)
26
+ # sessions/<id>/left.json [Left]: what a continue left with the previous link (.move)
26
27
  # The guardrails protect the root (ProtectedPaths, CHI_TEXT): a source's
27
28
  # command runs later, outside the gate.
28
29
  module ContextSources
29
30
  DIR = "context"
30
31
  NAME_RE = /\A[a-z0-9][a-z0-9-]{0,39}\z/
31
- # subscriptions.json shares a session's folder with its sources.
32
- RESERVED_NAMES = %w[subscriptions].freeze
32
+ # subscriptions.json and left.json share a session's folder with its sources.
33
+ RESERVED_NAMES = %w[subscriptions left].freeze
33
34
  SCOPES = %w[session project].freeze
34
35
  MIN_EVERY_SECONDS = 30
35
36
  DEFAULT_EVERY_SECONDS = 300
@@ -38,6 +39,7 @@ module Samagotchi
38
39
  LINE_MAX_CHARS = 300
39
40
  SNAPSHOT_SUFFIX = ".snapshot.json"
40
41
  SUBSCRIPTIONS_FILE = "subscriptions.json"
42
+ LEFT_FILE = "left.json"
41
43
  MUTED_DIR = "muted"
42
44
  DECLINED_DIR = "declined"
43
45
  CANDIDATES_DIR = "candidates"
@@ -53,21 +55,32 @@ module Samagotchi
53
55
  # folder its cmd's {bundle_dir} names (ContextProviders.command_for).
54
56
  # +title+: what a person reads it as (a candidate's, when one was
55
57
  # attached; nil for most).
56
- Source = Data.define(:name, :cmd, :every_seconds, :why, :hint, :scope, :added_by, :created_at, :provider, :title) do
57
- def initialize(name:, cmd:, every_seconds:, why:, hint:, scope:, added_by:, created_at:, provider: nil, title: nil) = super
58
+ # +movable+: whether a continue or a fork takes it to the new session
59
+ # (ContextSources.move); nil derives it (#movable?).
60
+ Source = Data.define(:name, :cmd, :every_seconds, :why, :hint, :scope, :added_by, :created_at, :provider, :title,
61
+ :movable) do
62
+ def initialize(name:, cmd:, every_seconds:, why:, hint:, scope:, added_by:, created_at:, provider: nil, title: nil,
63
+ movable: nil) = super
58
64
 
59
65
  def push? = cmd.nil?
60
66
 
67
+ # Given (+movable+), else derived from who writes the text: a command
68
+ # source moves (chi runs its command, in the new session too); a
69
+ # pushed one stays (its writer holds the old session's id).
70
+ def movable? = movable.nil? ? !push? : movable
71
+
61
72
  def to_h
62
73
  { "name" => name, "cmd" => cmd, "every_seconds" => every_seconds, "why" => why, "hint" => hint,
63
74
  "scope" => scope, "added_by" => added_by, "created_at" => created_at, "provider" => provider,
64
- "title" => title }.compact
75
+ "title" => title, "movable" => movable }.compact
65
76
  end
66
77
 
67
78
  def self.from_h(data)
79
+ movable = data["movable"]
68
80
  new(name: data["name"].to_s, cmd: data["cmd"], every_seconds: data["every_seconds"]&.to_i,
69
81
  why: data["why"], hint: data["hint"], scope: data["scope"].to_s, added_by: data["added_by"],
70
- created_at: data["created_at"], provider: data["provider"], title: data["title"])
82
+ created_at: data["created_at"], provider: data["provider"], title: data["title"],
83
+ movable: [true, false].include?(movable) ? movable : nil)
71
84
  end
72
85
  end
73
86
 
@@ -179,10 +192,11 @@ module Samagotchi
179
192
  return [] unless Dir.exist?(dir)
180
193
 
181
194
  Dir.children(dir).sort.filter_map do |file|
182
- next unless file.end_with?(".json") && !file.end_with?(SNAPSHOT_SUFFIX) && file != SUBSCRIPTIONS_FILE
195
+ next unless file.end_with?(".json") && !file.end_with?(SNAPSHOT_SUFFIX)
183
196
 
184
197
  name = file.delete_suffix(".json")
185
- name.match?(NAME_RE) ? source(name) : nil
198
+ # subscriptions.json, left.json: not sources.
199
+ name.match?(NAME_RE) && !RESERVED_NAMES.include?(name) ? source(name) : nil
186
200
  end
187
201
  end
188
202
 
@@ -374,6 +388,18 @@ module Samagotchi
374
388
  AtomicFile.write(File.join(dir, SUBSCRIPTIONS_FILE), JSON.generate(subs.transform_values(&:to_h)))
375
389
  end
376
390
 
391
+ # What a continue left with the previous link (ContextSources.move).
392
+ # @return [Array<Left>] none without the file
393
+ def left
394
+ rows = ContextSources.read_json_value(File.join(dir, LEFT_FILE))
395
+ Array(rows).filter_map { |row| Left.from_h(row) if row.is_a?(Hash) && row["name"].is_a?(String) }
396
+ end
397
+
398
+ def write_left(rows)
399
+ FileUtils.mkdir_p(dir)
400
+ AtomicFile.write(File.join(dir, LEFT_FILE), JSON.generate(rows.map(&:to_h)))
401
+ end
402
+
377
403
  def update_subscription(name)
378
404
  subs = subscriptions
379
405
  subs[name] = yield(subs[name] || Subscription.blank(name))
@@ -382,8 +408,215 @@ module Samagotchi
382
408
  end
383
409
  end
384
410
 
411
+ # A source a move left behind (ContextSources.move): its +name+ and
412
+ # +why+, :pushed (derived: its writer holds the old id) or :not_movable
413
+ # (its movable: false).
414
+ Stayed = Data.define(:name, :why) do
415
+ def label = why == :pushed ? "pushed" : "not movable"
416
+
417
+ # The peer whose pairing this is ("Claude"), for a pushed
418
+ # <peer>-inbox or <peer>-outbox (the peer bundles' names: the move
419
+ # runs where no plugin is loaded, so the name is all there is; it
420
+ # only words the note, PeerSources decides what a peer is); nil for
421
+ # any other.
422
+ def peer
423
+ match = why == :pushed && PEER_NAME.match(name)
424
+ match ? match[1].capitalize : nil
425
+ end
426
+
427
+ def inbox? = name.end_with?("-inbox")
428
+ end
429
+ # A source a continue left with the previous link (+from+), as the new
430
+ # link's left.json keeps it: its +name+ and +hint+, the snapshot's (a
431
+ # pushed hint: a peer's re-pair pushes its new inbox there) else the
432
+ # source's. ctx.context.left_behind reads it (Plugin::Peer asks the peer
433
+ # to pair again at that inbox).
434
+ Left = Data.define(:name, :hint, :from) do
435
+ def to_h = { "name" => name, "hint" => hint, "from" => from }.compact
436
+
437
+ def self.from_h(data) = new(name: data["name"].to_s, hint: data["hint"]&.to_s, from: data["from"]&.to_s)
438
+ end
439
+
440
+ PEER_NAME = /\A([a-z][a-z0-9]*)-(?:inbox|outbox)\z/
441
+
442
+ # What ContextSources.move did: the names it took to the new session
443
+ # (+moved+) and the sources it left (+stayed+, Stayed).
444
+ Moved = Data.define(:moved, :stayed) do
445
+ def self.none = new(moved: [], stayed: [])
446
+
447
+ def empty? = moved.empty? && stayed.empty?
448
+
449
+ # The new session's note (one sentence each, no instructions); nil
450
+ # when nothing moved or stayed.
451
+ # @param from [String] the session the sources came from
452
+ def note_text(from)
453
+ return nil if empty?
454
+
455
+ lines = []
456
+ lines << "Context moved with this session: #{moved.join(", ")}." unless moved.empty?
457
+ lines << "Left with #{from.to_s[0, 8]}: #{left_words.join(", ")}." unless stayed.empty?
458
+ lines.join(" ")
459
+ end
460
+
461
+ # Each stayed source with why; a peer's pairing as one group, saying
462
+ # what chi does about it (Plugin::Peer posts the moved message to an
463
+ # inbox left behind; an outbox alone hears of it on its next push's
464
+ # refusal), never whether it worked.
465
+ def left_words
466
+ stayed.group_by { |s| s.peer || s }.values.map do |group|
467
+ peer = group.first.peer
468
+ next "#{group.first.name} (#{group.first.label})" unless peer
469
+
470
+ how = if group.any?(&:inbox?)
471
+ "#{peer}'s pairing: chi asks #{peer} to pair again with this session"
472
+ else
473
+ "#{peer} pairs again when it next answers"
474
+ end
475
+ "#{group.map(&:name).join(", ")} (#{how})"
476
+ end
477
+ end
478
+
479
+ # A UI's few words (chi send --new --continues); nil for nothing.
480
+ def words
481
+ parts = []
482
+ parts << "context moved: #{moved.join(", ")}" unless moved.empty?
483
+ parts << "context stayed: #{stayed.map(&:name).join(", ")}" unless stayed.empty?
484
+ parts.empty? ? nil : parts.join("; ")
485
+ end
486
+
487
+ # chi web's continue answer (moved_context).
488
+ def to_h = { "moved" => moved, "stayed" => stayed.map { |s| { "name" => s.name, "why" => s.label } } }
489
+
490
+ # @param data [Hash, nil] #to_h's; nil (an older chi web): nil
491
+ def self.from_h(data)
492
+ return nil unless data.is_a?(Hash)
493
+
494
+ stayed = Array(data["stayed"]).filter_map do |row|
495
+ next unless row.is_a?(Hash)
496
+
497
+ Stayed.new(name: row["name"].to_s, why: row["why"] == "pushed" ? :pushed : :not_movable)
498
+ end
499
+ new(moved: Array(data["moved"]).map(&:to_s), stayed: stayed)
500
+ end
501
+ end
502
+
385
503
  module_function
386
504
 
505
+ # Takes the movable sources of session +from+'s own location
506
+ # (Source#movable?) to session +to+, the new link of a continue or a
507
+ # plugin fork (+mode+ :continue or :fork), before +to+'s worker starts:
508
+ # each one's source and snapshot (a plain read: writes are AtomicFile
509
+ # renames; never Location#locked, which a fetch holds for its whole
510
+ # command), every declined/ and muted/ marker (the user's choices),
511
+ # and a subscription per source moved. A continue's says nothing seen
512
+ # (the new link's first absorb gives the Attached note) at the
513
+ # snapshot's serial (an old wake doesn't wake it). A fork's is what
514
+ # its +seed+ (the fork's messages) last had: the newest note about the
515
+ # source (its note_id, ContextAbsorber#text_note_id), else as a
516
+ # continue's. Never candidates/, lock files, or a source +to+ has
517
+ # already (it wins). A continue's link keeps what stayed in left.json
518
+ # (Left, Location#left).
519
+ # @param seed [Array<Hash>] a fork's messages
520
+ # @return [Moved]
521
+ def move(from:, to:, mode:, state_dir:, seed: nil)
522
+ raise ArgumentError, "mode is :continue or :fork, not #{mode.inspect}" unless %i[continue fork].include?(mode)
523
+
524
+ source_loc = session_location(from, state_dir: state_dir)
525
+ target = session_location(to, state_dir: state_dir)
526
+ return Moved.none unless Dir.exist?(source_loc.dir)
527
+
528
+ moved = []
529
+ stayed = []
530
+ left = []
531
+ subs = {}
532
+ source_loc.sources.each do |source|
533
+ unless source.movable?
534
+ stayed << Stayed.new(name: source.name, why: source.movable.nil? ? :pushed : :not_movable)
535
+ left << Left.new(name: source.name, hint: source_loc.snapshot(source.name).hint || source.hint, from: from)
536
+ next
537
+ end
538
+ next if File.exist?(target.source_path(source.name))
539
+
540
+ snapshot = copy_source(source, from: source_loc, to: target) or next
541
+ subs[source.name] = moved_subscription(source.name, snapshot, mode == :fork ? seed : nil)
542
+ moved << source.name
543
+ end
544
+ [DECLINED_DIR, MUTED_DIR].each { |folder| copy_markers(source_loc.dir, target.dir, folder) }
545
+ target.write_subscriptions(target.subscriptions.merge(subs)) unless subs.empty?
546
+ target.write_left(left) if mode == :continue && !left.empty?
547
+ Moved.new(moved: moved, stayed: stayed)
548
+ end
549
+
550
+ # The source's file and its snapshot's (when it has one), as they are.
551
+ # @return [Snapshot, nil] the snapshot copied (Snapshot.empty: none);
552
+ # nil when the source went meanwhile (nothing copied)
553
+ def copy_source(source, from:, to:)
554
+ source_raw = File.read(from.source_path(source.name))
555
+ snapshot_path = from.snapshot_path(source.name)
556
+ snapshot_raw = File.file?(snapshot_path) ? File.read(snapshot_path) : nil
557
+ FileUtils.mkdir_p(to.dir)
558
+ AtomicFile.write(to.snapshot_path(source.name), snapshot_raw) if snapshot_raw
559
+ AtomicFile.write(to.source_path(source.name), source_raw)
560
+ data = snapshot_raw && read_json_text(snapshot_raw)
561
+ data ? Snapshot.from_h(data) : Snapshot.empty
562
+ rescue SystemCallError
563
+ nil
564
+ end
565
+
566
+ def read_json_text(raw)
567
+ data = JSON.parse(raw)
568
+ data.is_a?(Hash) ? data : nil
569
+ rescue JSON::ParserError
570
+ nil
571
+ end
572
+
573
+ def copy_markers(from_dir, to_dir, folder)
574
+ source = File.join(from_dir, folder)
575
+ return unless Dir.exist?(source)
576
+
577
+ Dir.children(source).each do |name|
578
+ next unless name.match?(NAME_RE)
579
+
580
+ path = File.join(to_dir, folder, name)
581
+ next if File.exist?(path)
582
+
583
+ FileUtils.mkdir_p(File.dirname(path))
584
+ AtomicFile.write(path, File.read(File.join(source, name)))
585
+ rescue SystemCallError
586
+ next
587
+ end
588
+ end
589
+
590
+ # A moved source's subscription in the new session (#move).
591
+ def moved_subscription(name, snapshot, seed)
592
+ blank = Subscription.blank(name).with(seen_serial: snapshot.serial)
593
+ held = seed && seed_note(name, seed)
594
+ return blank unless held
595
+
596
+ serial, prefix = held
597
+ same = snapshot.serial == serial && snapshot.revision.to_s.start_with?(prefix)
598
+ # A partial revision differs from every full one: an Updated note follows.
599
+ Subscription.blank(name).with(seen: same ? snapshot.revision : prefix, seen_serial: serial)
600
+ end
601
+
602
+ # The serial and revision prefix of the newest text note about +name+
603
+ # in +messages+ (ContextAbsorber's note_id, ctx-<name>-<serial>-<rev12>).
604
+ # @return [Array(Integer, String), nil]
605
+ def seed_note(name, messages)
606
+ pattern = /\Actx-#{Regexp.escape(name)}-(\d+)-(\h{12})\z/
607
+ Array(messages).reverse_each do |message|
608
+ next unless message.is_a?(Hash)
609
+
610
+ context_source = message.key?(:context_source) ? message[:context_source] : message["context_source"]
611
+ next unless context_source == name
612
+
613
+ note_id = (message.key?(:note_id) ? message[:note_id] : message["note_id"]).to_s
614
+ match = pattern.match(note_id) or next
615
+ return [match[1].to_i, match[2]]
616
+ end
617
+ nil
618
+ end
619
+
387
620
  # <state dir>/context; +state_dir+ is the sessions dir (Session.default_state_dir).
388
621
  def root(state_dir: nil)
389
622
  File.join(File.dirname(state_dir || Session.default_state_dir), DIR)
@@ -523,10 +756,15 @@ module Samagotchi
523
756
  end
524
757
 
525
758
  def read_json(path)
759
+ data = read_json_value(path)
760
+ data.is_a?(Hash) ? data : nil
761
+ end
762
+
763
+ # The JSON value in +path+; nil when there is none or it isn't JSON.
764
+ def read_json_value(path)
526
765
  return nil unless File.file?(path)
527
766
 
528
- data = JSON.parse(File.read(path))
529
- data.is_a?(Hash) ? data : nil
767
+ JSON.parse(File.read(path))
530
768
  rescue JSON::ParserError, SystemCallError
531
769
  nil
532
770
  end
@@ -169,6 +169,7 @@ module Samagotchi
169
169
  @chat_backend = nil
170
170
  @chat_backend_mutex = Mutex.new
171
171
  @side_judgments = SideJudgments.new
172
+ @judgments = build_judgments
172
173
  @context_judge_after_turn = nil
173
174
  # On mode's cards an answer brought while a turn ran: shown once it
174
175
  # has ended (#show_context_cards_after_turn).
@@ -431,7 +432,11 @@ module Samagotchi
431
432
  # System 1 (experimental, audit phase): the judgment client is read
432
433
  # from config on every ask, and the running turn's cancel controller
433
434
  # closes a judgment that is no longer wanted.
434
- system_one: -> { SystemOne::Client.from_config(host_registry: @host_registry) },
435
+ system_one: lambda {
436
+ system_one_recording(SystemOne::Client.from_config(host_registry: @host_registry, mode: Config.get("guardrails.system_one.mode")),
437
+ SystemOne::ApprovalQuestion::JUDGMENT, @session)
438
+ },
439
+ system_one_runs: -> { system_one_runs },
435
440
  cancel_controller: -> { active_cancel_controller },
436
441
  # A participant's turn: their name on the owner's card, their
437
442
  # grant's mode for the turn's (GuardrailWiring#turn_mode).
@@ -2924,13 +2929,24 @@ module Samagotchi
2924
2929
  tool_index: @tool_index,
2925
2930
  peer_sources: @peer_sources,
2926
2931
  prompt_sections: @prompt_sections,
2927
- prompt_changed: -> { prompt_changed! }
2932
+ prompt_changed: -> { prompt_changed! },
2933
+ judgments: @judgments
2928
2934
  )
2929
2935
  # What plugins show while they load (an MCP server that didn't
2930
2936
  # start) waits for the first turn, beside the load warnings: no UI
2931
2937
  # is there yet, and the Engine isn't built.
2932
- @extension_load.load_plugins(registries, failures: @plugin_failures)
2938
+ @extension_load.load_plugins(registries, failures: @plugin_failures) { warn_undeclared_judgments }
2939
+ end
2940
+
2941
+ # Held with the plugins' own notices, so every UI gets it: a worker's
2942
+ # stderr goes nowhere.
2943
+ def warn_undeclared_judgments
2944
+ @judgments.undeclared.each do |name|
2945
+ Log.warn(:config, "judgment_undeclared", judgment: name)
2946
+ hook_notify("system_one.judgments.#{name}: no loaded bundle declares it, so it does nothing", :warn, "config")
2947
+ end
2933
2948
  end
2949
+ private :warn_undeclared_judgments
2934
2950
 
2935
2951
  # Keep a plugin's new tool set (chi.replace_tools, from any thread)
2936
2952
  # for the turn thread (PluginTasks#stage_tools).
@@ -3055,7 +3071,8 @@ module Samagotchi
3055
3071
  return
3056
3072
  end
3057
3073
 
3058
- client = SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :toolkit)
3074
+ client = system_one_recording(SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :toolkit),
3075
+ ToolkitSuggest::JUDGMENT, session, mode: Config.get("toolkit.suggest.mode").to_s)
3059
3076
  return unless client
3060
3077
 
3061
3078
  # D7: on a shared single-slot server audit's free ask would compete
@@ -3091,7 +3108,9 @@ module Samagotchi
3091
3108
  state: { project: state[:project].dup.freeze, prompt: state[:prompt].dup.freeze }.freeze
3092
3109
  )
3093
3110
  threshold = Config.get("toolkit.suggest.threshold")
3111
+ runs = session.scratch ? nil : system_one_runs
3094
3112
  pending = ToolkitSuggest::Pending.new(log: log, joined: joined,
3113
+ acted: runs && ->(judged, did) { runs.acted(judged.fields[:run_id], did) },
3095
3114
  timeout_seconds: SystemOne::Client.configured_timeout_ms / 1000.0)
3096
3115
  # On mode: cut by a Stop while the turn waits (Pending#wait), not
3097
3116
  # by one after it went on; audit's ask is never cut.
@@ -3124,7 +3143,7 @@ module Samagotchi
3124
3143
  # slow System 1 host (a local one) is the usual cause.
3125
3144
  timeout_ms = SystemOne::Client.configured_timeout_ms
3126
3145
  Log.warn(:toolkit, "toolkit_suggest_timeout", session_id: turn.session.id, timeout_ms: timeout_ms,
3127
- reason: "System 1 gave no answer within guardrails.system_one.timeout_ms")
3146
+ reason: "System 1 gave no answer within system_one.timeout_ms")
3128
3147
  @toolkit_binding.fell_back(turn.session, "System 1 took over #{timeout_ms} ms")
3129
3148
  return
3130
3149
  end
@@ -3210,6 +3229,46 @@ module Samagotchi
3210
3229
  end
3211
3230
  private :toolkit_suggestion_log
3212
3231
 
3232
+ # +client+ (nil for none) saving its asks as +judgment+'s runs. Anything
3233
+ # going wrong here leaves the client as it was: a run is never worth a
3234
+ # judgment.
3235
+ #
3236
+ # A scratch session's asks aren't saved; a participant's turn is never
3237
+ # judged, so it never comes here.
3238
+ # @param mode [String, nil] the use's mode, for its runs (Recording.wrap)
3239
+ def system_one_recording(client, judgment, session, mode: nil)
3240
+ return client if client.nil? || session&.scratch
3241
+
3242
+ context = SystemOne::Recording::Context.of(session, session_model: session && effective_model_name)
3243
+ SystemOne::Recording.wrap(client, judgment: judgment, runs: system_one_runs, context: context, recorded_mode: mode)
3244
+ rescue StandardError => e
3245
+ Log.warn(:system_one, "system_one_recording_failed", error: e.class.name, msg: e.message.to_s[0, 200])
3246
+ client
3247
+ end
3248
+ private :system_one_recording
3249
+
3250
+ # Bundles' judgments (chi.judgment), on this Engine's Runs and side asks.
3251
+ # A judgment's own host and model are for bundles only: core's clients
3252
+ # above never pass them (D2, JudgmentSettings).
3253
+ def build_judgments
3254
+ SystemOne::Judgments.new(
3255
+ client_for: lambda { |_name, settings|
3256
+ SystemOne::Client.from_config(host_registry: @host_registry, mode: settings.mode, host: settings.host,
3257
+ model: settings.client_model, tag: :plugins)
3258
+ },
3259
+ runs: -> { @session&.scratch ? SystemOne::Runs.new : system_one_runs },
3260
+ where: -> { @session && SystemOne::Recording::Context.of(@session, session_model: effective_model_name) },
3261
+ side: @side_judgments,
3262
+ shared_host_busy: ->(host) { turn_running? && system_one_shares_local_host?(host) },
3263
+ participant: -> { !turn_author.nil? }
3264
+ )
3265
+ end
3266
+ private :build_judgments
3267
+
3268
+ # Where this Engine's runs are saved; read each time, as the settings are.
3269
+ def system_one_runs = SystemOne::Runs.for_sessions_dir(session_state_dir)
3270
+ private :system_one_runs
3271
+
3213
3272
  # D7: System 1's host is the session's model server, and a local one
3214
3273
  # (a single-slot Splash or llama.cpp): the same name, or two hosts:
3215
3274
  # entries for one server root (scheme, host, port).
@@ -3270,7 +3329,8 @@ module Samagotchi
3270
3329
  parent_attached: context_parent_attached(session))
3271
3330
  return if jobs.empty?
3272
3331
 
3273
- client = SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :context)
3332
+ client = system_one_recording(SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :context),
3333
+ ContextJudge::JUDGMENT, session, mode: settings.mode)
3274
3334
  return unless client
3275
3335
 
3276
3336
  choice = context_choice(session, log, settings)
@@ -3451,7 +3511,8 @@ module Samagotchi
3451
3511
  turn_author: -> { turn_author },
3452
3512
  # A plugin's prompt section is in the stable part: a full re-read.
3453
3513
  cache_confirm: ->(line, changed) { CacheConfirm.ask(line: line, cost: :full, changed: changed, engine: self) },
3454
- candidate_proposed: ->(_candidate) { judge_late_candidates }
3514
+ candidate_proposed: ->(_candidate) { judge_late_candidates },
3515
+ judgments: -> { @judgments }
3455
3516
  )
3456
3517
  end
3457
3518
 
@@ -43,11 +43,12 @@ module Samagotchi
43
43
  end
44
44
 
45
45
  # Load the installed bundles' plugins into +registries+; one that fails
46
- # goes to +failures+, and the rest still load.
46
+ # goes to +failures+, and the rest still load. The block runs after them,
47
+ # still loading: what it shows is held with theirs.
47
48
  def load_plugins(registries, failures:)
48
49
  @held_events = []
49
50
  @loading = true
50
- Plugin::Loader.load_installed(registries, failures: failures, settings: bundle_settings)
51
+ Plugin::Loader.load_installed(registries, failures: failures, settings: bundle_settings).tap { yield if block_given? }
51
52
  ensure
52
53
  @loading = false
53
54
  end
@@ -44,12 +44,15 @@ module Samagotchi
44
44
  # (a bundle's rules kept because it needs a newer chi)
45
45
  # @param system_one [#call] → SystemOne::Client or nil: the judgment client
46
46
  # (nil while `guardrails.system_one.mode` is off or no host is set)
47
+ # @param system_one_runs [#call] → SystemOne::Runs or nil: where labels
48
+ # and what an ask led to are saved
47
49
  # @param cancel_controller [#call] → the running turn's CancellationController, nil
48
50
  # @param participant [#call] (author) → the participant's
49
51
  # Participants::Entry (participants.json: their name, their grant's
50
52
  # mode), nil for none
51
53
  def initialize(scratch:, hooks:, tools:, session:, model_key:, cancelled:, ask:, model_name: -> {},
52
- notify: ->(_message) {}, system_one: -> {}, cancel_controller: -> {}, participant: ->(_author) {})
54
+ notify: ->(_message) {}, system_one: -> {}, system_one_runs: -> {}, cancel_controller: -> {},
55
+ participant: ->(_author) {})
53
56
  @scratch = scratch
54
57
  @hooks_lookup = hooks
55
58
  @tools_lookup = tools
@@ -60,6 +63,7 @@ module Samagotchi
60
63
  @ask = ask
61
64
  @notify = notify
62
65
  @system_one = system_one
66
+ @system_one_runs = system_one_runs
63
67
  @cancel_controller = cancel_controller
64
68
  @participant = participant
65
69
  @turn_mode = nil
@@ -273,6 +277,7 @@ module Samagotchi
273
277
  config_path: Samagotchi::ConfigFile.global_path,
274
278
  hooks_dir: Hooks::Loader.hooks_dir,
275
279
  context_dir: ContextSources.root,
280
+ runs_dir: File.join(File.dirname(@approvals.path, 2), "system_one"),
276
281
  home_path: ChiHome.path,
277
282
  shim_path: ChiShim.path
278
283
  )
@@ -375,11 +380,13 @@ module Samagotchi
375
380
  # judged is written after it, so the examples are always earlier asks.
376
381
  entries = log.entries
377
382
  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
383
+ # A scratch session saves no run, so nothing hangs a later line on one.
384
+ run_id = SystemOne::Runs.new_id(SystemOne::ApprovalQuestion::JUDGMENT) unless @session_lookup.call&.scratch
378
385
  answers = begin
379
386
  client.ask(state: SystemOne::ApprovalQuestion.state(approval, session_title: @session_lookup.call&.title,
380
387
  entries: entries),
381
388
  questions: { SystemOne::ApprovalQuestion::ID => SystemOne::ApprovalQuestion.question },
382
- cancel_controller: @cancel_controller.call)
389
+ cancel_controller: @cancel_controller.call, run_id: run_id)
383
390
  rescue LLM::RequestCancelled
384
391
  raise
385
392
  rescue StandardError => e
@@ -393,13 +400,14 @@ module Samagotchi
393
400
  auto = system_one_auto_allow?(client, approval, p, entries, targets: targets)
394
401
  decision = system_one_decision(client, auto)
395
402
 
396
- id = log.judgment(session_id: @session_lookup.call&.id,
403
+ id = log.judgment(id: run_id, session_id: @session_lookup.call&.id,
397
404
  rule: approval.rule, source: approval.source, tool: approval.tool,
398
405
  **SystemOne::ApprovalQuestion.call_fields(approval),
399
406
  repo_name: approval.repo_name,
400
407
  p: p, threshold: Config.get("guardrails.system_one.threshold"), model: client.model,
401
408
  latency_ms: latency_ms, decision: decision, origin: "live")
402
409
  # A judgment the log cannot hold is no judgment: the user is asked.
410
+ system_one_run_facts(run_id, approval, targets, id.nil? && auto ? "asked" : decision)
403
411
  { id: id, p: p, auto: auto && !id.nil? }
404
412
  rescue LLM::RequestCancelled
405
413
  raise
@@ -409,6 +417,22 @@ module Samagotchi
409
417
  nil
410
418
  end
411
419
 
420
+ # The saved run's later lines: what the ask led to, and what the gates
421
+ # say of it now, which can't be recomputed later (a rule list changes):
422
+ # a later comparison must tell a sweep of gated asks from ungated ones.
423
+ def system_one_run_facts(run_id, approval, targets, what)
424
+ runs = @system_one_runs.call
425
+ return unless run_id && runs&.on?
426
+
427
+ rule = approval.rule.to_s
428
+ runs.gates(run_id, rule: rule, rule_listed: system_one_rules.include?(rule),
429
+ self_protect_refused: SystemOne::SelfProtect.refuse?(approval, targets: targets),
430
+ threshold: Config.get("guardrails.system_one.threshold"))
431
+ runs.acted(run_id, what)
432
+ rescue StandardError => e
433
+ Samagotchi::Log.warn(:guardrails, "system_one_run_facts_failed", error: "#{e.class}: #{e.message}")
434
+ end
435
+
412
436
  # What the judgment line says it did: "auto" (System 1 answered for the
413
437
  # user), "asked" (on mode, the user decides), "audit" (nothing decided).
414
438
  def system_one_decision(client, auto)
@@ -450,43 +474,24 @@ module Samagotchi
450
474
  []
451
475
  end
452
476
 
453
- # The user's answer to that ask, as a label on the judgment: the scope
454
- # they took, a denial, or none for an ask that was cancelled. A parent
455
- # agent's answer is not the user's: its allow labels nothing, and its
456
- # deny is a label only where the parent could have allowed — a parent
457
- # that was not allowed to permit says nothing about what the user would
458
- # have done (docs/guardrails.md, "System 1").
477
+ # The answer to that ask, as a label on the judgment and on its saved run
478
+ # (SystemOne::ApprovalLabel: which answers are labels, how strong).
459
479
  def system_one_label(judgment, answer, payload)
460
480
  id = judgment && judgment[:id]
461
481
  return nil if id.nil?
462
482
 
463
- scopes = Array(payload[:approval].scopes)
464
- if !answer.is_a?(Samagotchi::QuestionAnswer)
465
- label = "none"
466
- elsif answer.parent_agent?
467
- return nil if parent_allowed?(answer, scopes) || !parent_may_permit?(payload)
468
-
469
- label = "deny"
470
- else
471
- index = answer.selected_indices.first
472
- label = if index && index < scopes.size
473
- scopes[index] == "once" ? "allow_once" : "allow_wide"
474
- else
475
- "deny"
476
- end
477
- end
478
- system_one_log.label(id, label, question_id: (answer.id if answer.is_a?(Samagotchi::QuestionAnswer)))
483
+ label = SystemOne::ApprovalLabel.of(answer, scopes: Array(payload[:approval].scopes),
484
+ parent_may_permit: -> { parent_may_permit?(payload) })
485
+ return nil if label.nil?
486
+
487
+ written = system_one_log.label(id, label.value, question_id: (answer.id if answer.is_a?(Samagotchi::QuestionAnswer)))
488
+ SystemOne::ApprovalLabel.save(@system_one_runs.call, id, label)
489
+ written
479
490
  rescue StandardError => e
480
491
  Samagotchi::Log.warn(:guardrails, "system_one_label_failed", error: "#{e.class}: #{e.message}")
481
492
  nil
482
493
  end
483
494
 
484
- # Whether a parent's answer picked one of the offered scopes.
485
- def parent_allowed?(answer, scopes)
486
- index = answer.selected_indices.first
487
- !index.nil? && index < scopes.size
488
- end
489
-
490
495
  # Whether this session's parent level lets a parent allow a call at all,
491
496
  # and the ask is not one only the user may answer.
492
497
  def parent_may_permit?(payload)
@@ -12,8 +12,9 @@ module Samagotchi
12
12
  # words against, as this process's environment and config.yml name them
13
13
  # (read each call). Each surface keeps its set:
14
14
  # .protected the config dir, the hooks dir, the approval store's
15
- # dir, the installed bundles' dir, attached context: an
16
- # ask only the user may answer (ParentApprovals.chi_files?)
15
+ # dir, the installed bundles' dir, attached context,
16
+ # System 1's saved runs: an ask only the user may answer
17
+ # (ParentApprovals.chi_files?)
17
18
  # .touches .protected and the session repo's git hooks dir: a
18
19
  # rule's touches: chi_dirs (Targets#touches_chi?)
19
20
  # .self_protect .protected and the whole state dir, resolved: what
@@ -27,11 +28,13 @@ module Samagotchi
27
28
  module_function
28
29
 
29
30
  # chi's config dir, the hooks dir, the approval store's dir, the
30
- # installed bundles' dir and attached context.
31
+ # installed bundles' dir, attached context and System 1's saved runs
32
+ # (labels there may train a model: no agent writes them).
31
33
  def protected
32
34
  hooks = begin Hooks::Loader.hooks_dir rescue nil end
33
35
  bundles = begin MemoryPaths.bundles_dir rescue nil end
34
- [ConfigFile.config_dir, hooks, File.join(Paths.state_dir, "guardrails"), bundles, File.join(Paths.state_dir, "context")]
36
+ [ConfigFile.config_dir, hooks, File.join(Paths.state_dir, "guardrails"), bundles, File.join(Paths.state_dir, "context"),
37
+ File.join(Paths.state_dir, "system_one")]
35
38
  .compact.map { |dir| dir.to_s.chomp("/") }.reject(&:empty?).uniq
36
39
  end
37
40
 
@@ -9,7 +9,7 @@ module Samagotchi
9
9
  # Outside, ShellPaths, RmTargets, ReviewPaths, PairCommand, Targets,
10
10
  # ParentApprovals, System 1's SelfProtect). Each surface keeps its own
11
11
  # predicate; this only says where a path lands and whether it is in a
12
- # dir. docs/internals/tool-guardrails.md maps which surface uses which.
12
+ # dir. docs/internals/tool-output-limits.md maps which surface uses which.
13
13
  module PathResolve
14
14
  # How many symlinks .real follows on a path that doesn't exist
15
15
  # (about the kernel's own ELOOP limit).