samagotchi 0.155.0 → 0.156.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 (124) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +14 -1
  3. data/bin/chi +1 -1
  4. data/docs/architecture.md +10 -6
  5. data/docs/internals/anthropic.md +1 -1
  6. data/docs/internals/attached-context.md +3 -2
  7. data/docs/internals/background-tasks.md +1 -1
  8. data/docs/internals/engine.md +625 -935
  9. data/docs/internals/llm-context-forget.md +8 -3
  10. data/docs/internals/objectives.md +2 -2
  11. data/docs/internals/prompt-caching.md +4 -1
  12. data/docs/internals/remote-sessions.md +3 -1
  13. data/docs/internals/working-set.md +1 -1
  14. data/docs/sessions.md +2 -2
  15. data/docs/system-one.md +3 -2
  16. data/lib/samagotchi/bootstrap/config_writer.rb +1 -1
  17. data/lib/samagotchi/broadcast_command.rb +3 -3
  18. data/lib/samagotchi/bundle_command/try/sandbox.rb +1 -1
  19. data/lib/samagotchi/bundles/system/config_modification_protocol.md +2 -2
  20. data/lib/samagotchi/bundles/system/manifest.yml +2 -2
  21. data/lib/samagotchi/child_move.rb +7 -51
  22. data/lib/samagotchi/children_status.rb +1 -1
  23. data/lib/samagotchi/cli/parent_wait.rb +1 -1
  24. data/lib/samagotchi/config.rb +17 -112
  25. data/lib/samagotchi/context_command.rb +1 -2
  26. data/lib/samagotchi/context_window.rb +3 -3
  27. data/lib/samagotchi/desktop/macos.rb +1 -1
  28. data/lib/samagotchi/engine/context_judge.rb +19 -11
  29. data/lib/samagotchi/engine/messages.rb +1 -1
  30. data/lib/samagotchi/engine/models.rb +5 -2
  31. data/lib/samagotchi/engine/objectives.rb +29 -11
  32. data/lib/samagotchi/engine/side_requests.rb +21 -11
  33. data/lib/samagotchi/engine/toolkit.rb +10 -9
  34. data/lib/samagotchi/engine/turn_end.rb +1 -1
  35. data/lib/samagotchi/engine/turn_helpers.rb +7 -7
  36. data/lib/samagotchi/engine/verify.rb +1 -1
  37. data/lib/samagotchi/engine.rb +14 -9
  38. data/lib/samagotchi/guardrails/targets.rb +24 -9
  39. data/lib/samagotchi/host_config.rb +72 -1
  40. data/lib/samagotchi/host_model.rb +2 -6
  41. data/lib/samagotchi/host_registry.rb +1 -1
  42. data/lib/samagotchi/kernel_loop.rb +46 -121
  43. data/lib/samagotchi/llm/anthropic_wire.rb +2 -2
  44. data/lib/samagotchi/llm/chat_loop.rb +34 -18
  45. data/lib/samagotchi/llm/native_backend.rb +1 -1
  46. data/lib/samagotchi/llm_context_apply.rb +54 -1
  47. data/lib/samagotchi/llm_context_notice.rb +1 -1
  48. data/lib/samagotchi/llm_context_strategy.rb +7 -9
  49. data/lib/samagotchi/llm_context_view.rb +9 -0
  50. data/lib/samagotchi/model_price.rb +4 -10
  51. data/lib/samagotchi/model_profile.rb +6 -6
  52. data/lib/samagotchi/model_settings.rb +37 -2
  53. data/lib/samagotchi/note_command.rb +1 -2
  54. data/lib/samagotchi/objectives_audit.rb +4 -3
  55. data/lib/samagotchi/participants.rb +2 -2
  56. data/lib/samagotchi/plugin/context.rb +1 -1
  57. data/lib/samagotchi/plugin/sessions.rb +2 -5
  58. data/lib/samagotchi/plugin/tool_spec.rb +5 -3
  59. data/lib/samagotchi/project_env.rb +1 -1
  60. data/lib/samagotchi/reasoning_history.rb +3 -3
  61. data/lib/samagotchi/reminder_carry.rb +1 -1
  62. data/lib/samagotchi/reprefill_meter.rb +45 -0
  63. data/lib/samagotchi/review_command.rb +1 -1
  64. data/lib/samagotchi/sampling_settings.rb +3 -3
  65. data/lib/samagotchi/self_report.rb +7 -7
  66. data/lib/samagotchi/session.rb +50 -7
  67. data/lib/samagotchi/session_access/local.rb +7 -5
  68. data/lib/samagotchi/session_access/remote.rb +17 -3
  69. data/lib/samagotchi/session_archive_command.rb +2 -2
  70. data/lib/samagotchi/session_chain.rb +7 -6
  71. data/lib/samagotchi/session_continue.rb +6 -5
  72. data/lib/samagotchi/session_delete_command.rb +1 -1
  73. data/lib/samagotchi/session_manager/delivery.rb +254 -0
  74. data/lib/samagotchi/session_manager/emptiness.rb +138 -0
  75. data/lib/samagotchi/session_manager/lifecycle.rb +274 -0
  76. data/lib/samagotchi/session_manager/listing.rb +189 -0
  77. data/lib/samagotchi/session_manager/removal.rb +190 -0
  78. data/lib/samagotchi/session_manager/spawn.rb +242 -0
  79. data/lib/samagotchi/session_manager/worker_command.rb +157 -0
  80. data/lib/samagotchi/session_manager.rb +26 -1540
  81. data/lib/samagotchi/session_metrics.rb +1 -1
  82. data/lib/samagotchi/sessions_command.rb +1 -1
  83. data/lib/samagotchi/share_command.rb +1 -1
  84. data/lib/samagotchi/starting_marker.rb +65 -0
  85. data/lib/samagotchi/steer_cut_after.rb +3 -3
  86. data/lib/samagotchi/system_one/recorder.rb +49 -0
  87. data/lib/samagotchi/terminal_ui/exit_lines.rb +1 -1
  88. data/lib/samagotchi/terminal_ui.rb +2 -6
  89. data/lib/samagotchi/testing/sessions.rb +1 -1
  90. data/lib/samagotchi/thinking.rb +3 -3
  91. data/lib/samagotchi/token_usage.rb +1 -1
  92. data/lib/samagotchi/tool_activity.rb +10 -4
  93. data/lib/samagotchi/tool_declarations.rb +2 -2
  94. data/lib/samagotchi/tool_output_cut.rb +17 -0
  95. data/lib/samagotchi/tool_runner.rb +7 -4
  96. data/lib/samagotchi/toolkit_command.rb +1 -1
  97. data/lib/samagotchi/tools/delegate.rb +10 -5
  98. data/lib/samagotchi/tools/delegate_result.rb +4 -4
  99. data/lib/samagotchi/tools/index_hint.rb +14 -0
  100. data/lib/samagotchi/tools/registry.rb +28 -11
  101. data/lib/samagotchi/tools/send_note.rb +4 -6
  102. data/lib/samagotchi/tools/tool_index.rb +52 -51
  103. data/lib/samagotchi/tools/tool_surface.rb +22 -8
  104. data/lib/samagotchi/turn_context.rb +2 -1
  105. data/lib/samagotchi/turn_stages/context_judge.rb +38 -36
  106. data/lib/samagotchi/turn_stages/objectives.rb +56 -52
  107. data/lib/samagotchi/turn_stages/toolkit_suggestion.rb +13 -17
  108. data/lib/samagotchi/turn_stages/verify_anchors.rb +9 -10
  109. data/lib/samagotchi/turn_stages/warmup.rb +14 -15
  110. data/lib/samagotchi/version.rb +1 -1
  111. data/lib/samagotchi/vision_support.rb +3 -3
  112. data/lib/samagotchi/web/app.rb +15 -8
  113. data/lib/samagotchi/web/participant_access.rb +2 -2
  114. data/lib/samagotchi/web/session_access_routes.rb +3 -3
  115. data/lib/samagotchi/web/session_control.rb +3 -3
  116. data/lib/samagotchi/web/session_create.rb +3 -3
  117. data/lib/samagotchi/web/session_hub.rb +1 -1
  118. data/lib/samagotchi/web/session_show.rb +3 -3
  119. data/lib/samagotchi/web/session_summary.rb +3 -4
  120. data/lib/samagotchi/worker.rb +55 -27
  121. data/lib/samagotchi/worker_boot.rb +184 -0
  122. data/lib/samagotchi/worker_signals.rb +1 -1
  123. data/lib/samagotchi/worker_task_wakes.rb +2 -2
  124. metadata +13 -1
@@ -142,7 +142,7 @@ module Samagotchi
142
142
  :cached_sum,
143
143
  :cache_write_sum,
144
144
  # What the server prefilled again of the previous request's prompt
145
- # (KernelLoop#reprefilled_tokens; an LLM context edit's cache break).
145
+ # (ReprefillMeter#tokens; an LLM context edit's cache break).
146
146
  :reprefill_sum,
147
147
  :reasoning_sum,
148
148
  :cost_sum,
@@ -302,7 +302,7 @@ module Samagotchi
302
302
  waiting = s.waiting_question(live: !!live)
303
303
  status = if waiting&.dig(:relayed_to) then "waiting (in parent #{waiting[:relayed_to]})"
304
304
  elsif waiting then "waiting"
305
- else s.status
305
+ else s.displayed_status(owner: Samagotchi::SessionManager.session_owner(s.id, state_dir: state_dir))
306
306
  end
307
307
  "#{s.id} #{status.ljust(8)} #{ctx.call(s).ljust(8)} #{s.updated_at} #{list_text.call(s)}#{flag}#{child}"
308
308
  end
@@ -101,7 +101,7 @@ module Samagotchi
101
101
  error_line("#{command_name}: #{e.message}")
102
102
  CLI::Exit::FAILED
103
103
  rescue ArgumentError => e
104
- error_line("#{command_name}: #{e.is_a?(Session::AmbiguousId) ? e.message : e.message.sub(/\ASession not found: /, "no session ")}")
104
+ error_line("#{command_name}: #{e.message}")
105
105
  CLI::Exit::FAILED
106
106
  end
107
107
 
@@ -0,0 +1,65 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "fileutils"
4
+ require "json"
5
+ require "time"
6
+ require_relative "atomic_file"
7
+ require_relative "session"
8
+
9
+ module Samagotchi
10
+ # A continue's "starting" marker on its new link: written before the
11
+ # continue moves delegates there (ChildMove) and spawns the link's worker,
12
+ # removed by that worker once it holds the owner lock (Worker#start). While
13
+ # it is #fresh?, nothing else spawns a worker for the link (SpawnPart's
14
+ # resume_session and wake_for_report): a ring from a moved child must not
15
+ # start a second one. CROSS-VERSION: the file name and its {pid, at} are
16
+ # read and cleared by other chi versions (spec/worker_contract_spec.rb).
17
+ module StartingMarker
18
+ # <new link dir>/starting: {pid, at}, from the move to the worker's spawn.
19
+ FILE = "starting"
20
+ # A starting marker older than this, or whose process is gone, is left
21
+ # over from a continue that died: it holds nothing back.
22
+ STALE = 60.0
23
+
24
+ module_function
25
+
26
+ # Hold off a worker for the continue's new link (#fresh?) until its
27
+ # own worker holds it: written before the move, removed by that worker
28
+ # once it has the owner lock (Worker#start).
29
+ def mark(session_id, state_dir:)
30
+ dir = Session.session_dir(session_id, state_dir: state_dir)
31
+ FileUtils.mkdir_p(dir)
32
+ AtomicFile.write(File.join(dir, FILE), JSON.generate({ "pid" => Process.pid, "at" => Time.now.iso8601(3) }))
33
+ end
34
+
35
+ def clear(session_id, state_dir:)
36
+ FileUtils.rm_f(File.join(Session.session_dir(session_id, state_dir: state_dir), FILE))
37
+ end
38
+
39
+ # Whether a continue is moving delegates to +session_id+ right now: its
40
+ # marker is there, fresh, and the process that wrote it runs.
41
+ def fresh?(session_id, state_dir:)
42
+ file = File.join(Session.session_dir(session_id, state_dir: state_dir), FILE)
43
+ return false unless File.exist?(file)
44
+
45
+ data = JSON.parse(File.read(file))
46
+ return false if Time.now - Time.iso8601(data["at"].to_s) > STALE
47
+
48
+ process_alive?(data["pid"].to_i)
49
+ rescue JSON::ParserError, ArgumentError, SystemCallError
50
+ false
51
+ end
52
+
53
+ # Signal 0 only asks whether the process exists.
54
+ def process_alive?(pid)
55
+ return false unless pid.positive?
56
+
57
+ Process.kill(0, pid)
58
+ true
59
+ rescue Errno::ESRCH
60
+ false
61
+ rescue Errno::EPERM
62
+ true
63
+ end
64
+ end
65
+ end
@@ -37,18 +37,18 @@ module Samagotchi
37
37
  # "steer.cut_after"; nil for the default).
38
38
  # @param target [HostRegistry::ModelTarget]
39
39
  # @param names [Array<String>] the model's lookup names (HostRegistry#lookup_names)
40
- # @param models [Hash{String => ModelSettings}, nil] ConfigFile.model_settings (specs)
40
+ # @param models [Hash{String => ModelSettings}, nil] ModelSettings.all (specs)
41
41
  # @return [Array(Integer, String|nil)]
42
42
  def resolve(target, names:, models: nil)
43
43
  value, origin = Config.get_with_origin("steer.cut_after")
44
44
  return [value.to_i, ENV_KEY] if origin == :env
45
45
 
46
46
  models ||= begin
47
- ConfigFile.model_settings
47
+ ModelSettings.all
48
48
  rescue StandardError
49
49
  {}
50
50
  end
51
- setting = ConfigFile.model_setting(names, :steer_cut_after, models: models)
51
+ setting = ModelSettings.find(names, :steer_cut_after, models: models)
52
52
  return [setting.value, "models: #{setting.key}"] if setting
53
53
 
54
54
  host = target.entry.steer_cut_after
@@ -0,0 +1,49 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "../log"
4
+ require_relative "recording"
5
+ require_relative "runs"
6
+
7
+ module Samagotchi
8
+ module SystemOne
9
+ # What a turn stage needs to save its System 1 asks as runs: the
10
+ # Engine's Runs and the session's model as the Engine names it now.
11
+ # Engine#system_one_recorder builds one fresh at each stage call (never
12
+ # kept: an outgoing ask after a before_turn hook's model switch names
13
+ # the new model), on the caller's thread; the stage keeps it only for
14
+ # that call. NONE is what a stage gets when the Engine couldn't build
15
+ # one: no runs, every client as it was.
16
+ #
17
+ # +runs+ [Runs, nil] where the runs go (Runs#on? false: system_one.runs
18
+ # off); nil: NONE
19
+ # +session_model+ [String, nil] Engine#effective_model_name at the call
20
+ Recorder = Data.define(:runs, :session_model) do
21
+ # +client+ (nil for none) saving its asks as +judgment+'s runs. Anything
22
+ # going wrong here leaves the client as it was: a run is never worth a
23
+ # judgment. A scratch session's asks aren't saved; a participant's
24
+ # turn is never judged, so it never comes here.
25
+ # @param mode [String, nil] the use's mode, for its runs (Recording.wrap)
26
+ def wrap(client, judgment, session, mode: nil)
27
+ return client if client.nil? || runs.nil? || session&.scratch
28
+
29
+ context = Recording::Context.of(session, session_model: session && session_model)
30
+ Recording.wrap(client, judgment: judgment, runs: runs, context: context, recorded_mode: mode)
31
+ rescue StandardError => e
32
+ Recorder.failed(e)
33
+ client
34
+ end
35
+
36
+ # Whether runs are saved (an ask whose only use is its run is made
37
+ # only then: ObjectivesAudit).
38
+ def saving? = !runs.nil? && runs.on?
39
+
40
+ # The one warn for a recording that can't be set up.
41
+ def self.failed(error)
42
+ Samagotchi::Log.warn(:system_one, "system_one_recording_failed", error: error.class.name, msg: error.message.to_s[0, 200])
43
+ end
44
+ end
45
+
46
+ # No recording: the plain client, no runs.
47
+ Recorder::NONE = Recorder.new(runs: nil, session_model: nil)
48
+ end
49
+ end
@@ -14,7 +14,7 @@ module Samagotchi
14
14
  LATE = "worker not answering in time"
15
15
  # An exit the worker agreed to in an empty session. Said before it has
16
16
  # left: it checks again once it lets go, and a note or prompt arriving
17
- # first keeps the session (SessionManager.discard_left_session).
17
+ # first keeps the session (WorkerBoot.discard_left_session).
18
18
  EMPTY_WORDS = "the session is empty: it will be discarded if nothing arrives before its worker stops."
19
19
  EMPTY_EXIT = "Detached; #{EMPTY_WORDS}"
20
20
  # Why the worker stayed up after /exit, by the reason it gave.
@@ -44,8 +44,6 @@ module Samagotchi
44
44
  # Raised when another process (a worker or another chi) owns the session
45
45
  # this run was asked to use.
46
46
  class SessionBusy < StandardError; end
47
- # --resume with an id that has no saved session.
48
- class SessionNotFound < StandardError; end
49
47
 
50
48
  EMPTY_ANSWER_ERROR = "chi: the model gave an empty answer"
51
49
 
@@ -100,9 +98,7 @@ module Samagotchi
100
98
  # between the load and the lock that this run would later save over.
101
99
  # An unknown id is refused before the claim, which would leave an
102
100
  # empty session dir behind.
103
- if session_id && !Session.exist?(session_id)
104
- raise SessionNotFound, "Session not found: #{session_id}"
105
- end
101
+ raise Session::NotFound, session_id if session_id && !Session.exist?(session_id)
106
102
 
107
103
  claim_session!(session_id) if session_id
108
104
  @resume_session = session_id ? Session.load(session_id) : nil
@@ -434,7 +430,7 @@ module Samagotchi
434
430
 
435
431
  # A fresh session reaches the disk before its first turn: a tool in that
436
432
  # turn reads it from there (delegate loads its parent to start a child,
437
- # "Session not found" otherwise).
433
+ # "no session …" otherwise).
438
434
  def save_before_first_turn(session)
439
435
  session.save unless Session.exist?(session.id)
440
436
  end
@@ -60,7 +60,7 @@ module Samagotchi
60
60
  end
61
61
 
62
62
  def read(id)
63
- answer(:read, [id], {}) { raise Plugin::Sessions::Error, "no session #{id}" }
63
+ answer(:read, [id], {}) { raise Plugin::Sessions::Error, Session::NotFound.new(id).message }
64
64
  end
65
65
 
66
66
  def children(all: false)
@@ -84,7 +84,7 @@ module Samagotchi
84
84
  # the default).
85
85
  # @param target [HostRegistry::ModelTarget]
86
86
  # @param names [Array<String>] the model's lookup names (HostRegistry#lookup_names)
87
- # @param models [Hash{String => ModelSettings}, nil] ConfigFile.model_settings (specs)
87
+ # @param models [Hash{String => ModelSettings}, nil] ModelSettings.all (specs)
88
88
  # @param session [Symbol, nil] the session's own level (Session#thinking)
89
89
  # @return [Array(Symbol, String|nil)]
90
90
  def resolve(target, names:, models: nil, session: nil)
@@ -94,11 +94,11 @@ module Samagotchi
94
94
  return [global, origin == :cli ? "--thinking" : "SAMAGOTCHI_THINKING_LEVEL"] if global && %i[cli env].include?(origin)
95
95
 
96
96
  models ||= begin
97
- ConfigFile.model_settings
97
+ ModelSettings.all
98
98
  rescue StandardError
99
99
  {}
100
100
  end
101
- setting = ConfigFile.model_setting(names, :thinking, models: models)
101
+ setting = ModelSettings.find(names, :thinking, models: models)
102
102
  return [setting.value, "models: #{setting.key}"] if setting
103
103
 
104
104
  host = target.entry.thinking
@@ -23,7 +23,7 @@ module Samagotchi
23
23
  class TokenUsage < Data.define(:prompt_tokens, :completion_tokens, :cached_tokens, :cache_write_tokens,
24
24
  :reasoning_tokens, :cost, :predicted_per_second, :prompt_per_second, :predicted_ms, :source)
25
25
  CHARS_PER_TOKEN = 4.0
26
- # Re-prefilled tokens under this are none (KernelLoop#reprefilled_tokens,
26
+ # Re-prefilled tokens under this are none (ReprefillMeter#tokens,
27
27
  # SessionMetrics): servers count the cache in blocks (OpenAI's 128).
28
28
  REPREFILL_MIN_TOKENS = 128
29
29
 
@@ -5,6 +5,7 @@ require_relative "log"
5
5
  require_relative "command_steps"
6
6
  require_relative "tool_view"
7
7
  require_relative "tools/execute"
8
+ require_relative "tools/registry"
8
9
  require_relative "tools/read"
9
10
  require_relative "tools/write"
10
11
  require_relative "tools/memory"
@@ -359,8 +360,9 @@ module Samagotchi
359
360
  name == "git" && args.first == "diff" && args.intersect?(%w[--quiet --exit-code])
360
361
  end
361
362
 
362
- # +surface+: the turn's Tools::ToolSurface, for a preview that reads it
363
- # (call_tool's); nil outside a turn.
363
+ # +surface+: the turn's Tools::ToolSurface, which a tool's entry is
364
+ # looked up in, for a preview that reads it (call_tool's); nil outside a
365
+ # turn (+registry+'s entry then).
364
366
  def tool_activity_params(tool_name, call, registry: nil, surface: nil)
365
367
  case tool_name
366
368
  when Tools::Execute::NAME
@@ -455,7 +457,8 @@ module Samagotchi
455
457
  parts << "options=#{preview_tool_param(Array(opts).join(","))}" if opts && !Array(opts).empty?
456
458
  parts.join(" ")
457
459
  else
458
- registry_params(registry_entry(registry, tool_name), call, surface)
460
+ registry_params(surface ? surface.registered[tool_name.to_s] : registry_entry(registry, tool_name), call,
461
+ surface)
459
462
  end
460
463
  end
461
464
 
@@ -473,7 +476,8 @@ module Samagotchi
473
476
  # key="value" (the parsers' args:, which a registry-less reader such as
474
477
  # the web's reload also has); nil for a tool the registry doesn't know
475
478
  # that has no args:, and for a built-in without its own words above
476
- # (the reminder tools).
479
+ # (the reminder tools). A missing surface (Tools::MissingSurface) is
480
+ # raised, never taken as a failing preview.
477
481
  def registry_params(entry, call, surface = nil)
478
482
  return nil if entry&.core?
479
483
  return nil if entry.nil? && !call[:args].is_a?(Hash)
@@ -481,6 +485,8 @@ module Samagotchi
481
485
  if entry&.preview
482
486
  begin
483
487
  return entry.preview_of(call, surface)
488
+ rescue Tools::MissingSurface
489
+ raise
484
490
  rescue StandardError => e
485
491
  Log.warn(:plugins, "plugin_preview_failed", tool: entry.name, error: e.class.name,
486
492
  msg: "#{entry.name} preview failed: #{e.message}")
@@ -2,7 +2,7 @@
2
2
 
3
3
  require "json"
4
4
  require_relative "tools/args"
5
- require_relative "llm_context_strategy"
5
+ require_relative "config"
6
6
  require_relative "tools/memory"
7
7
 
8
8
  module Samagotchi
@@ -482,7 +482,7 @@ module Samagotchi
482
482
  # (Tools::Registry's layer gate), so it is not in TOOL_SCHEMAS, which
483
483
  # every turn declares. Its description carries llm_context.policy
484
484
  # (#forget_outputs_schema); this one the default's.
485
- FORGET_OUTPUTS_POLICY = LLMContextStrategy::DEFAULT_POLICY
485
+ FORGET_OUTPUTS_POLICY = Config::DEFAULT_LLM_CONTEXT_POLICY
486
486
  FORGET_OUTPUTS_DESCRIPTION = "Forget tool outputs you no longer need, to free context. Every tool output starts " \
487
487
  "with an id like [#t42]: list ids to forget, and each output is replaced in place by " \
488
488
  "a stub with your note (the call stays). %<policy>s\n" \
@@ -1,5 +1,6 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require_relative "config"
3
4
  require_relative "tool_output_files"
4
5
 
5
6
  module Samagotchi
@@ -28,6 +29,22 @@ module Samagotchi
28
29
  # task's log, the child's reply in its output/ folder), which the tool
29
30
  # gave with its text (Tools::RefText) and the gap line names.
30
31
  module ToolOutputCut
32
+ # The per-output cap with nothing set (max_tool_output_chars).
33
+ DEFAULT_MAX_CHARS = 10_000
34
+
35
+ # The per-output cap both loops cut tool outputs to (and the emitted
36
+ # tool call events carry): an explicit +override+ wins, then
37
+ # max_tool_output_chars (Config). A non-positive value falls back to
38
+ # DEFAULT_MAX_CHARS (there is intentionally no "unlimited": live UIs get
39
+ # a bounded `output:` plus a truthful `output_truncated:` flag). The one
40
+ # exception is memory_read, which ToolRunner leaves out of this cap
41
+ # (memory.read_max_chars, 0: no fixed cap; a memory is read whole).
42
+ # @return [Integer]
43
+ def self.max_chars(override)
44
+ parsed = (override || Config.get("max_tool_output_chars")).to_i
45
+ parsed.positive? ? parsed : DEFAULT_MAX_CHARS
46
+ end
47
+
31
48
  POLICIES = { "execute" => :head_tail_file, "task_wait" => :head_tail_ref, "delegate" => :head_tail_ref,
32
49
  "delegate_result" => :head_tail_ref }.freeze
33
50
 
@@ -407,22 +407,25 @@ module Samagotchi
407
407
  # The kernel's tools, for the activity line of a tool that isn't built in.
408
408
  def tools = @kernel.tools
409
409
 
410
- # The turn's Tools::ToolSurface (+context+'s), else one computed now
411
- # from the kernel's tools (a runner outside an Engine turn).
412
- def surface(context) = Tools::ToolSurface.of(context, tools)
410
+ # The turn's Tools::ToolSurface (+context+'s; none raises
411
+ # Tools::MissingSurface).
412
+ def surface(context) = Tools::ToolSurface.of(context)
413
413
 
414
414
  # The call its tool's entry unwraps it to (call_tool on a built-in),
415
415
  # else the call as it is. On a host that loads tools, a direct call of
416
416
  # a source's tool by its acts_as runs as the call_tool call first
417
417
  # (Registry::Index#wrap): call_tool's row, rules and approvals. One
418
418
  # that fails runs as it is: call_tool then refuses a built-in (fail
419
- # closed).
419
+ # closed). A context without a surface raises Tools::MissingSurface
420
+ # here, before the gate: the call never runs.
420
421
  def unwrapped(call, context)
421
422
  return call if tools.nil? || call[:name].nil?
422
423
 
423
424
  surface = surface(context)
424
425
  call = wrapped(surface, call)
425
426
  surface.declared_entry(call[:name])&.unwrap&.call(call, surface) || call
427
+ rescue Tools::MissingSurface
428
+ raise
426
429
  rescue StandardError => e
427
430
  Log.warn(:turn, "tool_unwrap_failed", tool: call[:name].to_s, error: "#{e.class}: #{e.message}")
428
431
  call
@@ -115,7 +115,7 @@ module Samagotchi
115
115
  raise ArgumentError, "#{NAME} #{verb} needs a tool name\n#{USAGE}" if tools.empty?
116
116
 
117
117
  tools.reduce(toolkit) do |kit, tool|
118
- raise ArgumentError, "no tool named #{tool} in this session" unless @engine.tools.key?(tool)
118
+ raise ArgumentError, "no tool named #{tool} in this session" unless @engine.published_tools.key?(tool)
119
119
 
120
120
  verb.casecmp?("add") ? kit.adding(tool) : kit.removing(tool)
121
121
  end
@@ -314,11 +314,13 @@ module Samagotchi
314
314
 
315
315
  # @return [String] the child's id, or an Error: line
316
316
  def self.follow_up(task, session:, parent:, state_dir:)
317
- id = Session.resolve_id(session, state_dir: state_dir)
317
+ id = Session.resolve!(session, state_dir: state_dir)
318
318
  child = begin
319
319
  Session.load(id, state_dir: state_dir)
320
- rescue ArgumentError
321
- return "Error: no session #{session} (list_sessions shows them)"
320
+ rescue Session::NotFound
321
+ raise # gone since resolve!: the outer rescue adds the list_sessions hint
322
+ rescue ArgumentError => e # a file that won't load
323
+ return "Error: #{e.message}"
322
324
  end
323
325
  unless child.parent_id == parent.id
324
326
  return "Error: #{id[0, 8]} is not a delegate of this session; send_note reaches any session"
@@ -340,6 +342,8 @@ module Samagotchi
340
342
  "Error: session #{id[0, 8]}: #{e.message}"
341
343
  rescue SessionManager::OwnedByTUI
342
344
  "Error: session #{id[0, 8]} is #{OwnerLock::TUI_BUSY}, which can't take a delegated message"
345
+ rescue Session::NotFound => e
346
+ "Error: #{e.message} (list_sessions shows them)"
343
347
  rescue Session::AmbiguousId => e
344
348
  "Error: #{e.message}"
345
349
  end
@@ -392,10 +396,11 @@ module Samagotchi
392
396
  # busy (a worker runs its turn), or running with a worker on its way
393
397
  # (ChildrenStatus asks it too).
394
398
  # @param summary [Hash] a children_of row, or the same keys: busy,
395
- # status, live, updated_at
399
+ # saved_status (the file's: the displayed status shows a worker on
400
+ # its way as idle), live, updated_at
396
401
  def self.running?(summary)
397
402
  return true if summary[:busy]
398
- return false unless summary[:status] == Session::STATUS_RUNNING && !summary[:live]
403
+ return false unless summary[:saved_status] == Session::STATUS_RUNNING && !summary[:live]
399
404
 
400
405
  Time.now - Time.iso8601(summary[:updated_at].to_s) < STARTING_GRACE_SECONDS
401
406
  rescue ArgumentError
@@ -29,7 +29,7 @@ module Samagotchi
29
29
  newest_running_child(peers.session_id, state_dir: sd) ||
30
30
  (return "No running delegate; list_sessions shows finished ones.")
31
31
  else
32
- id = Session.resolve_id(session.to_s.strip, state_dir: sd)
32
+ id = Session.resolve!(session.to_s.strip, state_dir: sd)
33
33
  child = Session.load(id, state_dir: sd)
34
34
  unless child.parent_id == peers.session_id
35
35
  return "Error: #{id[0, 8]} is not a delegate of this session (list_sessions marks them child)"
@@ -38,10 +38,10 @@ module Samagotchi
38
38
  id
39
39
  end
40
40
  DelegateWait.call(child_id, peers: peers, timeout: Delegate.parse_timeout(timeout))
41
- rescue Session::AmbiguousId => e
41
+ rescue Session::NotFound => e
42
+ "Error: #{e.message} (list_sessions shows them)"
43
+ rescue ArgumentError => e
42
44
  "Error: #{e.message}"
43
- rescue ArgumentError
44
- "Error: no session #{session.to_s.strip} (list_sessions shows them)"
45
45
  end
46
46
 
47
47
  def self.newest_running_child(parent_id, state_dir:)
@@ -0,0 +1,14 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Samagotchi
4
+ module Tools
5
+ # find_tools' answer text that the wire reads too, kept a leaf (no
6
+ # requires): ToolIndex writes CALL_HINT as a keyword answer's first
7
+ # line, and LLM::AnthropicWire strips it from a result whose tools it
8
+ # loads (they are called directly then).
9
+ module IndexHint
10
+ # A keyword answer's first line; call_tool is BuiltinCalls::VIA.
11
+ CALL_HINT = "Call one with call_tool(tool: \"<group>/<tool>\", args: {…})."
12
+ end
13
+ end
14
+ end
@@ -2,6 +2,14 @@
2
2
 
3
3
  module Samagotchi
4
4
  module Tools
5
+ # A reader of the turn's tools (Tools::ToolSurface) given none: a
6
+ # context or call that should carry the turn's carries nothing. Never
7
+ # taken as a failing preview's or targets' (ToolActivity, Guardrails::
8
+ # Targets re-raise it): a rule's acts_as must not silently go missing.
9
+ class MissingSurface < StandardError
10
+ def initialize(msg = "no ToolSurface: the turn's tools are missing (TurnContext#surface)") = super
11
+ end
12
+
5
13
  # The tools a session offers the model, in declaration order: the
6
14
  # built-ins (Tools::Builtins) as registered, then the ones bundles add,
7
15
  # by bundle and name. That order doesn't depend on which plugin
@@ -19,8 +27,11 @@ module Samagotchi
19
27
  # "Error: …" marks a failure); kctx is the KernelLoop's ToolContext
20
28
  # @!attribute label [String, nil] the activity line's action ("calling
21
29
  # tool" when nil); ToolActivity knows the built-ins' own
22
- # @!attribute preview [#call, nil] call → the activity line's params
23
- # @!attribute targets [#call, nil] call → what guardrail rules match
30
+ # @!attribute preview [#call, nil] (call, surface) → the activity line's
31
+ # params; +surface+ the turn's Tools::ToolSurface (nil: none)
32
+ # @!attribute targets [#call, nil] (call, surface) → what guardrail
33
+ # rules match. #register takes a one-argument preview or targets
34
+ # (call only, a plugin's) and gives it this form (.per_call)
24
35
  # @!attribute refs [#call, nil] call → the row's refs (a plugin's
25
36
  # refs:, RowRefs checks what it gives)
26
37
  # @!attribute source [String] "core", or the bundle that added it
@@ -37,17 +48,22 @@ module Samagotchi
37
48
  def core? = source == "core"
38
49
 
39
50
  # Its preview on +call+ (the row's params), nil without one.
40
- # +surface+, the turn's Tools::ToolSurface (nil: none), goes to a
41
- # preview that takes a second argument (call_tool's: what the turn
42
- # reaches); a plugin's takes the call only.
43
- def preview_of(call, surface = nil) = preview && Entry.per_call(preview, call, surface)
51
+ # +surface+, the turn's Tools::ToolSurface (nil: none), is what
52
+ # call_tool's reads (what the turn reaches: it raises MissingSurface
53
+ # without one); a plugin's ignores it.
54
+ def preview_of(call, surface = nil) = preview&.call(call, surface)
44
55
 
45
56
  # Its targets on +call+ (what guardrail rules match), nil without
46
57
  # any; +surface+ as #preview_of.
47
- def targets_of(call, surface = nil) = targets && Entry.per_call(targets, call, surface)
58
+ def targets_of(call, surface = nil) = targets&.call(call, surface)
59
+
60
+ # +callable+ as (call, surface) → value, the one form an entry's
61
+ # preview and targets take: a one-argument one (call only) is given
62
+ # the call alone. The arity is read here, once, at registration.
63
+ def self.per_call(callable)
64
+ return callable if callable.nil? || callable.arity != 1
48
65
 
49
- def self.per_call(callable, call, surface)
50
- callable.arity == 1 ? callable.call(call) : callable.call(call, surface)
66
+ ->(call, _surface = nil) { callable.call(call) }
51
67
  end
52
68
 
53
69
  # Offered in a turn under +layers+ (the turn's LLM context layers).
@@ -99,8 +115,9 @@ module Samagotchi
99
115
  unwrap: nil)
100
116
  raise ArgumentError, "tool #{name} is already registered" if @entries.key?(name)
101
117
 
102
- @entries[name] = Entry.new(name: name, schema: schema, handler: handler, label: label, preview: preview,
103
- targets: targets, refs: refs, source: source, layer: layer, unwrap: unwrap)
118
+ @entries[name] = Entry.new(name: name, schema: schema, handler: handler, label: label,
119
+ preview: Entry.per_call(preview), targets: Entry.per_call(targets), refs: refs,
120
+ source: source, layer: layer, unwrap: unwrap)
104
121
  end
105
122
 
106
123
  # Remove a tool (a plugin's tool set changed after load).
@@ -22,7 +22,7 @@ module Samagotchi
22
22
  return "Error: this session's id is not known here" unless peers&.session_id
23
23
  return "Error: give the target session's id (list_sessions shows them)" if session.to_s.strip.empty?
24
24
 
25
- id = Session.resolve_id(session.to_s.strip, state_dir: peers.state_dir)
25
+ id = Session.resolve!(session.to_s.strip, state_dir: peers.state_dir)
26
26
  Session.load(id, state_dir: peers.state_dir)
27
27
  return "Error: #{id[0, 8]} is this session; send_note is for other sessions" if id == peers.session_id
28
28
 
@@ -33,12 +33,10 @@ module Samagotchi
33
33
 
34
34
  where = result.status == :queued ? "its worker adds it before its next turn" : "it has no worker now, so it waits for its next start"
35
35
  "Queued a note for session #{id[0, 8]}: #{where}. It does not start a turn there."
36
- rescue Session::AmbiguousId => e
36
+ rescue Session::NotFound => e
37
+ "Error: #{e.message} (list_sessions shows them)"
38
+ rescue ArgumentError => e # AmbiguousId, SessionInbox::NoteRejected, a file that won't load
37
39
  "Error: #{e.message}"
38
- rescue SessionInbox::NoteRejected => e
39
- "Error: #{e.message}"
40
- rescue ArgumentError
41
- "Error: no session #{session.to_s.strip} (list_sessions shows them)"
42
40
  end
43
41
  end
44
42
  end