samagotchi 0.141.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 (165) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +111 -7
  3. data/README.md +2 -1
  4. data/bin/chi +2 -0
  5. data/docs/architecture.md +25 -289
  6. data/docs/bundle-authoring.md +7 -6
  7. data/docs/bundles.md +1232 -0
  8. data/docs/cli.md +51 -13
  9. data/docs/configuration.md +68 -30
  10. data/docs/context.md +12 -12
  11. data/docs/guardrails.md +27 -20
  12. data/docs/hooks.md +28 -9
  13. data/docs/internals/attached-context.md +225 -0
  14. data/docs/internals/background-tasks.md +1 -1
  15. data/docs/internals/bridge.md +380 -0
  16. data/docs/internals/bundles.md +6 -3
  17. data/docs/internals/context-telemetry.md +1 -1
  18. data/docs/internals/engine.md +31 -19
  19. data/docs/internals/participants.md +13 -12
  20. data/docs/internals/prompt-caching.md +12 -12
  21. data/docs/internals/remote-sessions.md +1 -1
  22. data/docs/internals/{tool-guardrails.md → tool-output-limits.md} +21 -2
  23. data/docs/internals/web-push.md +1 -1
  24. data/docs/memory.md +33 -3
  25. data/docs/plugins.md +127 -1231
  26. data/docs/sessions.md +51 -27
  27. data/docs/sub-agent.md +6 -6
  28. data/docs/system-one.md +122 -0
  29. data/docs/testing.md +3 -1
  30. data/lib/samagotchi/bridge.rb +2 -0
  31. data/lib/samagotchi/bundle_command/api_calls.rb +132 -0
  32. data/lib/samagotchi/bundle_command/check.rb +50 -34
  33. data/lib/samagotchi/bundle_command/installed_check.rb +86 -0
  34. data/lib/samagotchi/bundle_command/scaffold.rb +1 -0
  35. data/lib/samagotchi/bundle_settings_check.rb +58 -0
  36. data/lib/samagotchi/bundles/agents-md/manifest.yml +4 -2
  37. data/lib/samagotchi/bundles/agents-md/plugin.rb +1 -1
  38. data/lib/samagotchi/bundles/btw/manifest.yml +4 -2
  39. data/lib/samagotchi/bundles/btw/plugin.rb +1 -1
  40. data/lib/samagotchi/bundles/check-in/manifest.yml +7 -3
  41. data/lib/samagotchi/bundles/check-in/plugin.rb +101 -11
  42. data/lib/samagotchi/bundles/claude-peer/manifest.yml +3 -3
  43. data/lib/samagotchi/bundles/claude-peer/plugin.rb +1 -1
  44. data/lib/samagotchi/bundles/claude-peer/scripts/pair +1 -1
  45. data/lib/samagotchi/bundles/codex-peer/manifest.yml +2 -2
  46. data/lib/samagotchi/bundles/codex-peer/plugin.rb +1 -1
  47. data/lib/samagotchi/bundles/coordinator/manifest.yml +2 -2
  48. data/lib/samagotchi/bundles/coordinator/plugin.rb +1 -1
  49. data/lib/samagotchi/bundles/core/manifest.yml +2 -2
  50. data/lib/samagotchi/bundles/cost-cap/manifest.yml +6 -3
  51. data/lib/samagotchi/bundles/cost-cap/plugin.rb +5 -7
  52. data/lib/samagotchi/bundles/github-pr/manifest.yml +3 -1
  53. data/lib/samagotchi/bundles/known-names/manifest.yml +3 -1
  54. data/lib/samagotchi/bundles/loop-guard/manifest.yml +4 -2
  55. data/lib/samagotchi/bundles/loop-guard/plugin.rb +1 -1
  56. data/lib/samagotchi/bundles/mcp/manifest.yml +4 -2
  57. data/lib/samagotchi/bundles/mcp/plugin.rb +2 -2
  58. data/lib/samagotchi/bundles/ruby/manifest.yml +2 -2
  59. data/lib/samagotchi/bundles/ruby/plugin.rb +1 -1
  60. data/lib/samagotchi/bundles/skills/manifest.yml +4 -2
  61. data/lib/samagotchi/bundles/skills/plugin.rb +1 -1
  62. data/lib/samagotchi/bundles/slow-commands/manifest.yml +4 -2
  63. data/lib/samagotchi/bundles/slow-commands/plugin.rb +1 -1
  64. data/lib/samagotchi/bundles/source-links/manifest.yml +3 -1
  65. data/lib/samagotchi/bundles/system/config_modification_protocol.md +3 -3
  66. data/lib/samagotchi/bundles/system/manifest.yml +4 -4
  67. data/lib/samagotchi/bundles/system/memory_guide.md +1 -1
  68. data/lib/samagotchi/bundles/system/self_map.md +3 -3
  69. data/lib/samagotchi/bundles/work-cap/manifest.yml +6 -3
  70. data/lib/samagotchi/bundles/work-cap/plugin.rb +11 -13
  71. data/lib/samagotchi/config.rb +74 -14
  72. data/lib/samagotchi/context_candidate_choice.rb +20 -3
  73. data/lib/samagotchi/context_candidates.rb +4 -1
  74. data/lib/samagotchi/context_candidates_log.rb +36 -1
  75. data/lib/samagotchi/context_judge.rb +6 -2
  76. data/lib/samagotchi/context_status.rb +1 -2
  77. data/lib/samagotchi/engine.rb +96 -70
  78. data/lib/samagotchi/extension_load.rb +11 -4
  79. data/lib/samagotchi/guardrail_wiring.rb +36 -31
  80. data/lib/samagotchi/guardrails/chi_dirs.rb +7 -4
  81. data/lib/samagotchi/guardrails/path_resolve.rb +1 -1
  82. data/lib/samagotchi/guardrails/protected_paths.rb +7 -4
  83. data/lib/samagotchi/guardrails_command.rb +3 -3
  84. data/lib/samagotchi/hook_routes.rb +37 -2
  85. data/lib/samagotchi/hooks/bundle_loader.rb +20 -4
  86. data/lib/samagotchi/hooks/registry.rb +23 -5
  87. data/lib/samagotchi/host_model.rb +3 -3
  88. data/lib/samagotchi/host_registry.rb +14 -7
  89. data/lib/samagotchi/judgments_command.rb +155 -0
  90. data/lib/samagotchi/kernel_loop.rb +20 -3
  91. data/lib/samagotchi/llm/chat_loop.rb +79 -10
  92. data/lib/samagotchi/llm/errors.rb +7 -5
  93. data/lib/samagotchi/llm/stray_tool_call.rb +68 -0
  94. data/lib/samagotchi/log_line.rb +1 -1
  95. data/lib/samagotchi/memory_bundle/builder.rb +4 -2
  96. data/lib/samagotchi/memory_bundle/entry_size.rb +100 -0
  97. data/lib/samagotchi/memory_bundle/installed_bundle.rb +9 -2
  98. data/lib/samagotchi/memory_bundle/installed_copy.rb +92 -0
  99. data/lib/samagotchi/memory_bundle/installer.rb +2 -0
  100. data/lib/samagotchi/memory_bundle/manifest.rb +23 -13
  101. data/lib/samagotchi/memory_bundle/provenance.rb +4 -1
  102. data/lib/samagotchi/memory_bundle/shipped_update.rb +13 -1
  103. data/lib/samagotchi/model_catalog.rb +3 -2
  104. data/lib/samagotchi/models_command.rb +1 -1
  105. data/lib/samagotchi/plugin/api.rb +41 -7
  106. data/lib/samagotchi/plugin/context.rb +59 -1
  107. data/lib/samagotchi/plugin/judgments.rb +72 -0
  108. data/lib/samagotchi/plugin/loader.rb +6 -3
  109. data/lib/samagotchi/plugin/peer.rb +17 -22
  110. data/lib/samagotchi/plugin_session_state.rb +32 -5
  111. data/lib/samagotchi/prompt_warmup.rb +1 -9
  112. data/lib/samagotchi/run_options.rb +1 -0
  113. data/lib/samagotchi/self_report.rb +36 -0
  114. data/lib/samagotchi/session_access/contract.rb +1 -1
  115. data/lib/samagotchi/session_access/local.rb +1 -1
  116. data/lib/samagotchi/session_access/remote.rb +3 -3
  117. data/lib/samagotchi/session_archive_command.rb +3 -3
  118. data/lib/samagotchi/session_commands.rb +7 -4
  119. data/lib/samagotchi/session_config.rb +9 -3
  120. data/lib/samagotchi/session_continue.rb +1 -1
  121. data/lib/samagotchi/session_manager.rb +25 -5
  122. data/lib/samagotchi/session_retention.rb +10 -0
  123. data/lib/samagotchi/side_judgments.rb +12 -1
  124. data/lib/samagotchi/system_one/answer.rb +63 -11
  125. data/lib/samagotchi/system_one/approval_label.rb +56 -0
  126. data/lib/samagotchi/system_one/approval_question.rb +2 -0
  127. data/lib/samagotchi/system_one/client.rb +43 -17
  128. data/lib/samagotchi/system_one/fake_backend.rb +1 -1
  129. data/lib/samagotchi/system_one/http_backend.rb +12 -4
  130. data/lib/samagotchi/system_one/judgment_settings.rb +61 -0
  131. data/lib/samagotchi/system_one/judgments.rb +243 -0
  132. data/lib/samagotchi/system_one/log.rb +25 -2
  133. data/lib/samagotchi/system_one/recording.rb +117 -0
  134. data/lib/samagotchi/system_one/runs.rb +179 -0
  135. data/lib/samagotchi/system_one/runs_store.rb +230 -0
  136. data/lib/samagotchi/system_one.rb +9 -0
  137. data/lib/samagotchi/terminal_ui/attach_link.rb +2 -2
  138. data/lib/samagotchi/terminal_ui/attached_loop/exit_commands.rb +1 -1
  139. data/lib/samagotchi/terminal_ui/attached_loop.rb +1 -1
  140. data/lib/samagotchi/terminal_ui/local_link.rb +1 -1
  141. data/lib/samagotchi/terminal_ui/remote_link.rb +1 -2
  142. data/lib/samagotchi/testing/bundle.rb +9 -2
  143. data/lib/samagotchi/testing/host.rb +2 -1
  144. data/lib/samagotchi/testing/judgments.rb +176 -0
  145. data/lib/samagotchi/testing/recorder.rb +5 -0
  146. data/lib/samagotchi/testing/recording_api.rb +1 -1
  147. data/lib/samagotchi/tool_output_cut.rb +26 -6
  148. data/lib/samagotchi/tool_response.rb +1 -1
  149. data/lib/samagotchi/tool_runner.rb +63 -4
  150. data/lib/samagotchi/toolkit_suggest.rb +11 -2
  151. data/lib/samagotchi/tools/memory.rb +28 -0
  152. data/lib/samagotchi/turn_note.rb +9 -0
  153. data/lib/samagotchi/update_command.rb +49 -16
  154. data/lib/samagotchi/version.rb +1 -1
  155. data/lib/samagotchi/web/app.rb +1 -0
  156. data/lib/samagotchi/web/auto_update.rb +79 -49
  157. data/lib/samagotchi/web/auto_update_record.rb +59 -0
  158. data/lib/samagotchi/web/public/app.js +8 -4
  159. data/lib/samagotchi/web/public/hash_intent.js +24 -0
  160. data/lib/samagotchi/web/public/index.html +3 -1
  161. data/lib/samagotchi/web/public/revise_stack.js +14 -5
  162. data/lib/samagotchi/web/session_control.rb +3 -3
  163. data/lib/samagotchi/web/update_check.rb +7 -6
  164. data/lib/samagotchi/web/update_ops.rb +80 -25
  165. metadata +23 -2
@@ -48,10 +48,12 @@ module Samagotchi
48
48
  append(line)
49
49
  end
50
50
 
51
- # @param fields [Hash] the judgment's own fields (rule, tool, p, …)
51
+ # @param fields [Hash] the judgment's own fields (rule, tool, p, …); its
52
+ # :id if the caller has one (a saved run's), else a new one
52
53
  # @return [String, nil] the judgment's id, nil when nothing was written
53
54
  def judgment(fields)
54
- id = SecureRandom.uuid
55
+ fields = fields.dup
56
+ id = fields.delete(:id) || SecureRandom.uuid
55
57
  entry("judgment", { "id" => id }.merge(fields)) ? id : nil
56
58
  end
57
59
 
@@ -113,6 +115,27 @@ module Samagotchi
113
115
  []
114
116
  end
115
117
 
118
+ # Drop the lines +keep+ rejects, rewriting the file under the same
119
+ # exclusive lock an append takes. A line that does not parse goes with
120
+ # them: nothing here can read it back.
121
+ # @param keep [#call] (line) — whether to keep a parsed line
122
+ # @return [Integer] how many lines were dropped
123
+ def prune(&)
124
+ with_lock(File::LOCK_EX) do |file|
125
+ lines = file.readlines
126
+ kept = lines.select { |line| (data = parse(line)) && yield(data) }
127
+ out = kept.join
128
+ file.rewind
129
+ file.write(out)
130
+ file.flush
131
+ file.truncate(out.bytesize)
132
+ lines.size - kept.size
133
+ end
134
+ rescue StandardError => e
135
+ warn_about(e)
136
+ 0
137
+ end
138
+
116
139
  private
117
140
 
118
141
  def append(line)
@@ -0,0 +1,117 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "../llm/errors"
4
+ require_relative "../log"
5
+ require_relative "question"
6
+ require_relative "runs"
7
+
8
+ module Samagotchi
9
+ module SystemOne
10
+ # A Client that saves each ask as a run (Runs): the same duck type, the
11
+ # same answers and the same raises. It sits where a use builds its
12
+ # client, so gates, threads and domain logs stay the use's own. A run
13
+ # that can't be saved is one warn and never changes the answer.
14
+ #
15
+ # client = Recording.wrap(Client.from_config(...), judgment: "approvals.allow", runs: runs, context: context)
16
+ # client&.ask(state:, questions:, cancel_controller:)
17
+ class Recording
18
+ # What a run says about its session, taken on the caller's thread:
19
+ # the ask itself may run on its own. +chain_link+ is the parent or the
20
+ # session this one continues (a chain is derived, SessionChain, and
21
+ # following it costs a listing), +session_model+ the session's model.
22
+ Context = Data.define(:session_id, :chain_link, :session_model, :test_run) do
23
+ def initialize(session_id: nil, chain_link: nil, session_model: nil, test_run: nil) = super
24
+
25
+ def to_h = super.transform_keys(&:to_s)
26
+
27
+ def self.of(session, session_model: nil)
28
+ new(session_id: session&.id, chain_link: session&.parent_id || session&.continues,
29
+ session_model: session_model, test_run: session&.test_run ? true : nil)
30
+ end
31
+ end
32
+
33
+ # The wrapped client, or nil for none: the caller's nil check stays.
34
+ # @param recorded_mode [String, nil] the use's mode as a run says it,
35
+ # where the client's isn't it (toolkit and context build theirs "on"
36
+ # in audit too); nil: the client's
37
+ def self.wrap(client, judgment:, runs:, context: Context.new, recorded_mode: nil)
38
+ client && new(client, judgment: judgment, runs: runs, context: context, recorded_mode: recorded_mode)
39
+ end
40
+
41
+ # @param fields [Hash] more for each of its runs (a bundle's judgment's
42
+ # positive: and negative: label values)
43
+ def initialize(client, judgment:, runs:, context: Context.new, recorded_mode: nil, fields: {})
44
+ @client = client
45
+ @judgment = judgment
46
+ @runs = runs
47
+ @context = context
48
+ @recorded_mode = recorded_mode
49
+ @fields = fields
50
+ end
51
+
52
+ def host = @client.host
53
+ def model = @client.model
54
+ def mode = @client.mode
55
+ def backend = @client.backend
56
+
57
+ # Client#ask, recorded. A cancelled ask or one that raises records its
58
+ # run, then raises as before.
59
+ # @param run_id [String, nil] the run's id when the caller needs it at
60
+ # once (it is passed in, not read back: one client serves several
61
+ # threads); nil: a new one
62
+ def ask(state:, questions:, cancel_controller: nil, run_id: nil)
63
+ facts = {}
64
+ started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
65
+ answers = @client.ask(state: state, questions: questions, cancel_controller: cancel_controller,
66
+ observer: ->(**told) { facts.merge!(told) })
67
+ record(run_id, state, questions, answers, facts, started)
68
+ answers
69
+ rescue LLM::RequestCancelled
70
+ record(run_id, state, questions, nil, facts.merge(failure: "cancelled"), started)
71
+ raise
72
+ rescue StandardError => e
73
+ record(run_id, state, questions, nil, facts.merge(failure: e.class.name, failure_text: e.message), started)
74
+ raise
75
+ end
76
+
77
+ # An ask that wasn't made: its run, at once, asked: false, so a later
78
+ # replay can answer the state (docs/system-one.md).
79
+ # @param reason [String] why: the run's +skipped+
80
+ def skip(state:, questions:, reason:, run_id: nil)
81
+ save(questions) do
82
+ { id: run_id || Runs.new_id(@judgment), state: state, asked: false, skipped: reason, model: said(:model) }
83
+ end
84
+ end
85
+
86
+ private
87
+
88
+ def record(run_id, state, questions, answers, facts, started)
89
+ save(questions) do
90
+ { id: run_id || Runs.new_id(@judgment), state: state, asked: true, model: facts[:model] || said(:model),
91
+ served_model: facts[:served_model], answers: facts[:raw] || answers&.transform_values(&:to_h), usage: facts[:usage],
92
+ failure: facts[:failure], failure_text: facts[:failure_text]&.to_s&.slice(0, 500),
93
+ latency_ms: ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round }
94
+ end
95
+ end
96
+
97
+ # One run: the block's fields, and what every run says.
98
+ def save(questions)
99
+ return unless @runs.on?
100
+
101
+ questions = SystemOne.normalize_questions(questions)
102
+ return if questions.empty? # Client#ask asked nothing.
103
+
104
+ @runs.record(judgment: @judgment, questions: questions, **@context.to_h.transform_keys(&:to_sym), **@fields,
105
+ origin: "live", mode: @recorded_mode || said(:mode), host: said(:host), **yield)
106
+ rescue StandardError, SystemStackError => e # a state nested too deep to copy
107
+ # Qualified: inside SystemOne, the bare Log is SystemOne::Log.
108
+ Samagotchi::Log.warn(:system_one, "system_one_run_failed",
109
+ echo: "[samagotchi:system_one] a run wasn't saved: #{e.class}: #{e.message}",
110
+ judgment: @judgment, error: e.class.name)
111
+ end
112
+
113
+ # What the client says about itself; a stand-in may say nothing.
114
+ def said(name) = @client.respond_to?(name) ? @client.public_send(name) : nil
115
+ end
116
+ end
117
+ end
@@ -0,0 +1,179 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "digest"
4
+ require "json"
5
+ require "securerandom"
6
+ require "time"
7
+
8
+ require_relative "../config"
9
+ require_relative "../log"
10
+ require_relative "question"
11
+ require_relative "runs_store"
12
+
13
+ module Samagotchi
14
+ module SystemOne
15
+ # The saved asks: one run per System 1 ask (Recording), what was sent and
16
+ # answered, and later lines on it, for a later comparison or fine-tune
17
+ # (docs/system-one.md). A Runs without a store saves nothing. Local only.
18
+ #
19
+ # A run's id is "<judgment>/<uuid>": it carries its judgment, so a later
20
+ # line can find its way with the id alone. Later lines never hold up the
21
+ # caller: a failed one is one warn and a false.
22
+ class Runs
23
+ # What the specs read: lines in memory, by judgment.
24
+ class MemoryStore
25
+ attr_reader :lines, :versions
26
+
27
+ def initialize
28
+ @lines = Hash.new { |hash, judgment| hash[judgment] = [] }
29
+ @versions = Hash.new { |hash, judgment| hash[judgment] = [] }
30
+ @mutex = Mutex.new
31
+ end
32
+
33
+ def append(judgment, line)
34
+ @mutex.synchronize { @lines[judgment] << line }
35
+ true
36
+ end
37
+
38
+ def version(judgment, line)
39
+ @mutex.synchronize do
40
+ @versions[judgment] << line unless @versions[judgment].include?(line)
41
+ end
42
+ true
43
+ end
44
+ end
45
+
46
+ # Names core keeps (a first word, as a bundle's scope would be) and the
47
+ # suffix a later replay's runs use: a bundle's judgment takes none.
48
+ RESERVED = Config::RESERVED_JUDGMENTS
49
+ RESERVED_SUFFIX = ".replay"
50
+ # The total the sweep keeps (docs/system-one.md).
51
+ MAX_BYTES = 100 * 1024 * 1024
52
+
53
+ # Runs on the state dir +root+ (where the sessions folder sits), saving
54
+ # unless system_one.runs is off.
55
+ def self.in(root)
56
+ new(store: Config.get("system_one.runs").to_s == "off" ? nil : RunsStore.new(root))
57
+ end
58
+
59
+ # .in, from the sessions folder.
60
+ def self.for_sessions_dir(sessions_dir) = self.in(File.dirname(sessions_dir))
61
+
62
+ # The session sweep: runs past session.retention_days (0: forever), then
63
+ # the oldest over the total cap. Whatever system_one.runs says now.
64
+ # @return [Integer] the day files deleted
65
+ def self.sweep_at(root, days: Config.get("session.retention_days").to_i, max_bytes: MAX_BYTES)
66
+ RunsStore.new(root).sweep(days: days, max_bytes: max_bytes)
67
+ end
68
+
69
+ # Explicit `chi sessions delete`: that session's runs and their later
70
+ # lines go, whatever system_one.runs says now.
71
+ def self.purge_session(session_id, sessions_dir:)
72
+ RunsStore.new(File.dirname(sessions_dir)).purge_session(session_id)
73
+ end
74
+
75
+ # Whether a bundle may declare +name+ (safe as a folder, not core's).
76
+ def self.declarable?(name)
77
+ text = name.to_s
78
+ text.match?(RunsStore::NAME) && !RESERVED.include?(text.split(".").first) && !text.end_with?(RESERVED_SUFFIX)
79
+ end
80
+
81
+ # A new run's id.
82
+ def self.new_id(judgment) = "#{judgment}/#{SecureRandom.uuid}"
83
+
84
+ # The judgment a run id carries; nil for anything else (a judgments
85
+ # log's id from before runs, a name that isn't safe as a folder).
86
+ def self.judgment_of(run_id)
87
+ judgment, uuid = run_id.to_s.split("/", 2)
88
+ judgment if judgment.to_s.match?(RunsStore::NAME) && !uuid.to_s.empty?
89
+ end
90
+
91
+ # The digests a run groups by: the questions' wording and, apart, their
92
+ # criteria, which can vary per session (a toolkit's kits).
93
+ # @param questions [Array<Question>]
94
+ # @return [Hash{String => String}]
95
+ def self.digests(questions)
96
+ wording = questions.map { |question| [question.id, question.type.to_s, question.instructions] }
97
+ criteria = questions.map { |question| [question.id, question.criteria] }
98
+ { "instructions_digest" => digest(wording), "criteria_digest" => digest(criteria) }
99
+ end
100
+
101
+ def self.digest(value) = Digest::SHA256.hexdigest(JSON.generate(value))[0, 16]
102
+ private_class_method :digest
103
+
104
+ # A copy +value+ can be written as JSON from: bytes that aren't UTF-8
105
+ # (a command's output in a state) are replaced, in strings and keys.
106
+ def self.scrubbed(value)
107
+ case value
108
+ when String then value.dup.force_encoding(Encoding::UTF_8).scrub("�")
109
+ when Symbol then scrubbed(value.to_s)
110
+ when Hash then value.to_h { |key, item| [scrubbed(key.to_s), scrubbed(item)] }
111
+ when Array then value.map { |item| scrubbed(item) }
112
+ else value
113
+ end
114
+ end
115
+
116
+ # @param store [#append, #version, nil] nil: nothing is saved
117
+ def initialize(store: nil)
118
+ @store = store
119
+ end
120
+
121
+ def on? = !@store.nil?
122
+
123
+ # Save one ask, its questions once per digest pair. Raises what its
124
+ # store raises: Recording holds the one warn.
125
+ # @param id [String] the run's id
126
+ # @param judgment [String] its judgment's name
127
+ # @param questions [Array<Question>] as asked
128
+ # @param fields [Hash] the run's other fields; nil ones are left out
129
+ # @return [Boolean] whether it was saved
130
+ def record(id:, judgment:, questions:, **fields)
131
+ return false unless on?
132
+
133
+ digests = self.class.digests(questions)
134
+ wire = questions.to_h { |question| [question.id, question.to_wire] }
135
+ @store.version(judgment, digests.merge("questions" => self.class.scrubbed(wire)))
136
+ @store.append(judgment, { "kind" => "run", "id" => id, "judgment" => judgment, "at" => now }
137
+ .merge(digests).merge(self.class.scrubbed(fields.compact)))
138
+ end
139
+
140
+ # What the user (or +by+) said about a run.
141
+ # @param value [String] the use's own word
142
+ # @param by [String] who said it
143
+ # @param strength [String, nil] "strong" or "weak", where the use has
144
+ # the difference
145
+ # @param question [String, nil] the question it answers
146
+ # @return [Boolean] whether it was saved
147
+ def label(run_id, value, by:, strength: nil, question: nil)
148
+ later(run_id, "label", value: value, by: by, strength: strength, question: question)
149
+ end
150
+
151
+ # What the use did with the answer: never known when the run is written.
152
+ # @return [Boolean] whether it was saved
153
+ def acted(run_id, what) = later(run_id, "acted", what: what)
154
+
155
+ # What the gates said at ask time, which can't be recomputed later.
156
+ # @return [Boolean] whether it was saved
157
+ def gates(run_id, **fields) = later(run_id, "gates", **fields)
158
+
159
+ private
160
+
161
+ def later(run_id, kind, **fields)
162
+ return false unless on?
163
+
164
+ judgment = self.class.judgment_of(run_id)
165
+ return false if judgment.nil?
166
+
167
+ @store.append(judgment, { "kind" => kind, "run_id" => run_id.to_s, "at" => now }.merge(self.class.scrubbed(fields.compact)))
168
+ rescue StandardError, SystemStackError => e
169
+ # Qualified: inside SystemOne, the bare Log is SystemOne::Log.
170
+ Samagotchi::Log.warn(:system_one, "system_one_run_line_failed",
171
+ echo: "[samagotchi:system_one] a #{kind} line wasn't saved: #{e.class}: #{e.message}",
172
+ judgment: judgment, error: e.class.name)
173
+ false
174
+ end
175
+
176
+ def now = Time.now.utc.iso8601(3)
177
+ end
178
+ end
179
+ end
@@ -0,0 +1,230 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "fileutils"
4
+ require "json"
5
+ require "time"
6
+
7
+ module Samagotchi
8
+ module SystemOne
9
+ # Runs on disk: <state>/system_one/runs/<judgment>/YYYY-MM-DD.jsonl (UTC,
10
+ # 0600), one append under flock per line, read by copying the lines out
11
+ # and parsing outside the lock; each judgment's questions once per digest
12
+ # pair in versions.jsonl beside them. Nothing is rewritten but for a
13
+ # session's purge.
14
+ class RunsStore
15
+ DIR = File.join("system_one", "runs")
16
+ # A judgment's name: safe as a folder name, dot-separated words.
17
+ NAME = /\A[a-z0-9][a-z0-9_-]*(?:\.[a-z0-9][a-z0-9_-]*)*\z/
18
+ VERSIONS = "versions.jsonl"
19
+ DAY_FILE = /\A\d{4}-\d{2}-\d{2}\.jsonl\z/
20
+ FILE_MODE = 0o600
21
+ DIR_MODE = 0o700
22
+ # The longest line: a longer state is saved cut, marked "truncated".
23
+ MAX_LINE_BYTES = 16 * 1024
24
+
25
+ attr_reader :dir
26
+
27
+ # @param root [String] the state dir the sessions folder sits in
28
+ def initialize(root)
29
+ @dir = File.join(root, DIR)
30
+ end
31
+
32
+ # @param line [Hash] with its "at"
33
+ # @return [Boolean] true: raises what the filesystem raises
34
+ def append(judgment, line)
35
+ write(File.join(judgment_dir(judgment), "#{day_of(line)}.jsonl"), fit(line))
36
+ true
37
+ end
38
+
39
+ # +line+ ({digests…, "questions"}) unless the file has its digest pair.
40
+ # @return [Boolean] whether it was new
41
+ def version(judgment, line)
42
+ path = File.join(judgment_dir(judgment), VERSIONS)
43
+ with_file(path) do |file|
44
+ known = file.each_line.any? do |text|
45
+ data = parse(text)
46
+ data && data["instructions_digest"] == line["instructions_digest"] && data["criteria_digest"] == line["criteria_digest"]
47
+ end
48
+ next false if known
49
+
50
+ file.seek(0, IO::SEEK_END)
51
+ file.write("#{JSON.generate(line)}\n")
52
+ true
53
+ end
54
+ end
55
+
56
+ # The judgments with a folder, sorted; a folder that isn't one is left
57
+ # alone, and in no one's way.
58
+ # @return [Array<String>]
59
+ def names
60
+ return [] unless Dir.exist?(@dir)
61
+
62
+ Dir.children(@dir).select { |name| name.match?(NAME) && File.directory?(File.join(@dir, name)) }.sort
63
+ end
64
+
65
+ # Every parseable line, oldest day first.
66
+ # @param since [String, nil] the first day (YYYY-MM-DD) wanted
67
+ # @return [Array<Hash>]
68
+ def lines(judgment, since: nil)
69
+ day_files(judgment).flat_map do |path|
70
+ next [] if since && File.basename(path, ".jsonl") < since
71
+
72
+ read(path).each_line.filter_map { |text| parse(text) }
73
+ end
74
+ end
75
+
76
+ # The questions saved, one line per digest pair.
77
+ # @return [Array<Hash>]
78
+ def versions(judgment)
79
+ path = File.join(judgment_dir(judgment), VERSIONS)
80
+ File.exist?(path) ? read(path).each_line.filter_map { |text| parse(text) } : []
81
+ end
82
+
83
+ # @return [Integer] the judgment's bytes on disk
84
+ def size(judgment)
85
+ Dir.children(judgment_dir(judgment)).sum { |name| File.size(File.join(judgment_dir(judgment), name)) }
86
+ rescue SystemCallError
87
+ 0
88
+ end
89
+
90
+ # Day files past +days+ (0: none), then the oldest until the total is
91
+ # under +max_bytes+, today's stay. A judgment with no day file left
92
+ # loses its versions and folder.
93
+ # @return [Integer] the day files deleted
94
+ def sweep(days:, max_bytes:, now: Time.now.utc)
95
+ return 0 unless Dir.exist?(@dir)
96
+
97
+ today = now.utc.strftime("%F")
98
+ cutoff = (now.utc - (days * 86_400)).strftime("%F") if days.positive?
99
+ files = names.flat_map { |name| day_files(name) }.sort_by { |path| File.basename(path) }
100
+ expired, kept = files.partition { |path| cutoff && File.basename(path, ".jsonl") < cutoff }
101
+ total = names.sum { |name| size(name) } - expired.sum { |path| File.size(path) }
102
+ over = kept.take_while do |path|
103
+ next false if total <= max_bytes || File.basename(path, ".jsonl") >= today
104
+
105
+ total -= File.size(path)
106
+ true
107
+ end
108
+ (expired + over).each { |path| FileUtils.rm_f(path) }
109
+ names.each { |name| remove_if_empty(name) }
110
+ expired.size + over.size
111
+ end
112
+
113
+ # One session's runs and the later lines on them, rewritten out of the
114
+ # day files under the lock.
115
+ # @return [Integer] the runs purged
116
+ def purge_session(session_id)
117
+ needle = session_id.to_s
118
+ return 0 if needle.empty?
119
+
120
+ names.sum do |name|
121
+ files = day_files(name).select { |path| read(path).include?(needle) }
122
+ ids = files.flat_map { |path| session_run_ids(path, needle) }
123
+ next 0 if ids.empty?
124
+
125
+ known = ids.to_h { |id| [id, true] }
126
+ day_files(name).each { |path| rewrite_without(path, known) }
127
+ remove_if_empty(name)
128
+ ids.size
129
+ end
130
+ end
131
+
132
+ private
133
+
134
+ def judgment_dir(judgment)
135
+ name = judgment.to_s
136
+ raise ArgumentError, "not a judgment's name: #{name.inspect}" unless name.match?(NAME)
137
+
138
+ File.join(@dir, name)
139
+ end
140
+
141
+ def day_files(judgment)
142
+ dir = judgment_dir(judgment)
143
+ return [] unless Dir.exist?(dir)
144
+
145
+ Dir.children(dir).grep(DAY_FILE).sort.map { |name| File.join(dir, name) }
146
+ end
147
+
148
+ def day_of(line) = line.fetch("at")[0, 10]
149
+
150
+ # The line as written: past the cap its state is cut, as a string, as
151
+ # little as fits (escaping makes a byte cost more than one in the line:
152
+ # the most that fits is searched for) and marked; a line that doesn't
153
+ # fit with no state at all keeps its facts only.
154
+ def fit(line)
155
+ text = JSON.generate(line)
156
+ return text if text.bytesize <= MAX_LINE_BYTES
157
+
158
+ line = line.merge("truncated" => true)
159
+ state = line["state"].is_a?(String) ? line["state"] : JSON.generate(line["state"])
160
+ cut = ->(bytes) { JSON.generate(line.merge("state" => state.byteslice(0, bytes).scrub(""))) }
161
+ return JSON.generate(line.except("state", "answers", "failure_text")) if cut.call(0).bytesize > MAX_LINE_BYTES
162
+
163
+ bytes = (0..[state.bytesize, MAX_LINE_BYTES].min).bsearch { |size| cut.call(size + 1).bytesize > MAX_LINE_BYTES }
164
+ cut.call(bytes || [state.bytesize, MAX_LINE_BYTES].min)
165
+ end
166
+
167
+ def write(path, text)
168
+ FileUtils.mkdir_p(File.dirname(path), mode: DIR_MODE)
169
+ File.open(path, File::WRONLY | File::APPEND | File::CREAT, FILE_MODE) do |file|
170
+ file.flock(File::LOCK_EX)
171
+ file.write("#{text}\n")
172
+ end
173
+ end
174
+
175
+ def with_file(path)
176
+ FileUtils.mkdir_p(File.dirname(path), mode: DIR_MODE)
177
+ File.open(path, File::RDWR | File::CREAT, FILE_MODE) do |file|
178
+ file.flock(File::LOCK_EX)
179
+ yield file
180
+ end
181
+ end
182
+
183
+ # The file's text, copied out under a shared lock.
184
+ def read(path)
185
+ File.open(path, File::RDONLY) do |file|
186
+ file.flock(File::LOCK_SH)
187
+ file.read
188
+ end
189
+ rescue SystemCallError
190
+ ""
191
+ end
192
+
193
+ def parse(text)
194
+ data = JSON.parse(text)
195
+ data.is_a?(Hash) ? data : nil
196
+ rescue JSON::ParserError
197
+ nil
198
+ end
199
+
200
+ def session_run_ids(path, session_id)
201
+ read(path).each_line.filter_map do |text|
202
+ next unless text.include?(session_id)
203
+
204
+ data = parse(text)
205
+ data["id"] if data && data["kind"] == "run" && data["session_id"] == session_id
206
+ end
207
+ end
208
+
209
+ def rewrite_without(path, ids)
210
+ with_file(path) do |file|
211
+ kept = file.each_line.reject do |text|
212
+ data = parse(text)
213
+ data && (ids[data["id"]] || ids[data["run_id"]])
214
+ end
215
+ file.rewind
216
+ file.write(kept.join)
217
+ file.flush
218
+ file.truncate(file.pos)
219
+ end
220
+ FileUtils.rm_f(path) if File.empty?(path)
221
+ end
222
+
223
+ def remove_if_empty(name)
224
+ return unless day_files(name).empty?
225
+
226
+ FileUtils.rm_rf(judgment_dir(name))
227
+ end
228
+ end
229
+ end
230
+ end
@@ -6,11 +6,16 @@ require_relative "system_one/answer"
6
6
  require_relative "system_one/fake_backend"
7
7
  require_relative "system_one/http_backend"
8
8
  require_relative "system_one/client"
9
+ require_relative "system_one/runs"
10
+ require_relative "system_one/recording"
11
+ require_relative "system_one/judgment_settings"
12
+ require_relative "system_one/judgments"
9
13
  require_relative "system_one/log"
10
14
  require_relative "system_one/record"
11
15
  require_relative "system_one/similar"
12
16
  require_relative "system_one/self_protect"
13
17
  require_relative "system_one/approval_question"
18
+ require_relative "system_one/approval_label"
14
19
 
15
20
  module Samagotchi
16
21
  # System 1: the cheap judgment model that will, one phase at a time,
@@ -20,6 +25,10 @@ module Samagotchi
20
25
  # that passes every gate allows the call once, without asking
21
26
  # (SystemOne::Record, SystemOne::SelfProtect). The line a UI shows for an
22
27
  # auto-allow is P3b (docs/guardrails.md, "System 1").
28
+ # Every core ask goes through SystemOne::Recording, the seam that saves it
29
+ # as a run, with labels and what came of it (SystemOne::Runs, RunsStore;
30
+ # docs/system-one.md). Bundles ask through SystemOne::Judgments, on the same
31
+ # Client and Recording (chi.judgment, ctx.judge).
23
32
  module SystemOne
24
33
  end
25
34
  end
@@ -74,8 +74,8 @@ module Samagotchi
74
74
  # /exit --delete, once the worker let go.
75
75
  def delete_session = raise(NotImplementedError)
76
76
 
77
- # /archive: SessionManager.archive_session's result ({discarded: […]}).
78
- # @return [Hash]
77
+ # /archive: SessionManager.archive_session's result.
78
+ # @return [SessionManager::ArchiveResult]
79
79
  def archive_session = raise(NotImplementedError)
80
80
 
81
81
  # The newest chi installed where the worker runs, for the version line.
@@ -124,7 +124,7 @@ module Samagotchi
124
124
  return detach("#{ExitLines.exit_line(reply, via: via, session_id: id)} Not archived.") unless [200, 409].include?(reply.status)
125
125
 
126
126
  result = @link.archive_session
127
- return detach("Detached; the session was empty, so it is discarded.") if result[:discarded].include?(id)
127
+ return detach("Detached; the session was empty, so it is discarded.") if result.discarded.include?(id)
128
128
 
129
129
  detach("Detached; archived session #{id}. #{via.command("sessions list --archived")} finds it.")
130
130
  rescue SystemCallError, IOError => e
@@ -97,7 +97,7 @@ module Samagotchi
97
97
  # @param now [#call] the wall clock, a Time (the gap dividers)
98
98
  # @param delete_session [#call] session id -> deletes it (/exit --delete)
99
99
  # @param archive_session [#call] session id -> archives it (/archive);
100
- # SessionManager.archive_session's result
100
+ # SessionManager::ArchiveResult
101
101
  # @param wait_at_eof [Boolean] lines come from a pipe or a file (`chi -p
102
102
  # X </dev/null`): at their end, detach only once this run's prompts
103
103
  # (the -p one too) have had their turns; if one failed, #run says so
@@ -33,7 +33,7 @@ module Samagotchi
33
33
  # @param state_dir [String] the state dir the worker was found in
34
34
  # @param delete_session [#call] session id -> deletes it
35
35
  # @param archive_session [#call] session id -> archives it
36
- # (SessionManager.archive_session's result)
36
+ # (SessionManager::ArchiveResult)
37
37
  # @param installed_version [#call] -> the newest chi installed
38
38
  # @param children_counts [#call] session id -> ChildrenStatus::Counts
39
39
  def initialize(client:, state_dir: Session.default_state_dir,
@@ -151,8 +151,7 @@ module Samagotchi
151
151
  raise SessionAccess::WebBridgeClient::Unreachable, e.message
152
152
  end
153
153
 
154
- # /archive: POST …/archive there ({discarded: […]}, as
155
- # SessionManager.archive_session's).
154
+ # /archive: POST …/archive there (a SessionManager::ArchiveResult).
156
155
  def archive_session
157
156
  @remote.archive(session_id)
158
157
  rescue SessionAccess::RemoteFailed => e
@@ -101,7 +101,8 @@ module Samagotchi
101
101
  Plugin::Registries.new(
102
102
  commands: SessionCommands.register_builtins(Commands::Registry.new), tools: Tools::Builtins.registry,
103
103
  services: Plugin::Services.new, stage_tools: ->(*) {}, toolkits: [], tool_index: Tools::ToolIndex.new,
104
- peer_sources: PeerSources.new, prompt_sections: Plugin::PromptSections.new, **fields
104
+ peer_sources: PeerSources.new, prompt_sections: Plugin::PromptSections.new,
105
+ judgments: SystemOne::Judgments.new, **fields
105
106
  )
106
107
  end
107
108
  end
@@ -375,6 +376,11 @@ module Samagotchi
375
376
  # Queue ask_model answers: a String, an exception, or a callable.
376
377
  def model_answers = @recorder.model_answers
377
378
 
379
+ # ctx.judge and ctx.judge_later's System 1, on a FakeBackend: what it
380
+ # answers, and the asks, runs and labels it saw (Testing::Judgments).
381
+ # @return [Judgments]
382
+ def judgments = @recorder.judgments.scoped(@name)
383
+
378
384
  # Queue ask_user answers ({selected:, freeform:, selected_indices:},
379
385
  # or a callable given the HookQuestion).
380
386
  def answer(*answers)
@@ -425,7 +431,8 @@ module Samagotchi
425
431
  @inits << Init.new(label: label, plugin_label: plugin_label, provides_tools: provides_tools, quiet: quiet,
426
432
  timeout: timeout, failed: failed, block: block)
427
433
  },
428
- toolkits: toolkits
434
+ toolkits: toolkits,
435
+ judgments: @recorder.judgments.layer
429
436
  )
430
437
  end
431
438