samagotchi 0.85.0 → 0.86.0

data/lib/samagotchi/bridge/client_event.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "../context_usage"
+
+module Samagotchi
+  class Bridge
+    # What an SSE client gets for an engine event (SSEWriter#write_event, live
+    # and replayed alike). A :generation_chunk carries chi's own counts
+    # (`counts`, ContextUsage.normalize of the provider's payload) instead of
+    # the provider's raw `payload`, and no raw `content` (the chat loop's is
+    # reasoning + content again, the native loop's the raw stream with its
+    # tool-call bytes and thought tags): clients read `text`, `thinking`,
+    # `tool_call` and `counts`, never a provider's payload shape. `?raw=1` on
+    # the worker's stream skips this (debugging).
+    #
+    # Pure: the event is the one hash SessionObserver hands every observer
+    # (the ring, TurnAccumulator, the other writers, SessionMetrics, hooks),
+    # so it is never mutated; keys are added or removed on a copy, and any
+    # key not named here (event_seq included) passes through.
+    module ClientEvent
+      # The counts a client gets: ctx_pct stays out, as normalize computes it
+      # without the session's LLM context budget (the client counts
+      # total_tokens against the window or budget itself).
+      COUNT_KEYS = %i[prompt_tokens completion_tokens total_tokens context_window_tokens].freeze
+
+      module_function
+
+      # @param event [Hash] the engine's event (symbol keys; its payload has
+      #   string keys)
+      # @return [Hash] the event as clients get it: a copy for a
+      #   :generation_chunk, the same object for every other event
+      def project(event)
+        return event unless event.is_a?(Hash) && event[:type].to_s == "generation_chunk"
+
+        projected = event.except(:payload, :content)
+        found = counts(event[:payload])
+        found ? projected.merge(counts: found) : projected
+      end
+
+      # The payload's normalized counts, nil keys left out; nil when the
+      # payload reports none (a missing key means unknown, never 0).
+      # @return [Hash, nil]
+      def counts(payload)
+        usage = ContextUsage.normalize(payload)
+        found = usage&.slice(*COUNT_KEYS)&.compact
+        found.nil? || found.empty? ? nil : found
+      end
+    end
+  end
+end

data/lib/samagotchi/bridge/sse_writer.rb

@@ -2,6 +2,7 @@
 
 require "json"
 
+require_relative "client_event"
 require_relative "event_id"
 
 module Samagotchi
@@ -58,10 +59,12 @@ module Samagotchi
       # @param bridge [Samagotchi::Bridge, nil] for stop signalling
       # @param max_queue [Integer] bounded-queue capacity
       # @param heartbeat_interval [Float] idle-seconds between `: ping` frames
+      # @param raw [Boolean] write events as the engine emitted them, not as
+      #   clients get them (ClientEvent): `?raw=1`, for debugging
       def initialize(engine:, ring:, session_id:, last_event_id: nil, epoch: nil,
                      frame_provider: nil, join_with_snapshot: false, bridge: nil,
                      max_queue: DEFAULT_MAX_QUEUE,
-                     heartbeat_interval: DEFAULT_HEARTBEAT_INTERVAL)
+                     heartbeat_interval: DEFAULT_HEARTBEAT_INTERVAL, raw: false)
         @engine = engine
         @ring = ring
         @session_id = session_id
@@ -72,6 +75,7 @@ module Samagotchi
         @bridge = bridge
         @max_queue = max_queue
         @heartbeat_interval = heartbeat_interval
+        @raw = raw
 
         @queue = BoundedQueue.new(capacity: @max_queue)
         cursor_seq, cursor_epoch = EventId.parse(@last_event_id)
@@ -203,7 +207,7 @@ module Samagotchi
         seq = event[:event_seq]
         return if seq && seq <= @high_water
 
-        write_frame(io, seq: seq, data: event)
+        write_frame(io, seq: seq, data: @raw ? event : ClientEvent.project(event))
         @high_water = seq if seq && seq > @high_water
       end
 

data/lib/samagotchi/bridge.rb

@@ -19,7 +19,6 @@ require_relative "bridge/sse_writer"
 require_relative "bridge/turn_accumulator"
 require_relative "session"
 require_relative "engine"
-require_relative "guardrails/parent_approvals"
 require_relative "session_commands"
 require_relative "queued_command"
 require_relative "steer"
@@ -309,10 +308,11 @@ module Samagotchi
     # @param after_file [String, nil] the input file it came in (its
     #   basename): it runs once that file is taken (Worker#on_command)
     # @return [String] its command_id
-    def queue_command(line, client_id: nil, card: false, after_file: nil)
+    def queue_command(line, client_id: nil, card: false, after_file: nil, enqueued_id: nil)
       # A card's action (the step-limit question's answer): the UIs leave
-      # its line out.
-      command = QueuedCommand.mint(line.to_s.strip, client_id: client_id, card: card)
+      # its line out. +enqueued_id+: a file-delivered command's input, whose
+      # sender's wait its command_ran settles.
+      command = QueuedCommand.mint(line.to_s.strip, client_id: client_id, card: card).with(enqueued_id: enqueued_id)
       @engine.synchronize_events { queue_command_locked(command, after_file: after_file) }
       command.command_id
     end
@@ -420,7 +420,7 @@ module Samagotchi
           cursor = reconnect_cursor(headers, request[:query])
           Log.debug(:bridge, "stream", method: method, path: request[:path], client_id: stream_client_id(request[:query]))
           serve_sse(io, route.last, last_event_id: cursor, snapshot: snapshot_requested?(request[:query]),
-                                    client_id: stream_client_id(request[:query]))
+                                    client_id: stream_client_id(request[:query]), raw: raw_requested?(request[:query]))
           break # SSE owns the connection until the client disconnects.
         else
           payload, status, body = dispatch(route.first, route.last, request[:body], request[:query])
@@ -447,7 +447,7 @@ module Samagotchi
 
     # Serve an SSE stream. Owns the connection until the client disconnects.
     # The connection thread IS the writer thread: serve! blocks until then.
-    def serve_sse(io, session_id, last_event_id:, snapshot: false, client_id: nil)
+    def serve_sse(io, session_id, last_event_id:, snapshot: false, client_id: nil, raw: false)
       unless own_session?(session_id)
         write_json(io, 404, {}, { error: "unknown_session" })
         return
@@ -463,7 +463,8 @@ module Samagotchi
         # A reconnect (with a cursor) replays; only a fresh join snapshots.
         join_with_snapshot: snapshot && last_event_id.nil?,
         bridge: self,
-        heartbeat_interval: @heartbeat_interval
+        heartbeat_interval: @heartbeat_interval,
+        raw: raw
       )
       @mutex.synchronize do
         @open_streams += 1
@@ -649,7 +650,7 @@ module Samagotchi
       selected = fetched(parsed, "selected")
       freeform = fetched(parsed, "freeform")
       # chi answer's marker: a parent agent, held to this worker's
-      # guardrails.parent_approvals (QuestionDesk::Refused). Not a boundary:
+      # Guardrails::ParentPolicy (QuestionDesk::Refused). Not a boundary:
       # any local process may post here, with or without it.
       client_id = fetched(parsed, "client_id")
       if qid.to_s.strip.empty?
@@ -667,9 +668,8 @@ module Samagotchi
         # Another client answered first, or the question was cancelled.
         [{}, 409, { error: "question_not_pending", detail: e.message }]
       rescue QuestionDesk::Refused => e
-        Log.info(:bridge, "parent_approval_refused", sid: session_id, id: qid, reason: e.reason)
-        [{}, 403, { error: e.reason == :stop_only ? "parent_continue_refused" : "parent_approval_refused",
-                    detail: Guardrails::ParentApprovals.message(e.reason) }]
+        Log.info(:bridge, "parent_answer_refused", sid: session_id, id: qid, reason: e.reason)
+        [{}, 403, { error: "parent_answer_refused", reason: e.reason.to_s, detail: e.detail }]
       rescue ArgumentError => e
         [{}, 400, { error: "invalid_answer", detail: e.message }]
       end
@@ -1180,6 +1180,17 @@ module Samagotchi
       false
     end
 
+    # `?raw=1`: events as the engine emitted them (a chunk's provider
+    # payload), not as clients get them (ClientEvent). For debugging on the
+    # worker's port: chi web never passes it on.
+    def raw_requested?(query)
+      return false unless query
+
+      URI.decode_www_form(query).to_h["raw"].to_s == "1"
+    rescue StandardError
+      false
+    end
+
     # `?client_id=`: whose stream it is (see #open_streams_except).
     def stream_client_id(query)
       return nil unless query

data/lib/samagotchi/bridge_client.rb

@@ -114,8 +114,8 @@ module Samagotchi
     # POST /session/:id/answer. 200 = recorded, 409 = another client answered
     # first (or the question is gone), 400 = invalid selection, 408
     # deadline_passed = read too late and dropped (see DEADLINE_SHARE), 403
-    # parent_approval_refused = a parent's allow (client_id cli:answer)
-    # beyond the worker's guardrails.parent_approvals.
+    # parent_answer_refused (with its reason) = a parent's pick (client_id
+    # cli:answer) beyond the worker's guardrails.parent_answers.
     # @param client_id [String, nil] who answers (chi answer marks its own)
     # @return [Response]
     def answer(id:, selected:, freeform: nil, client_id: nil)

data/lib/samagotchi/bundle_command/check.rb

@@ -0,0 +1,348 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require "stringio"
+require "tmpdir"
+require_relative "../memory_bundle"
+require_relative "../memory_bundle/shas"
+require_relative "../memory_bundle/memory_files"
+require_relative "../plugin/api"
+require_relative "../version"
+
+module Samagotchi
+  class BundleCommand
+    # `chi bundle check [PATH] [--fix] [--set KEY=VALUE]`: what keeps the
+    # bundle at PATH from installing and loading cleanly, one finding per
+    # line (docs/cli.md):
+    #
+    #   error|warn|info CODE file[:line]: message (fix: hint)
+    #
+    # It installs and loads the bundle in a Testing::Sandbox (temp HOME and
+    # XDG dirs), not in the user's config or state, but in this process: the
+    # plugin's and hooks' own code runs as written; --fix rewrites stale
+    # sha256 lines (MemoryBundle::Shas). #run returns 0 without errors, 1
+    # with any.
+    class Check
+      Finding = Data.define(:level, :code, :file, :line, :message, :fix) do
+        def error? = level == :error
+
+        def to_s
+          where = line ? "#{file}:#{line}" : file
+          "#{level} #{code} #{where}: #{message}#{" (fix: #{fix})" if fix}"
+        end
+      end
+
+      LIB_DIR = File.expand_path("../..", __dir__)
+      TRUSTED = %w[reviewed trusted].freeze
+      # A call of the plugin API, or a name SINCE lists, in the source.
+      API_CALL = /\b(?:chi|ctx)\.[a-z_]+\b|\bfallback_for:|\bSamagotchi::AtomicFile\b/
+      # A requirement's lower bound: >= X, > X, ~> X or = X.
+      LOWER_BOUND = /\A(?:>=|>|~>|=)?\s*(\d+(?:\.\d+)*)\z/
+
+      # @param dir [String] the bundle's folder
+      # @param fix [Boolean] rewrite stale sha lines
+      # @param settings [Hash] config.yml `bundles: <name>:` for the load
+      def initialize(dir, fix: false, settings: {}, stdout: $stdout)
+        @dir = File.expand_path(dir)
+        @fix = fix
+        @settings = settings
+        @stdout = stdout
+        @findings = []
+      end
+
+      # @return [Integer] exit status
+      def run
+        manifest = read_manifest
+        if manifest
+          missing = check_files(manifest)
+          check_unlisted(manifest)
+          check_shas unless missing
+          check_requires_chi(manifest)
+          check_trust(manifest)
+          check_clash(manifest)
+          check_install(manifest) unless missing || placeholders?
+          check_boundary(manifest)
+          check_tests
+        end
+        errors = @findings.count(&:error?)
+        warnings = @findings.count { |f| f.level == :warn }
+        @stdout.puts "#{errors.zero? ? "ok" : "failed"}: #{errors} error#{"s" unless errors == 1}, " \
+                     "#{warnings} warning#{"s" unless warnings == 1} (#{display(@dir)})"
+        errors.zero? ? CLI::Exit::OK : CLI::Exit::FAILED
+      end
+
+      private
+
+      def add(level, code, file, message, line: nil, fix: nil)
+        finding = Finding.new(level: level, code: code, file: file, line: line, message: message, fix: fix)
+        @findings << finding
+        @stdout.puts finding
+      end
+
+      def path(rel) = File.join(@dir, rel)
+
+      def display(dir) = dir.start_with?("#{Dir.pwd}/") ? dir.delete_prefix("#{Dir.pwd}/") : dir
+
+      # Through symlinks on both sides: a linked path to chi's own bundle is it.
+      def shipped? = File.dirname(File.realpath(@dir)) == File.realpath(MemoryBundle::SourceNormalizer::SHIPPED_DIR)
+
+      # ── manifest ──────────────────────────────────────────────────────
+
+      # The manifest, parsed with its placeholder shas taken (a stale sha is
+      # check_shas' finding, not a parse error); nil after a `manifest` error.
+      def read_manifest
+        unless File.file?(path("manifest.yml"))
+          add(:error, :manifest, "manifest.yml", "no manifest.yml in #{display(@dir)}", fix: "chi bundle new NAME")
+          return nil
+        end
+
+        @text = File.read(path("manifest.yml"))
+        Dir.mktmpdir("chi-bundle-check-") do |tmp|
+          File.write(File.join(tmp, "manifest.yml"), MemoryBundle::Shas.parseable(@text))
+          MemoryBundle::Manifest.read(dir: tmp)
+        rescue MemoryBundle::Manifest::ValidationError => e
+          add(:error, :manifest, "manifest.yml", e.message.gsub(tmp, display(@dir)))
+          nil
+        end
+      end
+
+      # The line of manifest.yml naming +file+ (its entry), or nil.
+      def manifest_line(file)
+        base = File.basename(file)
+        index = @text.lines.index { |l| l.match?(/\A\s*(?:file: )?["']?#{Regexp.escape(base)}["']?:?(?:\s|\z)/) }
+        index && (index + 1)
+      end
+
+      # ── files ─────────────────────────────────────────────────────────
+
+      # @return [Boolean] whether a listed file is missing
+      def check_files(manifest)
+        listed = manifest.files.keys + Array(manifest.plugin && manifest.plugin[:file]) +
+                 manifest.hooks.keys.map { |h| File.join("hooks", h) } + manifest.scripts.keys.map { |s| File.join("scripts", s) }
+        missing = listed.reject { |rel| File.file?(path(rel)) }
+        missing.each do |rel|
+          add(:error, :"missing-file", "manifest.yml", "lists #{rel}, which isn't in the bundle", line: manifest_line(rel),
+                                                                                                fix: "add the file or drop the entry")
+        end
+        !missing.empty?
+      end
+
+      # What an install leaves out: a memory files: doesn't list (by
+      # MemoryFiles' rules), a plugin, hook or script the manifest doesn't name.
+      def check_unlisted(manifest)
+        memories = MemoryBundle::MemoryFiles.select(@dir, manifest)
+        loose = Dir.glob(path("*.md")).map { |f| File.basename(f) }.sort.reject do |name|
+          memories.include?(name) || MemoryBundle::MemoryFiles.repo_meta?(name)
+        end
+        loose.each { |name| unlisted(name, "files:") }
+        plugin = manifest.plugin && manifest.plugin[:file]
+        unlisted("plugin.rb", "plugin:") if File.file?(path("plugin.rb")) && plugin != "plugin.rb"
+        Dir.glob(path("hooks/*.rb")).sort.each do |file|
+          unlisted("hooks/#{File.basename(file)}", "hooks:") unless manifest.hooks.key?(File.basename(file))
+        end
+        Dir.glob(path("scripts/*")).sort.each do |file|
+          unlisted("scripts/#{File.basename(file)}", "scripts:") unless manifest.scripts.key?(File.basename(file))
+        end
+      end
+
+      def unlisted(rel, key)
+        add(:warn, :unlisted, rel, "manifest.yml's #{key} doesn't list it, so an install leaves it out",
+            fix: "list it under #{key}, then chi bundle check --fix")
+      end
+
+      # ── sha256 lines ──────────────────────────────────────────────────
+
+      def check_shas
+        if @fix
+          text, changes = MemoryBundle::Shas.refresh(@dir, @text)
+          unless changes.empty?
+            File.write(path("manifest.yml"), text)
+            @text = text
+            changes.each { |file, _old, new| @stdout.puts "fixed sha #{file} → sha256:#{new[0, 12]}…" }
+          end
+        end
+        MemoryBundle::Shas.stale(@dir, @text).each do |stale|
+          line = manifest_line(stale.file)
+          if stale.old.nil?
+            add(:error, :sha, "manifest.yml", "#{stale.file} has no sha256 line, so it installs unchecked", line: line,
+                                                                                                          fix: "add `sha256: sha256:` under its entry, then chi bundle check --fix")
+          else
+            what = stale.old.empty? ? "a placeholder sha256" : "a stale sha256"
+            add(:error, :sha, "manifest.yml", "#{what} for #{stale.file}", line: line, fix: "chi bundle check --fix")
+          end
+        end
+      rescue MemoryBundle::Shas::Error => e
+        add(:error, :sha, "manifest.yml", e.message.sub(%r{\A[^/]+/manifest\.yml:? ?}, ""))
+      end
+
+      # ── requires_chi ──────────────────────────────────────────────────
+
+      def code?(manifest) = manifest.plugin || manifest.hooks.any? || manifest.scripts.any?
+
+      def check_requires_chi(manifest)
+        line = manifest_line("requires_chi")
+        if (failure = MemoryBundle::Manifest.requires_chi_failure(manifest.requires_chi, VERSION))
+          @too_new = true
+          add(:error, :"requires-chi", "manifest.yml", "this chi can't load it: #{failure}", line: line,
+                                                                                            fix: "chi update, or lower requires_chi")
+        elsif manifest.requires_chi.nil? && code?(manifest)
+          add(:warn, :"requires-chi", "manifest.yml", "no requires_chi for a bundle with code", fix: "add requires_chi: \">= #{VERSION}\"")
+        end
+        check_floor(manifest, line) if manifest.plugin && manifest.requires_chi && !@too_new
+      end
+
+      # The plugin calls an API newer than the oldest chi requires_chi admits.
+      def check_floor(manifest, line)
+        floor = lower_bound(manifest.requires_chi)
+        return unless floor && File.file?(path(manifest.plugin[:file]))
+
+        calls = File.read(path(manifest.plugin[:file])).scan(API_CALL).uniq.select { |call| Plugin::Api::SINCE.key?(call) }
+        call = calls.max_by { |c| Gem::Version.new(Plugin::Api::SINCE[c]) } or return
+        version = Plugin::Api::SINCE[call]
+        return unless Gem::Version.new(version) > floor
+
+        add(:warn, :"requires-chi-floor", "manifest.yml",
+            "requires_chi #{manifest.requires_chi.inspect} admits chi #{floor}, but #{manifest.plugin[:file]} uses " \
+            "#{call}, which needs chi #{version}", line: line,
+                                                                                      fix: "requires_chi: \">= #{version}\"")
+      end
+
+      def lower_bound(requirement)
+        requirement.to_s.split(",").filter_map do |part|
+          version = part.strip[LOWER_BOUND, 1]
+          Gem::Version.new(version) if version
+        end.max
+      end
+
+      def check_trust(manifest)
+        return if shipped? || !TRUSTED.include?(manifest.trust_level)
+
+        add(:warn, :trust, "manifest.yml", "trust_level: #{manifest.trust_level} is set by the bundle's author",
+            line: manifest_line("trust_level"), fix: "leave it out unless someone reviewed the bundle")
+      end
+
+      # ── install and load ──────────────────────────────────────────────
+
+      # Before the sandbox: the user's installed bundles and chi's shipped ones.
+      def check_clash(manifest)
+        name = manifest.name
+        shipped = MemoryBundle::Listing.shipped.map(&:name) + [MemoryBundle::SystemBundle::BUNDLE_NAME]
+        if shipped.include?(name) && !shipped?
+          add(:warn, :clash, "manifest.yml", "chi ships a bundle named #{name}; installing this one replaces chi's",
+              line: manifest_line("name"), fix: "rename the bundle")
+        end
+        # A shipped bundle installed from any chi's copy is that bundle.
+        return if shipped?
+
+        record = MemoryBundle::Provenance.new(name: name).record
+        return unless record && File.expand_path(record.source.to_s) != @dir
+
+        add(:warn, :clash, "manifest.yml", "a bundle named #{name} is installed from #{record.source}",
+            line: manifest_line("name"), fix: "rename the bundle, or chi bundle upgrade #{display(@dir)} to replace it")
+      rescue StandardError
+        nil
+      end
+
+      # An unfilled `sha256: sha256:` isn't YAML: the Installer can't read
+      # the manifest until --fix fills it.
+      def placeholders?
+        return false unless @findings.any? { |f| f.code == :sha && f.message.start_with?("a placeholder") }
+
+        add(:info, :install, "manifest.yml", "skipped until the placeholder shas are filled", fix: "chi bundle check --fix")
+        true
+      end
+
+      def check_install(manifest)
+        require_relative "../testing"
+        result = nil
+        # The log's echoes (the "experimental" line every external bundle
+        # gets) are left out: what failed is in the result.
+        quietly do
+          Testing::Sandbox.with do |sandbox|
+            result = Testing::Install.run(@dir, settings: @settings, sandbox: sandbox, force: true)
+          end
+        end
+        install_warnings(result.warnings)
+        # The loaders refuse a bundle requires_chi rules out: that's the requires-chi error.
+        result.failures.each { |failure| install_failure(failure) unless @too_new && failure.reason.include?("it requires chi") }
+        report_registered(manifest, result.registered)
+      rescue MemoryBundle::Installer::InstallError, MemoryBundle::Manifest::ValidationError => e
+        add(:error, :install, "manifest.yml", e.message)
+      rescue StandardError => e
+        # Whatever else the install or the load raised: one finding, not a trace.
+        add(:error, :install, "manifest.yml", "the sandboxed install failed: #{e.class}: #{e.message}")
+      end
+
+      def quietly
+        saved = $stderr
+        $stderr = StringIO.new
+        yield
+      ensure
+        $stderr = saved
+      end
+
+      def install_warnings(warnings)
+        stale_reported = @findings.any? { |f| f.code == :sha }
+        warnings.each do |warning|
+          next if stale_reported && warning.start_with?("Checksum mismatch")
+          next if @too_new && warning.include?("won't load:")
+
+          if warning.start_with?("needs ")
+            add(:warn, :install, "manifest.yml", warning)
+          else
+            add(:error, :install, "manifest.yml", warning)
+          end
+        end
+      end
+
+      def install_failure(failure)
+        file, line = failure.location&.match(/\A(.+):(\d+)\z/)&.captures
+        file = file ? file.delete_prefix("#{@dir}/") : "manifest.yml"
+        add(:error, :install, file, "#{failure.what} failed to load: #{failure.reason}", line: line&.to_i)
+      end
+
+      def report_registered(manifest, registered)
+        plugin = manifest.plugin ? manifest.plugin[:file] : "manifest.yml"
+        registered[:commands].each { |name, _, _| add(:info, :registered, plugin, "command #{name}") }
+        registered[:tools].each { |name| add(:info, :registered, plugin, "tool #{name}") }
+        registered[:hooks].each do |event, hooks|
+          hooks.each do |_bundle, hook, priority|
+            file = manifest.hooks.key?(hook) ? "hooks/#{hook}" : plugin
+            next add(:info, :registered, file, "hook #{event} (priority #{priority})") if Hooks::EVENTS.include?(event)
+
+            add(:warn, :"hook-event", file, "hook on #{event.inspect}, which chi never fires",
+                fix: "one of #{Hooks::EVENTS.join(", ")}")
+          end
+        end
+        { inits: "init", toolkits: "toolkit", tool_sources: "tool source", peer_sources: "peer source" }.each do |key, what|
+          registered[key].each { |name| add(:info, :registered, plugin, "#{what} #{name}") }
+        end
+      end
+
+      # ── what it reaches of chi ────────────────────────────────────────
+
+      def check_boundary(manifest)
+        require_relative "../testing/boundary"
+        known = shipped? ? Testing::Boundary::EXCEPTIONS.fetch(manifest.name, {}) : {}
+        Testing::Boundary.scan(@dir).reject { |f| known.key?(f.reference) }.each do |finding|
+          add(:warn, :boundary, finding.file, "#{finding.reference} is internal to chi and may break on a chi upgrade",
+              fix: "use chi.* / ctx, or the names docs/plugins.md lists as stable")
+        end
+      end
+
+      # ── tests ─────────────────────────────────────────────────────────
+
+      def check_tests
+        tests = Dir.glob(path("test/**/*_test.rb")).sort.map { |f| f.delete_prefix("#{@dir}/") }
+        if tests.any?
+          add(:info, :tests, "test/", "#{tests.size} file#{"s" unless tests.size == 1}: run chi bundle test " \
+                                      "(Minitest on #{RbConfig.ruby}, -I #{LIB_DIR})")
+        elsif File.directory?(path("spec"))
+          add(:info, :tests, "spec/", "chi bundle test (runs rspec with the kit)")
+        else
+          add(:info, :tests, display(@dir), "no tests", fix: "chi bundle new NAME writes one to copy")
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/bundle_command/scaffold.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../memory_bundle/shas"
+require_relative "../version"
+
+module Samagotchi
+  class BundleCommand
+    # `chi bundle new NAME [--dir DIR]`: a bundle to start from, in DIR/NAME:
+    # a manifest (block-form plugin: entry, its sha filled, requires_chi at
+    # this chi), a plugin with one command and one after_tool_call hook, a
+    # Minitest test on the kit that passes as written, and a README. The
+    # test is the pattern to copy (docs/bundle-authoring.md).
+    class Scaffold
+      # A name that is also a slash command (Plugin::Api::COMMAND_NAME).
+      NAME = /\A[a-z][a-z0-9_-]{0,31}\z/
+
+      # @return [String] the bundle's folder
+      attr_reader :dir
+
+      def initialize(name, parent: ".")
+        @name = name
+        @dir = File.expand_path(name, parent)
+      end
+
+      # Write the files; ArgumentError for a bad name or a folder that's there.
+      # @return [Array<String>] the files written, relative to #dir
+      def write
+        raise ArgumentError, "#{@name.inspect} isn't a bundle name: a-z first, then a-z, 0-9, - or _ (32 at most)" unless @name.match?(NAME)
+        raise ArgumentError, "#{@dir} exists already" if File.exist?(@dir)
+
+        files.each do |rel, text|
+          FileUtils.mkdir_p(File.dirname(File.join(@dir, rel)))
+          File.write(File.join(@dir, rel), text)
+        end
+        File.write(File.join(@dir, "manifest.yml"), MemoryBundle::Shas.refresh(@dir).first)
+        files.keys
+      end
+
+      private
+
+      def test_file = "test/#{@name.tr("-", "_")}_test.rb"
+      def test_class = "#{@name.split(/[-_]/).map(&:capitalize).join}Test"
+
+      def files
+        { "manifest.yml" => manifest, "plugin.rb" => plugin, test_file => test, "README.md" => readme }
+      end
+
+      def manifest
+        <<~YAML
+          name: #{@name}
+          version: 0.1.0
+          scope: system
+          description: "What #{@name} adds to chi, in one line"
+          requires_chi: ">= #{VERSION}"
+          plugin:
+            file: plugin.rb
+            sha256: sha256:
+        YAML
+      end
+
+      def plugin
+        <<~RUBY
+          # frozen_string_literal: true
+
+          # #{@name}: one slash command and one hook (docs/bundle-authoring.md in chi's source dir).
+          class Plugin
+            # settings: config.yml `bundles: #{@name}:` (string keys), read once when the plugin loads.
+            def initialize(settings)
+              @greeting = settings.fetch("greeting", "hello")
+            end
+
+            def register(chi)
+              # /#{@name} [WHO]: the block gets the text after the name and returns what to show.
+              chi.command("/#{@name}", "say hello") do |args, _ctx|
+                "\#{@greeting}, \#{args.empty? ? "there" : args}"
+              end
+
+              # After each tool call: an execute that exited non-zero gets one notice. Match on event[:result]
+              # (the tool's own text, ending in "exit: N"), not event[:output] (what the model reads, maybe cut).
+              chi.on(:after_tool_call) do |event, ctx|
+                next unless event[:tool] == "execute"
+
+                code = event[:result].to_s[/^exit: (\\d+)/, 1].to_i
+                ctx.notify("the command exited \#{code}", level: :warn) unless code.zero?
+              end
+            end
+          end
+        RUBY
+      end
+
+      def test
+        <<~RUBY
+          # frozen_string_literal: true
+
+          require "minitest/autorun"
+          require "samagotchi/testing/minitest"
+
+          # `chi bundle test` runs this with chi's own Ruby and lib. Each test gets a sandbox (temp HOME, config,
+          # state); load_bundle loads the bundle's source through chi's loaders, and the recorders show what it did.
+          class #{test_class} < Samagotchi::Testing::Case
+            BUNDLE = File.expand_path("..", __dir__)
+
+            def test_the_command_greets
+              assert_equal "hello, chi", load_bundle(BUNDLE).command("/#{@name} chi")
+              assert_equal "hi, there", load_bundle(BUNDLE, settings: { "greeting" => "hi" }).command("/#{@name}")
+            end
+
+            def test_a_failed_execute_gets_a_notice
+              bundle = load_bundle(BUNDLE)
+              # An execute's after_tool_call as chi fires it (docs/hooks.md, Hook Events).
+              bundle.fire(:after_tool_call, tool: "execute", status: "error", iteration: 1, elapsed_ms: 12,
+                                            call: { name: "execute", content: "false" },
+                                            result: "exit: 1 (no output)", output: "[execute]\\nexit: 1 (no output)")
+              bundle.fire(:after_tool_call, tool: "execute", status: "ok", iteration: 2, elapsed_ms: 9,
+                                            call: { name: "execute", content: "echo hi" },
+                                            result: "stdout:\\nhi\\n\\nexit: 0", output: "[execute]\\nstdout:\\nhi\\n\\nexit: 0")
+
+              assert_equal [["the command exited 1", :warn]], bundle.notices.map { |n| [n.text, n.level] }
+            end
+          end
+        RUBY
+      end
+
+      def readme
+        <<~MD
+          # #{@name}
+
+          A chi bundle: `/#{@name}`, and a notice when a command fails.
+          Check it with `chi bundle check`, test it with `chi bundle test`, install it with `chi bundle install .`
+        MD
+      end
+    end
+  end
+end