samagotchi 0.106.0 → 0.108.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +157 -1
  3. data/bin/chi +2 -0
  4. data/docs/architecture.md +6 -1
  5. data/docs/cli.md +45 -5
  6. data/docs/guardrails.md +8 -2
  7. data/docs/internals/engine.md +17 -6
  8. data/docs/internals/participants.md +129 -30
  9. data/docs/internals/remote-sessions.md +12 -5
  10. data/docs/internals/working-set.md +2 -1
  11. data/docs/memory.md +20 -0
  12. data/docs/plugins.md +38 -3
  13. data/docs/releasing.md +13 -6
  14. data/docs/sessions.md +39 -4
  15. data/docs/sub-agent.md +3 -1
  16. data/docs/testing.md +7 -1
  17. data/lib/samagotchi/bridge/turn_accumulator.rb +8 -1
  18. data/lib/samagotchi/bridge.rb +7 -2
  19. data/lib/samagotchi/bridge_client/stream_request.rb +10 -3
  20. data/lib/samagotchi/bundles/coordinator/manifest.yml +6 -5
  21. data/lib/samagotchi/bundles/coordinator/plugin.rb +85 -5
  22. data/lib/samagotchi/bundles/coordinator/skill_coordinator.md +18 -0
  23. data/lib/samagotchi/bundles/cost-cap/manifest.yml +2 -2
  24. data/lib/samagotchi/bundles/cost-cap/plugin.rb +51 -9
  25. data/lib/samagotchi/bundles/dev/manifest.yml +2 -2
  26. data/lib/samagotchi/bundles/system/manifest.yml +2 -2
  27. data/lib/samagotchi/bundles/system/memory_guide.md +1 -1
  28. data/lib/samagotchi/bundles/work-cap/manifest.yml +2 -2
  29. data/lib/samagotchi/bundles/work-cap/plugin.rb +50 -14
  30. data/lib/samagotchi/child_reports.rb +2 -1
  31. data/lib/samagotchi/cli/parent_wait.rb +1 -1
  32. data/lib/samagotchi/context_sources.rb +1 -6
  33. data/lib/samagotchi/continue_offer.rb +56 -7
  34. data/lib/samagotchi/engine.rb +36 -25
  35. data/lib/samagotchi/guardrail_wiring.rb +9 -6
  36. data/lib/samagotchi/guardrails/review_boundary.rb +6 -57
  37. data/lib/samagotchi/guardrails/review_paths.rb +93 -0
  38. data/lib/samagotchi/idle_scheduler.rb +17 -2
  39. data/lib/samagotchi/last_turn.rb +7 -0
  40. data/lib/samagotchi/log_subscriber.rb +2 -1
  41. data/lib/samagotchi/memory_orphans.rb +74 -0
  42. data/lib/samagotchi/memory_paths.rb +4 -4
  43. data/lib/samagotchi/model_profile.rb +5 -3
  44. data/lib/samagotchi/parent_report.rb +34 -4
  45. data/lib/samagotchi/participant_messages.rb +11 -0
  46. data/lib/samagotchi/participants.rb +20 -6
  47. data/lib/samagotchi/plugin/api.rb +2 -1
  48. data/lib/samagotchi/plugin/sessions.rb +25 -0
  49. data/lib/samagotchi/remote_command.rb +1 -1
  50. data/lib/samagotchi/remotes.rb +23 -8
  51. data/lib/samagotchi/reply_wait.rb +7 -2
  52. data/lib/samagotchi/review_apply.rb +123 -0
  53. data/lib/samagotchi/review_command.rb +121 -0
  54. data/lib/samagotchi/review_start.rb +161 -0
  55. data/lib/samagotchi/run_options.rb +17 -2
  56. data/lib/samagotchi/send_command/busy.rb +5 -2
  57. data/lib/samagotchi/send_command/wait_target.rb +18 -8
  58. data/lib/samagotchi/send_command.rb +2 -0
  59. data/lib/samagotchi/session.rb +33 -5
  60. data/lib/samagotchi/session_access/contract.rb +10 -2
  61. data/lib/samagotchi/session_access/dispatch.rb +8 -2
  62. data/lib/samagotchi/session_access/http_transport.rb +10 -1
  63. data/lib/samagotchi/session_access/local.rb +19 -2
  64. data/lib/samagotchi/session_access/remote.rb +15 -1
  65. data/lib/samagotchi/session_access/web_bridge_client.rb +1 -1
  66. data/lib/samagotchi/session_access.rb +23 -10
  67. data/lib/samagotchi/session_chain.rb +10 -2
  68. data/lib/samagotchi/session_continue.rb +4 -3
  69. data/lib/samagotchi/session_inbox.rb +12 -8
  70. data/lib/samagotchi/session_manager.rb +30 -8
  71. data/lib/samagotchi/session_metrics.rb +7 -6
  72. data/lib/samagotchi/session_participants.rb +3 -1
  73. data/lib/samagotchi/session_review.rb +28 -0
  74. data/lib/samagotchi/share_command.rb +7 -1
  75. data/lib/samagotchi/steer.rb +11 -1
  76. data/lib/samagotchi/terminal_ui/attached_loop.rb +34 -27
  77. data/lib/samagotchi/terminal_ui/formatting.rb +2 -2
  78. data/lib/samagotchi/terminal_ui/one_shot_sink.rb +5 -1
  79. data/lib/samagotchi/testing/sessions.rb +10 -2
  80. data/lib/samagotchi/tools/memory.rb +16 -9
  81. data/lib/samagotchi/turn_checkpoint.rb +13 -0
  82. data/lib/samagotchi/turn_origin.rb +68 -0
  83. data/lib/samagotchi/version.rb +1 -1
  84. data/lib/samagotchi/web/app.rb +108 -21
  85. data/lib/samagotchi/web/grants.rb +92 -17
  86. data/lib/samagotchi/web/participant_access.rb +56 -110
  87. data/lib/samagotchi/web/participant_review.rb +45 -2
  88. data/lib/samagotchi/web/participant_stream_filter.rb +118 -17
  89. data/lib/samagotchi/web/participant_view.rb +19 -14
  90. data/lib/samagotchi/web/participants_admin.rb +129 -0
  91. data/lib/samagotchi/web/public/app.js +60 -5
  92. data/lib/samagotchi/web/public/chip_popover.js +10 -3
  93. data/lib/samagotchi/web/public/data.js +10 -2
  94. data/lib/samagotchi/web/public/delivery_line.js +79 -15
  95. data/lib/samagotchi/web/public/index.html +26 -0
  96. data/lib/samagotchi/web/public/info_bar.js +7 -3
  97. data/lib/samagotchi/web/public/info_bar_model.js +7 -1
  98. data/lib/samagotchi/web/public/live_turn.js +3 -0
  99. data/lib/samagotchi/web/public/participant.html +58 -5
  100. data/lib/samagotchi/web/public/participant.js +172 -25
  101. data/lib/samagotchi/web/public/participant_model.js +89 -24
  102. data/lib/samagotchi/web/public/participant_names.js +37 -5
  103. data/lib/samagotchi/web/public/participants_panel.js +86 -18
  104. data/lib/samagotchi/web/public/question_cards.js +1 -0
  105. data/lib/samagotchi/web/public/review_apply.js +34 -0
  106. data/lib/samagotchi/web/public/review_start.js +101 -0
  107. data/lib/samagotchi/web/public/send_turn.js +25 -1
  108. data/lib/samagotchi/web/public/session_actions.js +44 -3
  109. data/lib/samagotchi/web/public/session_state.js +3 -0
  110. data/lib/samagotchi/web/public/start_page.js +38 -2
  111. data/lib/samagotchi/web/public/stream_handlers.js +10 -0
  112. data/lib/samagotchi/web/public/turn_html.js +2 -1
  113. data/lib/samagotchi/web/public/turn_view.js +5 -0
  114. data/lib/samagotchi/web/session_summary.rb +3 -0
  115. data/lib/samagotchi/worker.rb +44 -27
  116. data/lib/samagotchi/worker_inbound.rb +12 -9
  117. data/lib/samagotchi/working_set.rb +3 -2
  118. metadata +11 -1
@@ -0,0 +1,93 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "protected_paths"
4
+ require_relative "shell_paths"
5
+ require_relative "../paths"
6
+
7
+ module Samagotchi
8
+ module Guardrails
9
+ # What a participant may read (the shared-sessions plan's §2): a file
10
+ # under the session's project root that isn't on the read denylist
11
+ # (chi's state and config dirs, home secret dirs, project secret files),
12
+ # checked on the path as given and as it resolves (a symlink in the
13
+ # project to ~/.ssh is ~/.ssh). ReviewBoundary asks it for every read of
14
+ # a participant's turn; a review session's subjects (chi review, the
15
+ # participant page's Plan) go through the same check.
16
+ class ReviewPaths
17
+ # Home folders that hold keys and tokens, never read in a review turn.
18
+ HOME_SECRET_DIRS = %w[.ssh .gnupg .aws].freeze
19
+ # Project files that hold secrets, by a path part's name: .env*,
20
+ # netrc, keys and certificates, anything named credentials, package
21
+ # registry tokens (.npmrc, .pypirc), ssh keys, terraform state, a
22
+ # secrets file; and a git config (.git/config, a submodule's
23
+ # .git/modules/x/config), checked apart.
24
+ SECRET_FILE = /\A(?:\.env.*|[._]netrc|.*\.(?:pem|key|p12|pfx|tfstate(?:\.backup)?)|.*credentials.*|
25
+ \.npmrc|\.pypirc|\.git-credentials|id_(?:rsa|dsa|ecdsa|ed25519)(?:\.pub)?|secrets?\.(?:ya?ml|json))\z/xi
26
+ # The .docker/config.json kind: a dot dir's config holding tokens.
27
+ SECRET_DIR_FILES = { ".docker" => "config.json", ".kube" => "config" }.freeze
28
+ GIT_DIR = ".git"
29
+
30
+ # Why a path can't be read (#refusal).
31
+ OUTSIDE = :outside
32
+ SECRET = :secret
33
+ HOME_ROOT = :home_root
34
+
35
+ # chi's state dir and config dir, as Paths has them now.
36
+ def self.chi_dirs = [Paths.state_dir, File.join(Paths.config_home, Paths::APP_DIR)]
37
+
38
+ # @param root [String, nil] the session's project root (the work tree
39
+ # top of its folder); nil or blank refuses every path
40
+ # @param denied_dirs [Array<String>] chi's own dirs (state, config:
41
+ # sessions, grants, the web token, memories and .bundles,
42
+ # config.yml, hooks)
43
+ # @param home [String, nil]
44
+ def initialize(root:, denied_dirs: ReviewPaths.chi_dirs, home: Dir.home)
45
+ @root = root.to_s
46
+ @denied_dirs = denied_dirs
47
+ @home = home.to_s
48
+ end
49
+
50
+ # Why +paths+ can't all be read, or nil when they can: OUTSIDE (no
51
+ # path, no root, or a path outside the root), HOME_ROOT (the root is
52
+ # the home folder or above it) or SECRET.
53
+ # @param paths [Array<String>] absolute, or relative to the cwd
54
+ # @return [Symbol, nil]
55
+ def refusal(paths)
56
+ return OUTSIDE if paths.empty? || @root.empty?
57
+
58
+ real_root = ProtectedPaths.real(@root)
59
+ return HOME_ROOT if !@home.empty? && ShellPaths.within?(ProtectedPaths.real(@home), real_root)
60
+
61
+ paths.each do |path|
62
+ given = File.expand_path(path)
63
+ real = ProtectedPaths.real(given)
64
+ return OUTSIDE unless ShellPaths.within?(real, real_root)
65
+ return SECRET if secret?(given) || secret?(real)
66
+ end
67
+ nil
68
+ end
69
+
70
+ private
71
+
72
+ def secret?(path)
73
+ dirs = @denied_dirs.compact.map { |dir| File.expand_path(dir) }
74
+ dirs += dirs.map { |dir| ProtectedPaths.real(dir) }
75
+ dirs += HOME_SECRET_DIRS.map { |dir| File.join(@home, dir) } unless @home.empty?
76
+ return true if dirs.any? { |dir| ShellPaths.within?(path, dir) }
77
+
78
+ parts = path.split(File::SEPARATOR)
79
+ return true if parts.any? { |part| SECRET_FILE.match?(part) }
80
+ return true if parts.each_cons(2).any? { |dir, file| SECRET_DIR_FILES[dir.downcase] == file.downcase }
81
+
82
+ git_config?(parts)
83
+ end
84
+
85
+ # A config file anywhere under a .git dir (.git/config,
86
+ # .git/modules/<sub>/config, a worktree's config.worktree).
87
+ def git_config?(parts)
88
+ git = parts.index { |part| part.casecmp?(GIT_DIR) } or return false
89
+ parts[(git + 1)..].any? { |part| part.downcase.start_with?("config") }
90
+ end
91
+ end
92
+ end
93
+ end
@@ -63,7 +63,10 @@ module Samagotchi
63
63
  # takes) passes join: false: the thread finishes its tick and exits by
64
64
  # itself, and a later joining stop (Engine#shutdown, the worker's
65
65
  # teardown) still joins it. From the scheduler's own thread (a job's
66
- # tick) it never joins.
66
+ # tick) it never joins. A thread that died of an error #run_loop doesn't
67
+ # rescue (a SystemStackError, a job's `exit`) is logged here, not raised
68
+ # again by the join into the caller (Engine#shutdown would skip the rest
69
+ # of its teardown: plugin tasks, MCP servers).
67
70
  def stop(join: true)
68
71
  @stopped = true
69
72
  @wake << :stop
@@ -72,7 +75,7 @@ module Samagotchi
72
75
  @unjoined = join ? nil : thread
73
76
  return if thread.nil? || !join || thread == Thread.current
74
77
 
75
- thread.kill unless thread.join(STOP_JOIN_SECONDS)
78
+ thread.kill unless join_thread(thread)
76
79
  nil
77
80
  end
78
81
 
@@ -104,6 +107,18 @@ module Samagotchi
104
107
 
105
108
  private
106
109
 
110
+ # The thread joined within STOP_JOIN_SECONDS (truthy) or not (nil).
111
+ def join_thread(thread)
112
+ thread.join(STOP_JOIN_SECONDS)
113
+ rescue Exception => e # rubocop:disable Lint/RescueException -- the thread's own death, re-raised by join
114
+ # A status of nil: the thread ended with this exception. Anything else
115
+ # (an interrupt of the caller's own while it waited) is the caller's.
116
+ raise unless thread.status.nil?
117
+
118
+ Log.exception(:idle, "scheduler_died", e, echo: "[IdleScheduler] scheduler thread died: #{e.class}: #{e.message}")
119
+ thread
120
+ end
121
+
107
122
  def run_loop
108
123
  until @stopped
109
124
  tick
@@ -1,5 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require_relative "steer"
4
+
3
5
  module Samagotchi
4
6
  # How a session's last turn ended (Session#last_turn), saved as
5
7
  # session.json's "last_turn" and sent in the web's session summary.
@@ -44,6 +46,11 @@ module Samagotchi
44
46
  # The stop facts this turn has (LastTurn::STOP_FACTS), symbol keys.
45
47
  # @return [Hash{Symbol => Object}]
46
48
  def stop_facts = to_h.slice(*self.class::STOP_FACTS).compact
49
+
50
+ # The turn's author when a participant's (Steer.sender_author, as
51
+ # TurnOrigin#participant_author reads a running turn's), else nil.
52
+ # @return [String, nil]
53
+ def participant_author = Steer.sender_author(author)
47
54
  end
48
55
 
49
56
  # Why a turn stopped, for a parent agent's wait (ReplyWait::Result takes
@@ -1,6 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require_relative "log"
4
+ require_relative "turn_origin"
4
5
 
5
6
  module Samagotchi
6
7
  # The event trail: a SessionObserver subscriber (next to SessionMetrics)
@@ -181,7 +182,7 @@ module Samagotchi
181
182
  end
182
183
 
183
184
  def origin(event)
184
- client = event.dig(:origin, :client_id) if event[:origin].is_a?(Hash)
185
+ client = TurnOrigin.from(event[:origin])&.client_id
185
186
  client ? { client_id: client } : {}
186
187
  end
187
188
 
@@ -0,0 +1,74 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "memory_paths"
4
+
5
+ module Samagotchi
6
+ # A project memory folder left behind by a move: memories copied to a
7
+ # machine (or a path) where the project root differs, so its key
8
+ # (MemoryPaths.project_key: basename + MD5 of the root) differs too, and
9
+ # chi finds no project memories without a word about why.
10
+ #
11
+ # Pure: one listing of the projects dir, no git subprocess. Said at
12
+ # session start (Engine#announce_load_events!, label "memory") and under a
13
+ # memory_read miss (Tools::MemoryRead); never in the system prompt.
14
+ module MemoryOrphans
15
+ # @!attribute computed [String] the folder chi reads (this project's key)
16
+ # @!attribute candidates [Array<String>] same-basename folders, other hashes
17
+ # @!attribute computed_exists [Boolean] whether +computed+ is a folder (empty of memories)
18
+ Found = Data.define(:computed, :candidates, :computed_exists)
19
+
20
+ module_function
21
+
22
+ # The orphan candidates for +cwd+'s project, or nil: only inside a git
23
+ # repository (outside one the root is cwd, and every src/ or tmp/ would
24
+ # match), and only while the computed folder holds no *.md (a
25
+ # memory_write's mkdir_p or a project-scope bundle install alone must
26
+ # not silence it).
27
+ # @return [Found, nil]
28
+ def find(env: ENV, cwd: Dir.pwd)
29
+ return nil unless MemoryPaths.in_repo?(cwd)
30
+
31
+ projects = MemoryPaths.projects_dir(env: env)
32
+ computed = MemoryPaths.project_dir(env: env, cwd: cwd)
33
+ return nil if File.directory?(computed) && Dir.children(computed).any? { |name| name.end_with?(".md") }
34
+
35
+ key = File.basename(computed)
36
+ # The root's basename, never a split of a key on "_" (a basename may hold one).
37
+ pattern = /\A#{Regexp.escape(File.basename(MemoryPaths.project_root(cwd)))}_\h{8}\z/
38
+ names = Dir.children(projects).select { |name| name != key && name.match?(pattern) }
39
+ candidates = names.sort.map { |name| File.join(projects, name) }.select { |path| File.directory?(path) }
40
+ return nil if candidates.empty?
41
+
42
+ Found.new(computed: computed, candidates: candidates, computed_exists: File.directory?(computed))
43
+ rescue SystemCallError
44
+ nil
45
+ end
46
+
47
+ # The one text for the condition (the startup warning and the
48
+ # memory_read hint both say it), or nil when there is none.
49
+ def message(env: ENV, cwd: Dir.pwd)
50
+ found = find(env: env, cwd: cwd)
51
+ found && text(found)
52
+ end
53
+
54
+ def text(found)
55
+ computed = found.computed
56
+ lead = "no project memories in #{computed}"
57
+ if found.candidates.size == 1
58
+ candidate = found.candidates.first
59
+ fix = if found.computed_exists
60
+ "move its files into #{computed} (e.g. `mv #{candidate}/* #{computed}/`)"
61
+ else
62
+ "`mv #{candidate} #{computed}`"
63
+ end
64
+ "#{lead}, but #{candidate} has the same project name with another path's hash (memories moved from " \
65
+ "another machine or path?). A name match can't prove it's this project; if it is, #{fix}."
66
+ else
67
+ fix = found.computed_exists ? "move its files into #{computed}" : "`mv <that folder> #{computed}`"
68
+ "#{lead}, but these have the same project name with another path's hash (memories moved from another " \
69
+ "machine or path?): #{found.candidates.join(", ")}. A name match can't prove one is this project; if one " \
70
+ "is, #{fix}."
71
+ end
72
+ end
73
+ end
74
+ end
@@ -23,10 +23,10 @@ module Samagotchi
23
23
  end
24
24
 
25
25
  # One folder per project root: basename + 8 hex chars of MD5(full root path).
26
- def project_key(cwd = Dir.pwd)
27
- root = project_root(cwd)
28
- "#{File.basename(root)}_#{Digest::MD5.hexdigest(root)[0..7]}"
29
- end
26
+ def project_key(cwd = Dir.pwd) = key_for_root(project_root(cwd))
27
+
28
+ # #project_key for a root already resolved (a session's project_root).
29
+ def key_for_root(root) = "#{File.basename(root)}_#{Digest::MD5.hexdigest(root)[0..7]}"
30
30
 
31
31
  # The repository's common git directory identifies the project; every linked
32
32
  # worktree shares it. Returns the checkout holding it when it is named .git,
@@ -228,8 +228,10 @@ module Samagotchi
228
228
  # @param lists [#read] ModelListStore by default
229
229
  # @param relist [#call, nil] how a miss re-lists the host:
230
230
  # (host_name, env) -> ids or nil. HostRegistry#list_models by default.
231
+ # @param now [Integer] epoch seconds the saved list's age is judged at
232
+ # (one clock read for both the TTL and the re-list age)
231
233
  # @return [String, nil]
232
- def self.model_warning(model_name, env: ENV, hosts: nil, lists: nil, relist: nil)
234
+ def self.model_warning(model_name, env: ENV, hosts: nil, lists: nil, relist: nil, now: Time.now.to_i)
233
235
  require_relative "config"
234
236
  require_relative "model_list_store"
235
237
  hosts ||= Samagotchi::ConfigFile.hosts_config(env: env)
@@ -241,13 +243,13 @@ module Samagotchi
241
243
  return nil if hosts[host.to_s.strip.downcase]&.models&.key?(parsed.id.to_s.strip.downcase)
242
244
 
243
245
  list = lists.read(env: env)[host.to_s.strip.downcase]
244
- return nil if list.nil? || list.stale? || list.known?(parsed.id)
246
+ return nil if list.nil? || list.stale?(now: now) || list.known?(parsed.id)
245
247
  # A saved list this recent is taken at its word. Re-listing every miss
246
248
  # would make each launch of an id a host serves but never lists (a
247
249
  # gateway's round-robin aliases) pay the re-list's cap and warn
248
250
  # anyway; a list that old is the case worth catching (a one-model
249
251
  # server reloaded with another model).
250
- return unknown_model_message(parsed.id, host, list.ids) if list.age < RELIST_AFTER_SECONDS
252
+ return unknown_model_message(parsed.id, host, list.ids) if list.age(now: now) < RELIST_AFTER_SECONDS
251
253
 
252
254
  fresh_ids = relist_or_nil(relist || default_relist(hosts), host, env)
253
255
  # A re-list that answered: the saved list catches up. The default
@@ -9,6 +9,7 @@ require_relative "pending_question"
9
9
  require_relative "session"
10
10
  require_relative "turn_checkpoint"
11
11
  require_relative "guardrails/parent_policy"
12
+ require_relative "participant_messages"
12
13
 
13
14
  module Samagotchi
14
15
  # How a wait's end (ReplyWait::Result) reads to whoever runs chi as a
@@ -46,8 +47,12 @@ module Samagotchi
46
47
  # answered the step-limit question), removed (the queued message was
47
48
  # taken back before it ran), no_answer, error, worker_gone, stopped,
48
49
  # waiting_for_owner (a participant's turn waits on the owner: chi
49
- # web's participant wait, through --remote) or running
50
+ # web's participant wait, through --remote), refused (a participant's
51
+ # queued turn the worker refused: revoked, expired, at their cap; no
52
+ # turn ran) or running
50
53
  def status(result)
54
+ return "refused" if refused?(result)
55
+
51
56
  case result.status
52
57
  when :done then "answered"
53
58
  when :waiting_for_answer then "question"
@@ -70,6 +75,18 @@ module Samagotchi
70
75
  end
71
76
  end
72
77
 
78
+ # The reasons a worker refuses a participant's queued turn
79
+ # (Worker#participant_refusal), as its settled record's cancel_reason.
80
+ REFUSED_LINES = { "revoked" => ParticipantMessages::TOKEN_ENDED,
81
+ "cap_reached" => ParticipantMessages::CAP_REACHED }.freeze
82
+
83
+ # A participant's turn the worker refused before it ran: by its
84
+ # cancel_reason (chi web's participant wait sends no outcome).
85
+ def refused?(result)
86
+ result.status == :no_reply && REFUSED_LINES.key?(result.cancel_reason.to_s) &&
87
+ [nil, "canceled"].include?(result.outcome)
88
+ end
89
+
73
90
  # @return [Integer] 0 answered (or not continued: the Stop asked for
74
91
  # was carried out), 3 a question waits (or, for a participant, the
75
92
  # owner: waiting_for_owner), 4 still running, 1 anything
@@ -116,6 +133,8 @@ module Samagotchi
116
133
  case status(result)
117
134
  when "failed" then { error_kind: result.error_kind, retryable: result.retryable, kept_steps: result.kept_steps }.compact
118
135
  when "canceled" then { cancel_reason: result.cancel_reason, stopped_by: result.stopped_by }.compact
136
+ # The refusal's code: revoked or cap_reached.
137
+ when "refused" then { cancel_reason: result.cancel_reason }
119
138
  else {}
120
139
  end
121
140
  end
@@ -316,13 +335,21 @@ module Samagotchi
316
335
  turn = turn_id || result.turn_id
317
336
  turn.to_s.empty? ? WAITING_FOR_OWNER : "#{WAITING_FOR_OWNER}: #{via.command("send --wait --turn #{turn} #{session_id}")}"
318
337
  else
319
- turn = turn_id || result.turn_id
320
- wait_again = via.command("send --wait --turn #{turn} #{session_id}") unless turn.to_s.empty?
321
- hint = wait_again || shows
338
+ hint = still_running_hint(session_id, turn_id || result.turn_id, via: via)
322
339
  timeout ? "still running after #{format("%g", timeout)} s: #{hint}" : "still running: #{hint}"
323
340
  end
324
341
  end
325
342
 
343
+ # What a wait that left the turn running (a --timeout, a Ctrl-C) offers
344
+ # next: the wait for that turn when its id is known, else the wait for
345
+ # the session's running turn, with the attach that shows it.
346
+ # @param turn [String, nil] the waited turn's id
347
+ def still_running_hint(session_id, turn, via: ChiInvocation::HERE)
348
+ return via.command("send --wait --turn #{turn} #{session_id}") unless turn.to_s.empty?
349
+
350
+ "#{via.command("send --wait #{session_id}")} waits again; #{via.shows(session_id)} shows it"
351
+ end
352
+
326
353
  # The whole question for stderr: header, text, numbered options, what
327
354
  # else it takes, and the commands that answer it.
328
355
  # @return [String] lines, newline-terminated
@@ -365,6 +392,9 @@ module Samagotchi
365
392
 
366
393
  def no_reply_line(result, session_id = nil, strategy: nil, via: ChiInvocation::HERE)
367
394
  return command_line(result) if result.origin == TurnCheckpoint::COMMAND_ORIGIN
395
+ if refused?(result)
396
+ return "the turn was refused (#{REFUSED_LINES.fetch(result.cancel_reason.to_s)}); no turn ran for it"
397
+ end
368
398
 
369
399
  case result.outcome
370
400
  when "failed" then failed_line(result)
@@ -6,11 +6,22 @@ module Samagotchi
6
6
  # SessionAccess errors a chi --remote client raises for the same codes.
7
7
  # No requires, so any file can use it.
8
8
  module ParticipantMessages
9
+ # 401 token_revoked: the owner revoked the grant, or archived or deleted its session.
10
+ TOKEN_REVOKED = "this review link was revoked by the session's owner"
11
+ # 401 token_expired: the grant's time ran out.
12
+ TOKEN_EXPIRED = "this review link expired: ask the session's owner for a new one"
13
+ # Either of those, where only that the link ended is known: the
14
+ # worker's cancel_reason "revoked" (participants.json reads them
15
+ # removed or past expires_at), as their chi send --wait reports it.
16
+ TOKEN_ENDED = "this review link was revoked or expired"
9
17
  # 403 not_permitted: a route, a command or a shell line only the owner may use.
10
18
  NOT_PERMITTED = "a participant can't do that: only the session's owner can"
11
19
  # 429 too_many_turns: their running turn and its queue are full.
12
20
  TOO_MANY_TURNS = "this participant has too many turns waiting: wait for one to finish"
13
21
  # 429 cap_reached: their grant spent its cap.
14
22
  CAP_REACHED = "this participant's spending cap is reached: ask the session's owner to raise it"
23
+ # Their turn failed (a wait's error, a failed turn's no_reply): never
24
+ # the exception's words or the failure summary, which may name a path.
25
+ TURN_FAILED = "this turn failed: the session's owner can see why"
15
26
  end
16
27
  end
@@ -77,6 +77,16 @@ module Samagotchi
77
77
  AtomicFile.write(File.join(dir, FILE), "#{JSON.pretty_generate({ "participants" => entries })}\n", perm: 0o600)
78
78
  end
79
79
 
80
+ # Web::Grants' on_write for a change to +session_ids+ (nil: the sessions
81
+ # of the grants it changed, a revoke's result): their sidecars rewritten
82
+ # from the grants just written, under the store's lock (two writers, chi
83
+ # web and chi share, can't finish out of order and lose a revoke here).
84
+ def sidecar_writer(state_dir, session_ids = nil)
85
+ lambda do |all, result|
86
+ (session_ids || result.map(&:session_id).uniq).each { |sid| write(sid, all.select { |grant| grant.session_id == sid }, state_dir: state_dir) }
87
+ end
88
+ end
89
+
80
90
  # One audit line: {"at", "event", …fields}. Nothing for a session whose
81
91
  # dir is gone (deleted, pruned).
82
92
  def log(session_id, event, state_dir: Session.default_state_dir, at: Time.now, **fields)
@@ -98,8 +108,8 @@ module Samagotchi
98
108
  raise Web::Grants::Invalid, "session #{session_id[0, 8]} is archived: unarchive it to invite anyone"
99
109
  end
100
110
 
101
- issued = grants.issue(session_id: session_id, name: name, kind: kind, ttl: ttl, cap: cap)
102
- write(session_id, grants.list(session_id: session_id), state_dir: state_dir)
111
+ issued = grants.issue(session_id: session_id, name: name, kind: kind, ttl: ttl, cap: cap,
112
+ on_write: sidecar_writer(state_dir, [session_id]))
103
113
  grant = issued.grant
104
114
  log(session_id, :issued, state_dir: state_dir, participant: grant.id, name: grant.name, kind: grant.kind,
105
115
  role: grant.role, expires_at: grant.expires_at, cap: grant.spend_cap)
@@ -111,9 +121,9 @@ module Samagotchi
111
121
  # @return [Web::Grants::Grant, nil] nil when +id+ isn't an active grant there
112
122
  # @raise [Web::Grants::Invalid] a cap out of range
113
123
  def set_cap(grants, session_id:, id:, cap:, state_dir: Session.default_state_dir)
114
- grant = grants.set_cap(id, cap, session_id: session_id) or return nil
124
+ grant = grants.set_cap(id, cap, session_id: session_id, on_write: sidecar_writer(state_dir, [session_id]))
125
+ return nil unless grant
115
126
 
116
- write(session_id, grants.list(session_id: session_id), state_dir: state_dir)
117
127
  log(session_id, :cap, state_dir: state_dir, participant: grant.id, cap: grant.spend_cap)
118
128
  grant
119
129
  end
@@ -126,9 +136,8 @@ module Samagotchi
126
136
  # affected session's sidecar and audit trail along.
127
137
  # @return [Array<Web::Grants::Grant>] the grants it revoked
128
138
  def revoke(grants, session_id: nil, id: nil, by: "owner", state_dir: Session.default_state_dir)
129
- revoked = grants.revoke(session_id: session_id, id: id, by: by)
139
+ revoked = grants.revoke(session_id: session_id, id: id, by: by, on_write: sidecar_writer(state_dir))
130
140
  revoked.group_by(&:session_id).each do |sid, ended|
131
- write(sid, grants.list(session_id: sid), state_dir: state_dir)
132
141
  ended.each { |grant| log(sid, :revoked, state_dir: state_dir, participant: grant.id, by: by) }
133
142
  end
134
143
  revoked
@@ -137,9 +146,14 @@ module Samagotchi
137
146
  # Ends the grants of sessions that were archived or deleted
138
147
  # (SessionManager): +by+ "archive" or "delete". Nothing is written for a
139
148
  # session nobody was invited to.
149
+ # A grants store that doesn't read (Web::Grants::Corrupt) doesn't stop
150
+ # the archive or delete: its links already find no grant, and the
151
+ # store itself says so (Log.warn) until it's fixed.
140
152
  def end_sessions(session_ids, by:, state_dir: Session.default_state_dir)
141
153
  grants = Web::Grants.new(Web::Grants.path(state_dir: state_dir))
142
154
  session_ids.each { |sid| revoke(grants, session_id: sid, by: by, state_dir: state_dir) }
155
+ rescue Web::Grants::Corrupt
156
+ nil
143
157
  end
144
158
  end
145
159
  end
@@ -41,7 +41,8 @@ module Samagotchi
41
41
  "ctx.use_toolkit" => "0.66.0", "ctx.toolkit" => "0.66.0", "ctx.declared_tools" => "0.66.0",
42
42
  "chi.tool_source" => "0.67.0", "chi.peer_source" => "0.67.0", "ctx.http" => "0.80.0",
43
43
  "ctx.cost" => "0.83.0", "ctx.sessions.children" => "0.34.0", "ctx.load_tools" => "0.99.0",
44
- "ctx.usage" => "0.100.0"
44
+ "ctx.usage" => "0.100.0", "ctx.sessions.stop" => "0.34.0", "ctx.turn_author" => "0.106.0",
45
+ "ctx.sessions.review" => "0.107.0"
45
46
  }.freeze
46
47
 
47
48
  # @param bundle [String]
@@ -7,6 +7,8 @@ require_relative "../bridge_client"
7
7
  require_relative "../bridge/turn_accumulator"
8
8
  require_relative "../tools/delegate"
9
9
  require_relative "../children_status"
10
+ require_relative "../review_start"
11
+ require_relative "../model_profile"
10
12
 
11
13
  module Samagotchi
12
14
  # Loaded on first use: this autoload keeps SessionManager and its ~80
@@ -60,6 +62,29 @@ module Samagotchi
60
62
  child.id
61
63
  end
62
64
 
65
+ # A review of this session (ReviewStart.fork, chi review --from): a new
66
+ # session in its folder, on its model and setup, seeded with its recap
67
+ # (never its transcript) and +seed+ (more context: the coordinator's
68
+ # handoff, say), idle, to share with participants (chi share). This
69
+ # session keeps running, unarchived. Not a child: it has no parent.
70
+ # The recap is the one saved (the worker is asked for a fresh one, not
71
+ # waited on unless +recap_wait+ seconds are given: this runs in this
72
+ # session's own worker).
73
+ # @param subjects [Array<String>] files under review, relative to its
74
+ # folder (ReviewStart.check_subjects)
75
+ # @return [String] the review session's id
76
+ # @raise [Error] no session yet, a scratch session, a subject refused
77
+ # (its one message), or it could not start
78
+ def review(subjects: [], seed: nil, recap_wait: 0)
79
+ source = @host.session_id.call or raise Error, "this session has no id yet"
80
+ raise Error, "a scratch session starts no other sessions: they would outlive it" if @host.scratch&.call
81
+
82
+ ReviewStart.fork(from: source, subjects: Array(subjects), seed: seed, state_dir: state_dir,
83
+ recap_wait: recap_wait).id
84
+ rescue ReviewStart::Refused, ModelProfile::MissingModel, ArgumentError => e
85
+ raise Error, e.message
86
+ end
87
+
63
88
  # Send +text+ to session +id+ as a user message (it runs as a turn;
64
89
  # a stopped session is woken). Waits up to 5 s for its worker, so call
65
90
  # it from an anytime command or your own thread, never a tool or hook
@@ -27,7 +27,7 @@ module Samagotchi
27
27
  in #{Paths.tilde(Remotes.path)} (0600); an existing NAME is replaced.
28
28
  ls [--format json] the remotes (never their tokens)
29
29
  rm NAME forget one
30
- Then: chi --remote NAME send|answer|note|context|sessions …, or CHI_REMOTE=NAME.
30
+ Then: chi --remote NAME send|answer|note|context|sessions|share|review …, or CHI_REMOTE=NAME.
31
31
  TEXT
32
32
 
33
33
  SUBCOMMANDS = %w[add ls rm].freeze
@@ -17,7 +17,8 @@ module Samagotchi
17
17
  # url: http://192.168.1.29:4567
18
18
  # token: …
19
19
  #
20
- # chi remote add / ls / rm write and read it (RemoteCommand).
20
+ # chi remote add / ls / rm write and read it (RemoteCommand); a write
21
+ # replaces it whole (AtomicFile) under remotes.yml.lock.
21
22
  module Remotes
22
23
  FILE = "remotes.yml"
23
24
  # A name as git takes a remote's, short: letters, digits, - and _.
@@ -27,7 +28,8 @@ module Samagotchi
27
28
  # path) and its access +token+ (nil for a loopback chi web, which needs
28
29
  # none). #inspect leaves the token out.
29
30
  Entry = Data.define(:name, :url, :token) do
30
- def host = URI(url).host
31
+ # The host as an address, an IPv6 one bare (::1, not [::1]).
32
+ def host = URI(url).hostname
31
33
 
32
34
  # How a failure names it: "remote studio (http://192.168.1.29:4567)".
33
35
  def label = "remote #{name} (#{url})"
@@ -80,17 +82,19 @@ module Samagotchi
80
82
 
81
83
  # Saves +entry+, replacing one of its name.
82
84
  def put(entry, path: self.path)
83
- write(all(path: path).reject { |other| other.name == entry.name } + [entry], path)
85
+ locked(path) { write(all(path: path).reject { |other| other.name == entry.name } + [entry], path) }
84
86
  end
85
87
 
86
88
  # @return [Boolean] whether there was one
87
89
  def remove(name, path: self.path)
88
- entries = all(path: path)
89
- kept = entries.reject { |entry| entry.name == name }
90
- return false if kept.size == entries.size
90
+ locked(path) do
91
+ entries = all(path: path)
92
+ kept = entries.reject { |entry| entry.name == name }
93
+ next false if kept.size == entries.size
91
94
 
92
- write(kept, path)
93
- true
95
+ write(kept, path)
96
+ true
97
+ end
94
98
  end
95
99
 
96
100
  # @raise [Invalid] unless +name+ is one
@@ -120,6 +124,17 @@ module Samagotchi
120
124
  raise Invalid, "give chi web's address, http://HOST:PORT, not #{text}"
121
125
  end
122
126
 
127
+ # The read-modify-write of +path+ under <path>.lock (0600), so two
128
+ # chi remote add / rm at once never drop each other's entry.
129
+ def locked(path)
130
+ FileUtils.mkdir_p(File.dirname(path))
131
+ File.open("#{path}.lock", File::RDWR | File::CREAT, 0o600) do |lock|
132
+ lock.flock(File::LOCK_EX)
133
+ yield
134
+ end
135
+ end
136
+ private_class_method :locked
137
+
123
138
  def write(entries, path)
124
139
  FileUtils.mkdir_p(File.dirname(path))
125
140
  remotes = entries.sort_by(&:name).to_h { |entry| [entry.name, { "url" => entry.url, "token" => entry.token }.compact] }
@@ -221,10 +221,15 @@ module Samagotchi
221
221
  # merged): that turn runs (its mark has another id, or none from a
222
222
  # worker that writes ids), or, idle, a turn not its ended since the
223
223
  # baseline. last_turn or a reply file being its own is never that, nor
224
- # an input with a tombstone (a removal's, written before its claim).
224
+ # an input with a tombstone (a removal's, written before its claim),
225
+ # nor one whose claimed file is still there: a drain deletes the file
226
+ # it merges as it reads it, while a turn of its own keeps it until the
227
+ # turn ends (WorkerInbound#take_input), so a look between that claim
228
+ # and the turn's running save (idle, an earlier turn's end since the
229
+ # baseline) doesn't take the earlier turn's reply for it.
225
230
  def merged_elsewhere?(session, turn, baseline, session_dir)
226
231
  return false if session.last_turn&.enqueued_id == turn || SessionInbox.reply_for(session_dir, turn)
227
- return false if SessionInbox.removed?(session_dir, turn)
232
+ return false if SessionInbox.removed?(session_dir, turn) || SessionInbox.claimed_input?(session_dir, turn)
228
233
 
229
234
  if session.status == Session::STATUS_RUNNING
230
235
  running_id = session.interrupted_turn&.enqueued_id