samagotchi 0.32.0 → 0.34.0

data/lib/samagotchi/guardrails/context.rb

@@ -50,6 +50,38 @@ module Samagotchi
       def common_dir(dir) = info(dir)[:common_dir]
       def branch(dir) = info(dir)[:branch]
 
+      # Every checkout of +dir+'s repository that is still there: the main
+      # one (the folder holding a common .git dir that isn't bare) and each
+      # linked worktree (<common dir>/worktrees/*/gitdir names its .git
+      # file; a relative one is relative to that admin dir). Read from the
+      # files, no git process, on every call (not memoized: a worktree
+      # added mid-turn counts at once); [] outside a repo.
+      # @return [Array<String>] absolute folders
+      def worktrees(dir)
+        common = common_dir(dir) or return []
+        self.class.checkouts(common)
+      end
+
+      # @param common [String] an absolute common git dir
+      def self.checkouts(common)
+        main = File.basename(common) == ".git" && !bare?(common) ? [File.dirname(common)] : []
+        linked = Dir[File.join(common, "worktrees", "*", "gitdir")].sort.filter_map do |file|
+          gitdir = File.read(file).strip
+          next if gitdir.empty?
+
+          File.dirname(File.expand_path(gitdir, File.dirname(file)))
+        rescue SystemCallError
+          nil
+        end
+        (main + linked).select { |folder| File.directory?(folder) }.uniq
+      end
+
+      def self.bare?(common)
+        File.read(File.join(common, "config")).match?(/^\s*bare\s*=\s*true\s*$/i)
+      rescue SystemCallError
+        false
+      end
+
       private
 
       def info(dir)

data/lib/samagotchi/guardrails/parent_approvals.rb

@@ -30,8 +30,6 @@ module Samagotchi
     # rewrite would be "allow everything" from then on.
     module ParentApprovals
       KEY = "guardrails.parent_approvals"
-      # The client id chi answer posts its answers with.
-      CLIENT_ID = "cli:answer"
       # Set by chi's execute and task_create for the commands they run: a
       # chi started there answers as a parent (#parent_process?).
       PARENT_SESSION_ENV = "SAMAGOTCHI_PARENT_SESSION"

data/lib/samagotchi/guardrails/shared_git.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative "shell_lex"
+require_relative "shell_git_dirs"
+
+module Samagotchi
+  module Guardrails
+    # Whether a shell command runs git that changes what every checkout of
+    # the repository shares (its common git dir), wherever it runs: from a
+    # worktree these reach the main checkout and the siblings too.
+    #   config     a write without --worktree (or --file/--blob, whose
+    #              path the caller checks); --get, --list, `config get`
+    #              and a lone key only read
+    #   update-ref always
+    #   worktree   add, remove, move, prune, lock, unlock, repair
+    #   stash      drop, clear, pop (one stash list for all)
+    #   tag        creating or deleting one (not listing or verifying)
+    #   branch     delete, force or a forced move/copy, of a branch other
+    #              than +own_branch+ (any, when that is unknown)
+    # Pure text, as ShellGitDirs: sh -c, aliases and $(…) get through.
+    module SharedGit
+      WORKTREE_CHANGES = %w[add remove move prune lock unlock repair].freeze
+      STASH_CHANGES = %w[drop clear pop].freeze
+      CONFIG_READS = %w[--get --get-all --get-regexp --get-urlmatch --list -l --get-color --get-colorbool].freeze
+      CONFIG_WRITES = %w[--unset --unset-all --add --replace-all --rename-section --remove-section -e --edit].freeze
+      CONFIG_OWN_FILE = %w[--worktree -f --file --blob].freeze
+      # config options that take the next word as their value.
+      CONFIG_VALUES = %w[--type --default --comment -f --file --blob].freeze
+      TAG_READS = %w[-l --list -n -v --verify --contains --no-contains --points-at --merged --no-merged].freeze
+      TAG_WRITES = %w[-d --delete -f --force -a --annotate -s --sign -u -m -F].freeze
+      BRANCH_DELETE = %w[-d -D --delete].freeze
+      BRANCH_MOVE = %w[-m --move -c --copy].freeze
+      BRANCH_FORCED_MOVE = %w[-M -C].freeze
+
+      module_function
+
+      # @param command [String]
+      # @param own_branch [String, nil] the branch checked out where the
+      #   session works
+      def changes?(command, own_branch: nil)
+        ShellLex.simple_commands(ShellLex.lex(command.to_s)).any? do |words|
+          next false unless words.is_a?(Array)
+
+          sub, args = git_call(words)
+          sub && changes_shared?(sub, args, own_branch)
+        end
+      rescue ArgumentError, EncodingError
+        false
+      end
+
+      # [subcommand, its args] of a git simple command, or nil.
+      def git_call(words)
+        words = words.drop_while { |w| w.match?(/\A[A-Za-z_]\w*=/) || ShellGitDirs::PREFIXES.include?(w) }
+        verb = words.first
+        return nil unless verb == "git" || verb.to_s.end_with?("/git")
+
+        args = words.drop(1).grep_v(ShellLex::REDIRECT)
+        until args.empty?
+          arg = args.shift
+          if ShellGitDirs::VALUE_OPTIONS.include?(arg) then args.shift
+          elsif !arg.start_with?("-") then return [arg, args]
+          end
+        end
+        nil
+      end
+
+      def changes_shared?(sub, args, own_branch)
+        case sub
+        when "config" then config_writes?(args)
+        when "update-ref" then true
+        when "worktree" then WORKTREE_CHANGES.include?(args.first)
+        when "stash" then STASH_CHANGES.include?(args.first)
+        when "tag" then tag_changes?(args)
+        when "branch" then branch_changes?(args, own_branch)
+        else false
+        end
+      end
+
+      def config_writes?(args)
+        return false if args.any? { |a| CONFIG_OWN_FILE.include?(a) || a.start_with?("--file=", "--blob=") }
+        return false if %w[get list].include?(args.first)
+        return true if %w[set unset rename-section remove-section edit].include?(args.first)
+        return false if args.any? { |a| CONFIG_READS.include?(a) }
+        return true if args.any? { |a| CONFIG_WRITES.include?(a) }
+
+        operands(args, CONFIG_VALUES).size >= 2
+      end
+
+      def tag_changes?(args)
+        return true if args.any? { |a| TAG_WRITES.include?(a) }
+        return false if args.empty? || args.any? { |a| TAG_READS.include?(a) || a.start_with?("--list=", "--contains=", "--points-at=") }
+
+        !operands(args, []).empty?
+      end
+
+      # The branches a branch command deletes or overwrites (a plain -m/-c
+      # only moves its source; its new name doesn't exist yet).
+      def branch_changes?(args, own_branch)
+        names = operands(args, %w[-u --set-upstream-to -t --track])
+        targets = if args.any? { |a| BRANCH_DELETE.include?(a) } then names
+                  elsif args.any? { |a| BRANCH_FORCED_MOVE.include?(a) } then names.size >= 2 ? names : [own_branch, *names]
+                  elsif args.any? { |a| BRANCH_MOVE.include?(a) } then names.size >= 2 ? [names.first] : []
+                  elsif args.any? { |a| %w[-f --force].include?(a) } then names.first(1)
+                  else []
+                  end
+        targets.any? { |name| own_branch.nil? || name != own_branch }
+      end
+
+      def operands(args, value_options)
+        rest = args.dup
+        found = []
+        until rest.empty?
+          arg = rest.shift
+          if value_options.include?(arg) then rest.shift
+          elsif arg == "--" then found.concat(rest)
+                                 break
+          elsif !arg.start_with?("-") then found << arg
+          end
+        end
+        found
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails.rb

@@ -12,6 +12,7 @@ require_relative "guardrails/approval"
 require_relative "guardrails/approvals"
 require_relative "guardrails/protected_paths"
 require_relative "guardrails/scratch_writes"
+require_relative "guardrails/child_boundary"
 require_relative "guardrails/load_failures"
 require_relative "guardrails/rules"
 require_relative "guardrails/gate"

data/lib/samagotchi/kernel_loop.rb

@@ -13,6 +13,7 @@ require_relative "client"
 require_relative "llm/errors"
 require_relative "log"
 require_relative "empty_answer_retry"
+require_relative "cut_policy"
 require_relative "thinking"
 require_relative "hooks"
 require_relative "pending_input_queue"
@@ -444,31 +445,17 @@ module Samagotchi
                                      messages: AnswerDisplay.strip_all(turn.conversation).map(&:dup).freeze })
     end
 
-    # A generation a plugin cut is an empty answer made early. Queued input
-    # (a user's line, a plugin's steer) goes in first, with or without a
-    # retry left, and spends no attempt: the model answers it. A steer's cut
-    # (Engine#cut_for_steer) with nothing queued (its message was taken at
-    # a boundary already) is asked again as is. Else it is asked again with
-    # its own nudge while the retry budget lasts, else the turn ends as
-    # cancelled (hook), with nothing salvaged and without the spent nudge.
-    # A Stop that came right after the cut is a plain cancel. Returns :next
-    # or the turn's result.
+    # A cut generation (CutPolicy): a Stop after it raises as any cancel,
+    # the turn going on is :next, the hook ending is the turn's result.
     def after_cut(turn, generation)
       cut = generation.cut
-      raise Client::RequestCancelled, turn.cancel_controller.reason if turn.cancel_controller.cancelled?
+      outcome = CutPolicy.decide(cut: cut, cancel_controller: turn.cancel_controller, empty_retry: turn.empty_retry,
+                                 conversation: turn.conversation, iteration: turn.iteration, emit: turn.emit,
+                                 inject: -> { inject_pending_input!(turn) },
+                                 finish_reason: "stopped", thinking_chars: generation.streamed_thinking)
+      raise Client::RequestCancelled, turn.cancel_controller.reason if outcome.stopped?
+      return :next if outcome.again?
 
-      # The row under the cut step, above the message it was cut for.
-      emit(turn, type: :steer_cut, iteration: turn.iteration, source: cut[:source].to_s) if cut[:steer]
-      return :next if inject_pending_input!(turn) || cut[:steer]
-
-      if turn.empty_retry.left?
-        turn.empty_retry.nudge!(turn.conversation, TurnNote.cut_retry(cut[:by], cut[:reason]),
-                                emit: turn.emit, iteration: turn.iteration, finish_reason: "stopped",
-                                thinking_chars: generation.streamed_thinking, stopped_by: cut[:by])
-        return :next
-      end
-      turn.empty_retry.drop_nudge!(turn.conversation)
-      turn.cancel_controller.cancel!(:hook, cut)
       emit(turn, type: :generation_cancelled, iteration: turn.iteration, reason: :hook, stopped_by: cut[:by])
       cancelled_result(turn.conversation, tool_activity: turn.tool_activity, reason: :hook, partial_assistant_text: "")
     end

data/lib/samagotchi/llm/chat_loop.rb

@@ -10,6 +10,7 @@ require_relative "openai_chat"
 require_relative "native_tool_normalizer"
 require_relative "../kernel_loop"
 require_relative "../answer_display"
+require_relative "../cut_policy"
 require_relative "../context_status"
 require_relative "../context_window"
 require_relative "../context_note"
@@ -396,30 +397,18 @@ module Samagotchi
                               thinking_chars: response.reasoning.to_s.length)
         end
 
-        # A generation a plugin cut (stop_generation) is an empty answer made
-        # early. Queued input (a user's line, a plugin's steer) goes in
-        # first, with or without a retry left, and spends no attempt. A
-        # steer's cut (Engine#cut_for_steer) with nothing queued is asked
-        # again as is. Else it is asked again with its own nudge while the
-        # retry budget lasts, else the turn ends as cancelled (hook), with
-        # nothing salvaged and without a spent nudge. A Stop that came right
-        # after the cut is a plain cancel. Returns :retry, or the turn's
-        # result.
+        # A cut generation (CutPolicy): a Stop after it ends the turn as
+        # any cancel, the turn going on is :retry, the hook ending is the
+        # turn's result.
         def after_cut(iteration, response)
-          return canceled(iteration, @cancel_controller.reason) if @cancel_controller.cancelled?
+          outcome = CutPolicy.decide(cut: response.cut, cancel_controller: @cancel_controller, empty_retry: @empty_retry,
+                                     conversation: @conversation, iteration: iteration, emit: method(:emit),
+                                     inject: -> { inject_pending_input(iteration) },
+                                     finish_reason: response.finish_reason,
+                                     thinking_chars: response.reasoning.to_s.length)
+          return canceled(iteration, @cancel_controller.reason) if outcome.stopped?
+          return :retry if outcome.again?
 
-          # The row under the cut step, above the message it was cut for.
-          emit(type: :steer_cut, iteration: iteration, source: response.cut[:source].to_s) if response.cut[:steer]
-          return :retry if inject_pending_input(iteration) || response.cut[:steer]
-
-          if @empty_retry.left?
-            @empty_retry.nudge!(@conversation, TurnNote.cut_retry(response.cut[:by], response.cut[:reason]),
-                                emit: method(:emit), iteration: iteration, finish_reason: response.finish_reason,
-                                thinking_chars: response.reasoning.to_s.length, stopped_by: response.cut[:by])
-            return :retry
-          end
-          @empty_retry.drop_nudge!(@conversation)
-          @cancel_controller.cancel!(:hook, response.cut)
           canceled(iteration, :hook)
         end
 

data/lib/samagotchi/memory_bundle/builder.rb

@@ -5,6 +5,7 @@ require "fileutils"
 require "tmpdir"
 require_relative "manifest"
 require_relative "placeholder"
+require_relative "../context_providers"
 require_relative "../memory_paths"
 require_relative "../model_overlay"
 
@@ -152,6 +153,10 @@ module Samagotchi
         requires_chi = prov_data && prov_data[:requires_chi]
         needs = prov_data && prov_data[:needs]
 
+        # ── Scripts and context providers: the installed bundle's ──
+        scripts_to_copy = installed_scripts(prov, prov_data)
+        context_providers = prov_data ? ContextProviders.parse_list(prov_data[:context_providers]) : []
+
         # Determine trust_level for the built bundle
         build_trust_level = @trust_level
         if (build_trust_level.nil? || build_trust_level.empty?) && prov_data && prov_data[:trust_level]
@@ -185,6 +190,11 @@ module Samagotchi
 
           FileUtils.cp(plugin_src, File.join(staging, File.basename(plugin_src))) if plugin_src
 
+          unless scripts_to_copy.empty?
+            FileUtils.mkdir_p(File.join(staging, "scripts"))
+            scripts_to_copy.each_value { |src| FileUtils.cp(src, File.join(staging, "scripts", File.basename(src))) }
+          end
+
           Manifest.write(
             dir: staging,
             name: resolved_name,
@@ -196,7 +206,10 @@ module Samagotchi
             trust_level: build_trust_level,
             plugin: plugin_src && { file: File.basename(plugin_src), sha256: Digest::SHA256.hexdigest(File.binread(plugin_src)) },
             requires_chi: requires_chi,
-            needs: needs
+            needs: needs,
+            scripts: scripts_to_copy.transform_values { |src| "sha256:#{Digest::SHA256.hexdigest(File.binread(src))}" },
+            context_providers: context_providers,
+            file_descriptions: file_descriptions(prov_data, files_map)
           )
 
           case format
@@ -255,6 +268,27 @@ module Samagotchi
 
       private
 
+      # The installed bundle's scripts its record lists, file name => path
+      # in its scripts/ (a missing one is left out); {} without a record.
+      def installed_scripts(prov, prov_data)
+        return {} unless prov && prov_data && prov_data[:scripts].is_a?(Hash)
+
+        prov_data[:scripts].keys.map(&:to_s).sort.to_h { |file| [file, File.join(prov.scripts_dir, file)] }
+                           .select { |_, path| File.file?(path) }
+      end
+
+      # The descriptions the installed bundle's record keeps for the files
+      # being built (its manifest's files: mappings), so a rebuild writes
+      # them back; {} without a record.
+      def file_descriptions(prov_data, files_map)
+        return {} unless prov_data && prov_data[:files].is_a?(Hash)
+
+        prov_data[:files].each_with_object({}) do |(key, entry), acc|
+          text = entry.is_a?(Hash) ? entry[:description].to_s : ""
+          acc[key.to_s] = text if files_map.key?(key.to_s) && !text.empty?
+        end
+      end
+
       # Without an allowlist, a memory another installed bundle owns (its
       # record lists it) isn't the user's to share: left out, one line
       # each. The bundle being built (same name) keeps its own.

data/lib/samagotchi/memory_bundle/installer.rb

@@ -92,6 +92,7 @@ module Samagotchi
         FileUtils.mkdir_p(target_dir)
 
         # Copy .md files and update index for each.
+        @file_descriptions = manifest&.file_descriptions || {}
         all_files_in_bundle = []
         provenance = Provenance.new(name: @name)
         existing_provenance = provenance.read
@@ -421,7 +422,8 @@ module Samagotchi
             needs: manifest.needs,
             conflicts: @conflicts.keys,
             scripts_files: scripts_for_provenance,
-            context_providers: manifest.context_providers
+            context_providers: manifest.context_providers,
+            file_descriptions: manifest.file_descriptions
           )
         end
 
@@ -695,7 +697,9 @@ module Samagotchi
           # Index lines use the entry name (as memory_write does); drop the
           # legacy "name.md" line older installs wrote.
           IndexUpdater.remove_index(scope, file_key) unless entry_name == file_key
-          IndexUpdater.update_index(scope, entry_name, byte_count, source: owned ? @name : nil)
+          # A manifest's description: for the file; nil keeps the line's.
+          description = owned ? @file_descriptions&.[](file_key) : nil
+          IndexUpdater.update_index(scope, entry_name, byte_count, description, source: owned ? @name : nil)
         rescue StandardError => e
           # Not fatal (the file is in place): a warning says so.
           @warnings << "index.md: line for #{entry_name} not updated (#{e.message})"

data/lib/samagotchi/memory_bundle/manifest.rb

@@ -16,7 +16,9 @@ module Samagotchi
     #   description: "…"       # optional
     #   files:
     #     identity.md: sha256:abc123...
-    #     commit_preferences.md: sha256:def456...
+    #     skill_x.md:          # or a mapping: the description is the
+    #       sha256: sha256:def456...   #   memory's index.md line
+    #       description: "Use when …"
     #   plugin:                # optional — the bundle's plugin.rb (docs/plugins.md)
     #     file: plugin.rb
     #     sha256: sha256:0a1b...
@@ -50,7 +52,9 @@ module Samagotchi
       # A bundle name, as `chi bundle install <name>` takes a shipped one.
       BUNDLE_NAME = /\A[A-Za-z0-9][A-Za-z0-9_-]*\z/
 
-      attr_reader :name, :version, :scope, :description, :files, :hooks, :trust_level, :plugin, :requires_chi, :needs, :includes,
+      # files: name → "sha256:<hex>" (both forms); file_descriptions: name →
+      # the description a mapping gave, for the files that have one.
+      attr_reader :name, :version, :scope, :description, :files, :file_descriptions, :hooks, :trust_level, :plugin, :requires_chi, :needs, :includes,
                   :scripts, :context_providers
 
       def initialize(path:)
@@ -62,6 +66,7 @@ module Samagotchi
         @description = (raw["description"] || "").to_s
         @files    = parse_files(raw["files"] || {})
         @hooks    = parse_hooks(raw["hooks"] || {})
+        @file_descriptions = parse_file_descriptions(raw["files"])
         @trust_level = (raw["trust_level"] || "experimental").to_s
         @plugin = parse_plugin(raw["plugin"])
         @requires_chi = parse_requires_chi(raw["requires_chi"])
@@ -123,8 +128,9 @@ module Samagotchi
       end
 
       # Writes a fresh manifest.yml from computed checksums at `dir`.
+      # +file_descriptions+ (name → text) writes those files as mappings.
       def self.write(dir:, name:, version:, files:, scope: nil, description: "", hooks: nil, trust_level: nil,
-                     plugin: nil, requires_chi: nil, needs: nil)
+                     plugin: nil, requires_chi: nil, needs: nil, scripts: {}, context_providers: [], file_descriptions: {})
         FileUtils.mkdir_p(dir)
         manifest = {
           "name" => name,
@@ -132,7 +138,10 @@ module Samagotchi
           "description" => description
         }
         manifest["scope"] = scope if scope
-        manifest["files"] = files # { "file.md" => "sha256:abc..." }
+        manifest["files"] = files.to_h do |key, sha| # { "file.md" => "sha256:abc..." }
+          text = file_descriptions[key].to_s.strip
+          [key, text.empty? ? sha : { "sha256" => sha, "description" => text }]
+        end
         if hooks && !hooks.empty?
           # Normalize hooks to string-keyed with sha256 prefix preserved
           manifest["hooks"] = hooks.transform_keys(&:to_s).transform_values do |v|
@@ -149,6 +158,8 @@ module Samagotchi
         manifest["requires_chi"] = requires_chi.to_s if requires_chi && !requires_chi.to_s.empty?
         needs = parse_needs(needs)
         manifest["needs"] = needs.map { |n| n.transform_keys(&:to_s).compact } unless needs.empty?
+        manifest["scripts"] = scripts.transform_keys(&:to_s) unless scripts.empty?
+        manifest["context_providers"] = context_providers.map(&:to_h) unless context_providers.empty?
         File.write(File.join(dir, "manifest.yml"), YAML.dump(manifest))
       end
 
@@ -203,7 +214,7 @@ module Samagotchi
         raw.each_with_object({}) do |(k, v), acc|
           next unless k.is_a?(String) && !k.empty?
 
-          str = v.to_s
+          str = (v.is_a?(Hash) ? v["sha256"] : v).to_s
           acc[k] = if str.start_with?("sha256:")
                      str
                    else
@@ -212,6 +223,18 @@ module Samagotchi
         end
       end
 
+      # The descriptions of the files: entries given as a mapping.
+      def parse_file_descriptions(raw)
+        return {} unless raw.is_a?(Hash)
+
+        raw.each_with_object({}) do |(k, v), acc|
+          next unless k.is_a?(String) && v.is_a?(Hash)
+
+          text = v["description"].to_s.strip
+          acc[k] = text unless text.empty?
+        end
+      end
+
       # plugin: {file:, sha256:} → {file:, sha256:} (sha "" when not given),
       # or nil; a file that isn't a plain .rb name is a validation error.
       def parse_plugin(raw)

data/lib/samagotchi/memory_bundle/provenance.rb

@@ -140,7 +140,7 @@ module Samagotchi
       # @param context_providers [Array<ContextProviders::Provider>]
       def write(files:, scope:, version:, source_path:, hooks: {}, trust_level: nil, source_commit: nil, hooks_files: {},
                 guardrails_files: {}, plugin_file: nil, requires_chi: nil, needs: nil, conflicts: [], includes: nil,
-                scripts_files: {}, context_providers: [])
+                scripts_files: {}, context_providers: [], file_descriptions: {})
         FileUtils.mkdir_p(@bundle_dir)
         bases_dir = File.join(@bundle_dir, "bases")
         FileUtils.mkdir_p(bases_dir)
@@ -158,6 +158,7 @@ module Samagotchi
           File.write(File.join(bases_dir, file_key), content)
           merged_entries[file_key] = { checksum: checksum }
           merged_entries[file_key][:conflict] = true if conflicts.include?(file_key.to_s)
+          merged_entries[file_key][:description] = file_descriptions[file_key.to_s] if file_descriptions[file_key.to_s]
         end
 
         # Prune stale base snapshots for files no longer in the bundle.

data/lib/samagotchi/memory_paths.rb

@@ -59,6 +59,16 @@ module Samagotchi
       dot_git && File.dirname(dot_git)
     end
 
+    # The git dir of the work tree holding +cwd+: .git itself in a main
+    # checkout, the worktree's own dir under .git/worktrees in a linked one
+    # (where HEAD is that worktree's); nil outside any repository.
+    def git_dir(cwd = Dir.pwd)
+      dot_git = find_dot_git(cwd)
+      return nil unless dot_git
+
+      File.directory?(dot_git) ? dot_git : gitdir_from_file(dot_git)
+    end
+
     # Is +cwd+ inside a git repository (a .git somewhere above it)?
     def in_repo?(cwd = Dir.pwd)
       !find_dot_git(cwd).nil?

data/lib/samagotchi/plugin/api.rb

@@ -47,8 +47,8 @@ module Samagotchi
       # show (a String) or nil for nothing. A raise is shown as an error.
       # @param name [String] "/name"; a name the session already has
       #   (built-in or another bundle's) is a load error
-      # @param anytime [Boolean] may run while a turn runs (from P2; today
-      #   it runs as other commands do)
+      # @param anytime [Boolean] runs at once on its own thread, beside a
+      #   running turn, instead of being refused as busy (docs/plugins.md)
       def command(name, description, anytime: false, &block)
         raise ArgumentError, "command #{name.inspect} needs a block" unless block
 

data/lib/samagotchi/plugin/sessions.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+require_relative "../client_id"
 require_relative "../session"
 require_relative "../bridge_client"
 require_relative "../bridge/turn_accumulator"
 require_relative "../tools/delegate"
+require_relative "../children_status"
 
 module Samagotchi
   # Loaded on first use: session_manager requires terminal_ui, which
@@ -15,7 +17,11 @@ module Samagotchi
     # plugin. A fork is an ordinary chi session in its own worker, shown in
     # every list as a child of this one (↳ parent).
     class Sessions
-      # A fork, send or read that couldn't be done; the message says why.
+      # How long #stop waits for the child's worker to let go, as the web's
+      # stop does.
+      STOP_WAIT = 2
+
+      # A fork, send, read or stop that couldn't be done; the message says why.
       class Error < StandardError; end
 
       # @param host [Host] session_id, cwd, model_name and state_dir
@@ -62,7 +68,7 @@ module Samagotchi
 
         state_dir = self.state_dir
         sid = resolve(id, state_dir)
-        delivered = SessionManager.deliver_turn(sid, prompt: text.to_s, client_id: "plugin", state_dir: state_dir)
+        delivered = SessionManager.deliver_turn(sid, prompt: text.to_s, client_id: ClientId::PLUGIN, state_dir: state_dir)
         case delivered[:status]
         when :accepted then sid
         when :refused then raise Error, "session #{sid[0, 8]} refused the message (#{delivered.dig(:ack, "error")})"
@@ -95,10 +101,49 @@ module Samagotchi
           running: running, messages: without_system_head(messages) }
       end
 
+      # This session's children, newest first (ChildrenStatus.of): delegates
+      # and forks (delegate: false), archived ones only with +all+. It reads
+      # every session's file, so call it on demand, not in a loop.
+      # @return [Array<Hash>] frozen ChildrenStatus::Child fields (symbol
+      #   keys); [] with no session yet
+      def children(all: false)
+        parent_id = @host.session_id.call or return []
+
+        ChildrenStatus.of(parent_id, state_dir: state_dir, include_archived: all).map { |child| child.to_h.freeze }
+      end
+
+      # Stop one of this session's own children as `chi sessions stop` does
+      # (by session id; no pid is read here), waiting up to STOP_WAIT s for
+      # its worker to let go.
+      # @return [String] the child's id
+      # @raise [Error] not a child of this session, no such session, or a
+      #   REPL owns it
+      def stop(id)
+        state_dir = self.state_dir
+        sid = resolve(id, state_dir)
+        parent_id = @host.session_id.call
+        unless parent_id && child_of?(sid, parent_id, state_dir)
+          raise Error, "session #{sid[0, 8]} is not a child of this session"
+        end
+
+        SessionManager.stop_session(sid, state_dir: state_dir, wait: STOP_WAIT)
+        sid
+      rescue SessionManager::OwnedByTUI
+        raise Error, "session #{sid[0, 8]} is open in a chi REPL; stop it there"
+      end
+
       private
 
       def state_dir = @host.state_dir&.call || Session.default_state_dir
 
+      # A session file that won't load (corrupt) is an Error, not a crash
+      # of the command that called stop.
+      def child_of?(sid, parent_id, state_dir)
+        Session.load(sid, state_dir: state_dir).parent_id == parent_id
+      rescue ArgumentError => e
+        raise Error, e.message
+      end
+
       def resolve(id, state_dir)
         sid = Session.resolve_id(id.to_s.strip, state_dir: state_dir)
         raise Error, "no session #{id}" unless sid && Session.exist?(sid, state_dir: state_dir)