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
@@ -69,7 +69,8 @@ module Samagotchi
69
69
  },
70
70
  # The candidate judge isn't the bundle's to test: a late proposal
71
71
  # goes nowhere.
72
- candidate_proposed: ->(_candidate) {}
72
+ candidate_proposed: ->(_candidate) {},
73
+ judgments: -> { recorder.judgments.layer }
73
74
  )
74
75
  end
75
76
 
@@ -0,0 +1,176 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "../llm/errors"
4
+ require_relative "../side_judgments"
5
+ require_relative "../system_one/answer"
6
+ require_relative "../system_one/client"
7
+ require_relative "../system_one/errors"
8
+ require_relative "../system_one/fake_backend"
9
+ require_relative "../system_one/judgments"
10
+
11
+ module Samagotchi
12
+ module Testing
13
+ # A ctx.judge or ctx.judge_later that reached System 1. +cancel+ is the
14
+ # controller it would stop with (nil for a judge_later's).
15
+ JudgmentAsk = Data.define(:name, :state, :questions, :cancel)
16
+
17
+ # What bundle.judgments is: chi's real SystemOne::Judgments, Client,
18
+ # Recording and Runs, with a FakeBackend per judgment and the runs in
19
+ # memory. So a judgment's off, skip, busy and failure paths are chi's own.
20
+ # Each judgment is on until the test says otherwise (chi's are off until
21
+ # the user sets a mode, which isn't the bundle's to test).
22
+ #
23
+ # bundle.judgments.answer("progress", noul: 0.9)
24
+ # bundle.fire(:after_turn)
25
+ # bundle.judgments.wait # judge_later's thread, and its block
26
+ # bundle.judgments.asks.last.state
27
+ # bundle.judgments.runs("progress").last["answers"]
28
+ # bundle.judgments.labels("progress").map { _1["value"] }
29
+ class Judgments
30
+ # The backend behind one judgment: records the ask, stops if it's cancelled.
31
+ class Backend < SystemOne::FakeBackend
32
+ def initialize(owner, name)
33
+ @owner = owner
34
+ @name = name
35
+ super() { |state, questions| owner.answers_for(name, state, questions) }
36
+ end
37
+
38
+ def ask(state:, questions:, cancel_controller: nil, observer: nil)
39
+ @owner.asked(JudgmentAsk.new(name: @name, state: state, questions: questions, cancel: cancel_controller))
40
+ raise LLM::RequestCancelled, :manual if cancel_controller&.cancelled?
41
+
42
+ super
43
+ end
44
+ end
45
+
46
+ # @return [SystemOne::Judgments] what the Host and registries hold
47
+ attr_reader :layer
48
+
49
+ # @param recorder [Recorder] the session's values: session_id, scratch,
50
+ # model_name and turn_author are read at each ask
51
+ def initialize(recorder)
52
+ @recorder = recorder
53
+ @scope = nil
54
+ @mutex = Mutex.new
55
+ @answers = Hash.new { |hash, name| hash[name] = {} }
56
+ @failing = {}
57
+ @modes = {}
58
+ @no_host = {}
59
+ @asks = []
60
+ @store = SystemOne::Runs::MemoryStore.new
61
+ @side = SideJudgments.new
62
+ @layer = build_layer
63
+ end
64
+
65
+ # Which bundle's short names these are (Bundle#judgments).
66
+ # @return [Judgments] self
67
+ def scoped(bundle)
68
+ @scope = bundle
69
+ self
70
+ end
71
+
72
+ # What the judgment answers from now on, until the next #answer: the
73
+ # Answer's fields (noul:, choice:, score:, confidence:), or a block given
74
+ # the state and returning them, which may also block, to hold a
75
+ # judge_later in flight. A question with no answer set is no judgment.
76
+ # @param question [String, nil] nil: every question that has none of its own
77
+ # @return [Judgments] self
78
+ def answer(name, question: nil, **fields, &block)
79
+ @mutex.synchronize do
80
+ @answers[full(name)][question&.to_s || :any] = block || fields
81
+ @failing.delete(full(name))
82
+ end
83
+ self
84
+ end
85
+
86
+ # The backend fails from now on, until the next #answer: a failed run.
87
+ # @return [Judgments] self
88
+ def fail(name, error: "fake System 1 is unavailable")
89
+ @mutex.synchronize { @failing[full(name)] = error }
90
+ self
91
+ end
92
+
93
+ # The judgment's mode: "off", "audit" or "on" (the default here).
94
+ # @return [Judgments] self
95
+ def mode(name, word)
96
+ @mutex.synchronize { @modes[full(name)] = word.to_s }
97
+ self
98
+ end
99
+
100
+ # No System 1 host is configured for the judgment.
101
+ # @return [Judgments] self
102
+ def no_host(name)
103
+ @mutex.synchronize { @no_host[full(name)] = true }
104
+ self
105
+ end
106
+
107
+ # Wait for judge_later's asks and blocks, and for the blocks of those
108
+ # that asked nothing.
109
+ # @return [Judgments] self
110
+ def wait(seconds = 5)
111
+ @side.join(seconds)
112
+ self
113
+ end
114
+
115
+ # Every ask that reached System 1, in order.
116
+ # @return [Array<JudgmentAsk>]
117
+ def asks = @mutex.synchronize { @asks.dup }
118
+
119
+ # The runs saved, as chi saves them (docs/system-one.md).
120
+ # @return [Array<Hash>]
121
+ def runs(name) = lines(name, "run")
122
+
123
+ # The label lines saved.
124
+ # @return [Array<Hash>]
125
+ def labels(name) = lines(name, "label")
126
+
127
+ # The acted lines saved.
128
+ # @return [Array<Hash>]
129
+ def acted_lines(name) = lines(name, "acted")
130
+
131
+ # @api private
132
+ def asked(ask)
133
+ @mutex.synchronize { @asks << ask }
134
+ end
135
+
136
+ # @api private: Backend's answers, one per question that has one.
137
+ def answers_for(name, state, questions)
138
+ answers, error = @mutex.synchronize { [@answers[name].dup, @failing[name]] }
139
+ raise SystemOne::BackendError, error if error
140
+
141
+ questions.to_h do |question|
142
+ entry = answers.fetch(question.id) { answers[:any] }
143
+ entry = entry.call(state) if entry.respond_to?(:call)
144
+ [question.id, entry && SystemOne::Answer.new(id: question.id, type: question.type, **entry)]
145
+ end.compact
146
+ end
147
+
148
+ private
149
+
150
+ def lines(name, kind) = @store.lines[full(name)].select { |line| line["kind"] == kind }
151
+
152
+ def full(name)
153
+ name = name.to_s
154
+ @scope && !@layer.declared?(name) ? "#{@scope}.#{name}" : name
155
+ end
156
+
157
+ def build_layer
158
+ SystemOne::Judgments.new(
159
+ settings: ->(name) { @mutex.synchronize { SystemOne::JudgmentSettings.new(mode: @modes.fetch(name, "on")) } },
160
+ client_for: lambda { |name, settings|
161
+ next nil if @mutex.synchronize { @no_host[name] }
162
+
163
+ SystemOne::Client.new(backend: Backend.new(self, name), mode: settings.mode, host: "fake", model: "fake", tag: :plugins)
164
+ },
165
+ runs: -> { SystemOne::Runs.new(store: @recorder[:scratch] ? nil : @store) },
166
+ where: lambda {
167
+ id = @recorder[:session_id]
168
+ id && SystemOne::Recording::Context.new(session_id: id, session_model: @recorder[:model_name])
169
+ },
170
+ side: @side,
171
+ participant: -> { !@recorder[:turn_author].nil? }
172
+ )
173
+ end
174
+ end
175
+ end
176
+ end
@@ -4,6 +4,7 @@ require_relative "../plugin/card"
4
4
  require_relative "../plugin/context"
5
5
  require_relative "../guardrails/parent_policy"
6
6
  require_relative "../hook_question"
7
+ require_relative "judgments"
7
8
 
8
9
  module Samagotchi
9
10
  module Testing
@@ -83,6 +84,10 @@ module Samagotchi
83
84
 
84
85
  def [](key) = @mutex.synchronize { @values.fetch(key) }
85
86
 
87
+ # ctx.judge and ctx.judge_later's System 1 (Testing::Judgments).
88
+ # @return [Judgments]
89
+ def judgments = @mutex.synchronize { @judgments ||= Judgments.new(self) }
90
+
86
91
  # Only stop_turn's, or only stop_generation's.
87
92
  def turn_stops = stops.select { |stop| stop.kind == :turn }
88
93
  def generation_stops = stops.select { |stop| stop.kind == :generation }
@@ -11,7 +11,7 @@ module Samagotchi
11
11
  # The real Plugin::Api, also recording each declaration in order
12
12
  # (#declarations), for a spec of what #register declares as written.
13
13
  class RecordingApi < Plugin::Api
14
- DECLARATIONS = %i[command annotation tool on service init toolkit tool_source peer_source prompt_section].freeze
14
+ DECLARATIONS = %i[command annotation tool on service init toolkit tool_source peer_source prompt_section judgment].freeze
15
15
 
16
16
  # @return [Array<Declaration>]
17
17
  def declarations = (@declarations ||= [])
@@ -9,7 +9,9 @@ module Samagotchi
9
9
  #
10
10
  # :head keeps the first chars and ends with head_line ("[cut: N of M
11
11
  # chars; read it in parts]"): read (which has line ranges) and every tool
12
- # with no policy of its own.
12
+ # with no policy of its own. memory_read's cut (a memory.read_max_chars
13
+ # cap) ends with memory_line instead, which says where the rest is
14
+ # (the memory's .md file, read with start_line): memory_read has no parts.
13
15
  #
14
16
  # :head_tail_file (execute) keeps a short head and a long tail, whole
15
17
  # lines, with one gap line between them, and saves the whole output
@@ -95,9 +97,11 @@ module Samagotchi
95
97
  # +save+ returned (nil when it wasn't called)
96
98
  # @param ref [String, nil] :head_tail_ref: the file the whole text is in
97
99
  # @param ref_stderr [String, nil] :head_tail_ref: its stderr's file, if apart
98
- def apply(output, cap:, tool:, save: nil, ref: nil, ref_stderr: nil, head_chars: HEAD_CHARS)
100
+ # @param line [#call, nil] (kept, total) → the cut line of a :head cut
101
+ # (head_line when nil): memory_read's names the memory file
102
+ def apply(output, cap:, tool:, save: nil, ref: nil, ref_stderr: nil, head_chars: HEAD_CHARS, line: nil)
99
103
  kind = policy(tool)
100
- return [head(output, cap), nil] if kind == :head || cap < MIN_TAIL * 3
104
+ return [head(output, cap, line: line), nil] if kind == :head || cap < MIN_TAIL * 3
101
105
 
102
106
  if kind == :head_tail_ref
103
107
  text = head_tail(output, cap: cap, blocks: [Block.new(from: 0, length: output.length)], head_chars: head_chars,
@@ -137,10 +141,26 @@ module Samagotchi
137
141
  # +output+ cut to +cap+ chars, the cut line included: the model knows
138
142
  # what it didn't get. A cap smaller than the line keeps +cap+ chars and
139
143
  # the line goes past it.
140
- def head(output, cap)
141
- keep = cap - head_line(cap, output.length).length
144
+ # @param line [#call, nil] (kept, total) → the cut line, head_line when nil
145
+ def head(output, cap, line: nil)
146
+ line ||= method(:head_line)
147
+ keep = cap - line.call(cap, output.length).length
142
148
  keep = cap unless keep.positive?
143
- "#{output[0, keep]}#{head_line(keep, output.length)}"
149
+ "#{output[0, keep]}#{line.call(keep, output.length)}"
150
+ end
151
+
152
+ # memory_read's cut line: the rest is in the memory's file, which read
153
+ # takes with start_line. +where+ names the memory dir(s) searched
154
+ # ("the memory .md file" for one name, "the .md files" for a list or the
155
+ # indexes).
156
+ # @param dirs [Array<String>] the memories dirs searched
157
+ # @param single [Boolean] one memory name was read
158
+ # @return [#call] a +line+ for head/apply
159
+ def memory_line(dirs, single:)
160
+ what = single ? "the memory's .md file" : "the memories' .md files"
161
+ lambda do |kept, total|
162
+ "\n[cut: #{kept} of #{total} chars; the rest is in #{what} in #{dirs.join(" or ")}: read it with start_line]"
163
+ end
144
164
  end
145
165
 
146
166
  def head_line(kept, total)
@@ -6,7 +6,7 @@ module Samagotchi
6
6
  # what the model gets back is per format: the native loop answers a batch
7
7
  # with ONE tool_response (#joined), the chat loop each call with its own,
8
8
  # paired by tool_call_id (#single). Both feed the capped outputs
9
- # (max_tool_output_chars).
9
+ # (max_tool_output_chars; memory_read's is memory.read_max_chars).
10
10
  module ToolResponse
11
11
  SEPARATOR = "\n\n---\n\n"
12
12
  # Saved with a result for the web's reload (a plugin tool's params line,
@@ -12,8 +12,11 @@ require_relative "tool_output_cut"
12
12
  require_relative "tool_output_files"
13
13
  require_relative "tools/output_guardrails"
14
14
  require_relative "tools/tool_path"
15
+ require_relative "tools/memory"
16
+ require_relative "config"
15
17
  require_relative "memory_bundle/index_sync"
16
18
  require_relative "memory_bundle/index_size"
19
+ require_relative "memory_bundle/entry_size"
17
20
  require_relative "participant_mode"
18
21
 
19
22
  module Samagotchi
@@ -37,7 +40,8 @@ module Samagotchi
37
40
  # and their veto), dispatch through KernelLoop, the after_tool_call hook
38
41
  # and the output cap. Both loops feed the model `capped_output:` (cut to
39
42
  # the cap by the tool's ToolOutputCut policy, with a "[cut: …]" line),
40
- # the text the event and the hook get too.
43
+ # the text the event and the hook get too. memory_read has its own cap,
44
+ # memory.read_max_chars (0: none), not max_tool_output_chars.
41
45
  class ToolRunner
42
46
  # More images in one result are left out, each with a line (a tool
43
47
  # that returns many screenshots can't flood the context).
@@ -51,9 +55,14 @@ module Samagotchi
51
55
  # the kernel is built.
52
56
  # @param clock [#call] monotonic seconds, for the approval wait and the
53
57
  # dispatch time (after_tool_call's elapsed_ms)
54
- def initialize(kernel, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
58
+ # @param window [#call, nil] → ContextWindow::Resolved or nil: the
59
+ # model's window, for memory_read's overflow guard. nil: the kernel's
60
+ # own reader (KernelLoop#tool_output_window); a loop whose window comes
61
+ # from more than the kernel's client (LLM::ChatLoop's adapter) passes it.
62
+ def initialize(kernel, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }, window: nil)
55
63
  @kernel = kernel
56
64
  @clock = clock
65
+ @window = window
57
66
  end
58
67
 
59
68
  # @param call_index [Integer] 1-based position of the call in its batch
@@ -115,6 +124,7 @@ module Samagotchi
115
124
  end
116
125
  before = verdict.deny? ? NOT_AN_EDIT : file_before(call)
117
126
  index_before = before.equal?(NOT_AN_EDIT) ? nil : memory_index_size(call)
127
+ entry_before = before.equal?(NOT_AN_EDIT) ? nil : MemoryBundle::EntrySize.measure_file(Tools::ToolPath.normalize(call[:path]))
118
128
  elapsed_ms = nil
119
129
  if verdict.deny?
120
130
  result = denied(call, verdict)
@@ -126,6 +136,7 @@ module Samagotchi
126
136
  diff = file_change(call, before)
127
137
  if diff && refresh_memory_index(call)
128
138
  result = with_index_note(result, index_before, call)
139
+ result = with_entry_note(result, entry_before, call)
129
140
  end
130
141
  result = approved(result, verdict) if verdict.allow? && verdict.decided_by
131
142
  result, images = attach_images(call, result) if result[:images]
@@ -139,8 +150,9 @@ module Samagotchi
139
150
  if (changed = changed_call_line(original, call))
140
151
  output = "#{changed}\n#{output}"
141
152
  end
142
- truncated = !max_tool_output_chars.nil? && output.length > max_tool_output_chars
143
- capped, saved = truncated ? cut(call, output, max_tool_output_chars, result) : output
153
+ cap = output_cap(call, max_tool_output_chars)
154
+ truncated = !cap.nil? && output.length > cap
155
+ capped, saved = truncated ? cut(call, output, cap, result) : output
144
156
  output_file = saved.path if saved.is_a?(ToolOutputFiles::Saved)
145
157
 
146
158
  # The call's outcome as its activity line has it (worked out from the
@@ -197,11 +209,48 @@ module Samagotchi
197
209
  # there is none) when it was cut that way
198
210
  def cut(call, output, cap, result)
199
211
  ToolOutputCut.apply(output, cap: cap, tool: call[:name], save: ->(text, dry: false) { save_output(call, text, dry: dry) },
212
+ line: (memory_cut_line(call) if call[:name] == MEMORY_READ),
200
213
  ref: result[:ref_path], ref_stderr: result[:ref_stderr_path],
201
214
  head_chars: Tools::OutputGuardrails.config_positive_int("execute.cut_head_chars",
202
215
  ToolOutputCut::HEAD_CHARS))
203
216
  end
204
217
 
218
+ MEMORY_READ = Tools::MemoryRead::NAME
219
+
220
+ # The most chars +call+'s result may hold: +cap+ (max_tool_output_chars)
221
+ # for every tool but memory_read, which memory.read_max_chars caps (0:
222
+ # no fixed cap) and, with none set, a known window's half (#window_guard).
223
+ # A nil +cap+ stays nil.
224
+ def output_cap(call, cap)
225
+ return cap unless cap && call[:name] == MEMORY_READ
226
+
227
+ fixed = Config.get("memory.read_max_chars").to_i
228
+ fixed.positive? ? fixed : window_guard
229
+ end
230
+
231
+ # Half the model's context window in characters, the most one memory_read
232
+ # result may take: a context overflow fails the turn (its work rolls back
233
+ # and a retry repeats the read). nil when the window isn't known (the
234
+ # default isn't a window) or can't be read. It checks this result, not the
235
+ # context already used.
236
+ def window_guard
237
+ window = @window ? @window.call : (@kernel.tool_output_window if @kernel.respond_to?(:tool_output_window))
238
+ return nil unless window&.tokens&.positive? && window.source != :default
239
+
240
+ (window.tokens * MemoryBundle::IndexSize.chars_per_token / 2).floor
241
+ rescue StandardError
242
+ nil
243
+ end
244
+
245
+ # memory_read's cut line: the rest is in the memory's file, in the dir(s)
246
+ # the call searched (a scope, else project then system).
247
+ def memory_cut_line(call)
248
+ scope = call[:scope].to_s.strip
249
+ scopes = Tools::VALID_SCOPES.include?(scope) ? [scope] : Tools::VALID_SCOPES
250
+ names = Tools::MemoryRead.parse_names(call[:content].to_s)
251
+ ToolOutputCut.memory_line(scopes.map { |s| Tools::MemoryRead.memories_dir(s) }, single: names.size == 1)
252
+ end
253
+
205
254
  # The whole output in the session's tool_output folder
206
255
  # (ToolOutputFiles), or why it isn't saved: no session (a bare kernel)
207
256
  # or the error's class. Never fails the call. +dry+: where it would go,
@@ -275,6 +324,16 @@ module Samagotchi
275
324
  note ? result.merge(output: "#{result[:output]}\n\n#{note}") : result
276
325
  end
277
326
 
327
+ # +result+ with the note a write/edit gets when it took the memory over
328
+ # memory.entry_warn_tokens (MemoryBundle::EntrySize). It is apart from
329
+ # the index's: that one is off with index_warn_tokens at 0, this one isn't.
330
+ def with_entry_note(result, before, call)
331
+ return result unless before
332
+
333
+ note = MemoryBundle::EntrySize.crossing_note(before, MemoryBundle::EntrySize.measure_file(Tools::ToolPath.normalize(call[:path])))
334
+ note ? result.merge(output: "#{result[:output]}\n\n#{note}") : result
335
+ end
336
+
278
337
  # A tool's output can hold bytes that aren't UTF-8 (`printf '\xff'`, a
279
338
  # binary file). They become "?" here, before the output reaches the
280
339
  # conversation, the events and the saved session: JSON.generate raises
@@ -6,6 +6,7 @@ require_relative "cancellation_controller"
6
6
  require_relative "log"
7
7
  require_relative "owner_prompt"
8
8
  require_relative "system_one/question"
9
+ require_relative "system_one/runs"
9
10
  require_relative "toolkit"
10
11
 
11
12
  module Samagotchi
@@ -17,6 +18,8 @@ module Samagotchi
17
18
  class ToolkitSuggest
18
19
  FILE = "toolkit_suggestions.jsonl"
19
20
  QUESTION_ID = "toolkit"
21
+ # Its saved asks' name (SystemOne::Runs).
22
+ JUDGMENT = "toolkit.suggest"
20
23
  PROMPT_MAX = 1500
21
24
  CHARS_PER_TOKEN = 4.0
22
25
  INSTRUCTIONS = "A user is starting a session of a coding agent with the prompt in the state. " \
@@ -121,8 +124,9 @@ module Samagotchi
121
124
  question, = question(default: Toolkit.new(name: snapshot.default.name),
122
125
  kits: snapshot.candidates.to_h { |candidate| [candidate.name, kit_for(candidate)] },
123
126
  project: snapshot.state.fetch(:project), prompt: snapshot.state.fetch(:prompt))
127
+ run_id = SystemOne::Runs.new_id(JUDGMENT)
124
128
  answer = client.ask(state: snapshot.state, questions: { QUESTION_ID => question },
125
- cancel_controller: cancel_controller)&.fetch(QUESTION_ID, nil)
129
+ cancel_controller: cancel_controller, run_id: run_id)&.fetch(QUESTION_ID, nil)
126
130
  raw = answer&.choice
127
131
  candidate_name = raw.to_s.delete_prefix("kit:")
128
132
  candidate = snapshot.candidates.find { |item| item.name == candidate_name } if raw.to_s.start_with?("kit:")
@@ -148,6 +152,7 @@ module Samagotchi
148
152
  end
149
153
  fields = {
150
154
  session_id: snapshot.session_id,
155
+ run_id: run_id,
151
156
  turn_number: snapshot.turn_number,
152
157
  default_kit: snapshot.default.name,
153
158
  raw: raw,
@@ -194,8 +199,11 @@ module Samagotchi
194
199
  # @return [CancellationController] what the ask's request watches
195
200
  attr_reader :cancel_controller
196
201
 
197
- def initialize(log:, timeout_seconds:, joined:, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
202
+ # @param acted [#call, nil] (judged, did), once, as its line is written
203
+ # with what the turn did: the saved run's acted line
204
+ def initialize(log:, timeout_seconds:, joined:, acted: nil, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
198
205
  @log = log
206
+ @acted = acted
199
207
  @clock = clock
200
208
  @deadline = clock.call + timeout_seconds.to_f
201
209
  @joined = joined
@@ -284,6 +292,7 @@ module Samagotchi
284
292
 
285
293
  @recorded = true
286
294
  ToolkitSuggest.record(@log, @judged, did: did)
295
+ @acted&.call(@judged, did) unless did.nil?
287
296
  end
288
297
  end
289
298
 
@@ -234,6 +234,8 @@ module Samagotchi
234
234
  # The index's size before the write, for the note on crossing
235
235
  # memory.index_warn_tokens (not for the verbatim index write).
236
236
  before = index_size(resolved_scope) unless entry_name == MEMORY_INDEX
237
+ # And the memory's own size, for memory.entry_warn_tokens.
238
+ entry_before = entry_size(resolved_scope, entry_name, file_path) unless entry_name == MEMORY_INDEX
237
239
  if entry_name == MEMORY_INDEX
238
240
  Samagotchi::MemoryBundle::IndexUpdater.locked_write(dir) { body }
239
241
  else
@@ -248,6 +250,7 @@ module Samagotchi
248
250
  message += " Index line refreshed automatically."
249
251
  message += index_crossing_note(before, resolved_scope)
250
252
  end
253
+ message += entry_crossing_note(entry_before, resolved_scope, entry_name, body) if entry_before
251
254
 
252
255
  message
253
256
  rescue StandardError => e
@@ -319,6 +322,31 @@ module Samagotchi
319
322
  size.measure(scope) if size.warn_limit.positive?
320
323
  end
321
324
 
325
+ # The memory +name+ as its file is now (0 tokens when it isn't there), nil
326
+ # when memory.entry_warn_tokens is off, for a model note (its own
327
+ # warning) or when it can't be measured.
328
+ def self.entry_size(scope, name, file_path)
329
+ require_relative "../memory_bundle/entry_size"
330
+ size = Samagotchi::MemoryBundle::EntrySize
331
+ return nil unless size.warn_limit.positive? && size.counted?(name)
332
+
333
+ size.of_text(name, scope, File.file?(file_path) ? File.read(file_path, encoding: "UTF-8") : "")
334
+ rescue StandardError
335
+ nil
336
+ end
337
+
338
+ # "\n\nNote: memory '<name>' is now ~N tokens …" when the write took
339
+ # the memory from at or under memory.entry_warn_tokens to over it
340
+ # (+before+: its size before the write), else "". +body+ is what was
341
+ # written.
342
+ def self.entry_crossing_note(before, scope, name, body)
343
+ size = Samagotchi::MemoryBundle::EntrySize
344
+ note = size.crossing_note(before, size.of_text(name, scope, body))
345
+ note ? "\n\n#{note}" : ""
346
+ rescue StandardError
347
+ ""
348
+ end
349
+
322
350
  # "\n\nNote: the <scope> memory index is now ~N tokens …" when the
323
351
  # write took +scope+'s index from at or under memory.index_warn_tokens
324
352
  # to over it (+before+: its size before the write), else "".
@@ -205,6 +205,15 @@ module Samagotchi
205
205
  "or answer if it is done."))
206
206
  end
207
207
 
208
+ # The hidden nudge before a retry of a reply that came back as a tool call
209
+ # written as text, which the host could not read (ChatLoop's
210
+ # LLM::StrayToolCall): nothing ran, and the text is not in the history, so
211
+ # the model is told what it is being asked for again.
212
+ def malformed_retry
213
+ retry_nudge(message("your last reply was a tool call written as plain text, and the host could not read it, " \
214
+ "so nothing ran. Call the tool again as a real tool call, or answer in plain text."))
215
+ end
216
+
208
217
  # The hidden nudge before a retry of a generation a plugin cut
209
218
  # (stop_generation): +by+ is the bundle, +reason+ what it said.
210
219
  def cut_retry(by, reason)