samagotchi 0.9.0 → 0.10.0

data/lib/samagotchi/note_command.rb

@@ -3,6 +3,8 @@
 require_relative "session"
 require_relative "session_inbox"
 require_relative "session_manager"
+require_relative "cli/command"
+require_relative "cli/flags"
 
 module Samagotchi
   # `chi note`: push text into sessions as a context note (background the
@@ -10,6 +12,8 @@ module Samagotchi
   # script, e.g. an Automator action:
   #   pbpaste | chi note --source slack $(chi sessions list --live --scope=all --format tsv | cut -f1)
   class NoteCommand
+    include CLI::Command
+
     USAGE = <<~TEXT
       Usage: chi note [--source NAME] [-m TEXT] (ID|PREFIX)... | --all
         Adds TEXT (or stdin) to each session as a context note: background
@@ -20,6 +24,12 @@ module Samagotchi
         Find ids with: chi sessions list --live [--scope=all] [--format tsv]
     TEXT
 
+    FLAGS = CLI::Flags.new(help: CLI::Command::HELP_WORDS) do |f|
+      f.switch "--all"
+      f.value "--source"
+      f.value "-m", "--message", key: :text
+    end
+
     # @param argv [Array<String>] the arguments after "note"
     def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, state_dir: nil)
       @argv = argv.dup
@@ -32,14 +42,12 @@ module Samagotchi
     # @return [Integer] exit status: 0 all queued, 1 any refused or failed,
     #   2 usage
     def run
-      options = parse or return 2
-      return 0 if options[:help]
+      options = parse
+      return options if options.is_a?(Integer)
 
       text = utf8(options[:text] || read_stdin)
-      unless text
-        usage_error("no note text: pass -m TEXT or pipe it in")
-        return 2
-      end
+      return usage_error("no note text: pass -m TEXT or pipe it in") unless text
+
       begin
         text = SessionInbox.checked_text(text)
       rescue SessionInbox::NoteRejected => e
@@ -64,24 +72,15 @@ module Samagotchi
 
     private
 
+    def command_name = "chi note"
+
+    # @return [Hash, Integer] the options, or the exit status after the
+    #   help or a usage error
     def parse
-      options = { source: "cli", ids: [] }
-      until @argv.empty?
-        arg = @argv.shift
-        case arg
-        when "-h", "--help", "help"
-          @stdout.puts(USAGE)
-          return { help: true }
-        when "--all" then options[:all] = true
-        when "--source", "-m", "--message"
-          value = @argv.shift or return usage_error("#{arg} needs a value")
-          options[arg == "--source" ? :source : :text] = value
-        when /\A--source=(.*)\z/m then options[:source] = Regexp.last_match(1)
-        when /\A--message=(.*)\z/m then options[:text] = Regexp.last_match(1)
-        when /\A-/ then return usage_error("unknown option #{arg}")
-        else options[:ids] << arg
-        end
-      end
+      parsed = parse_flags(FLAGS, @argv, source: "cli")
+      return parsed if parsed.is_a?(Integer)
+
+      options = parsed.options.merge(ids: parsed.args)
       return usage_error("give session ids or --all") if options[:ids].empty? && !options[:all]
       return usage_error("--all takes no ids") if options[:all] && options[:ids].any?
 
@@ -127,7 +126,7 @@ module Samagotchi
     def deliver(id, text, source)
       short = id[0, 8]
       owner = SessionManager.session_owner(id, state_dir: @state_dir)
-      if owner && owner["kind"] == "tui"
+      if owner&.tui?
         @stdout.puts("#{short}  refused: it is open in a chi REPL; notes need attached mode")
         return false
       end
@@ -148,18 +147,5 @@ module Samagotchi
     def utf8(text)
       text&.dup&.force_encoding(Encoding::UTF_8)&.scrub
     end
-
-    # stderr isn't buffered, stdout is when it's a pipe: flush the lines
-    # already printed, so the output keeps the order of the ids given.
-    def error_line(text)
-      @stdout.flush
-      @stderr.puts(text)
-    end
-
-    def usage_error(message)
-      error_line("chi note: #{message}")
-      @stderr.puts(USAGE)
-      nil
-    end
   end
 end

data/lib/samagotchi/owner_lock.rb

@@ -20,6 +20,18 @@ module Samagotchi
     RETRY_INTERVAL = 0.05
     OWNER_READ_ATTEMPTS = 10
 
+    # Who holds the lock, as .owner reads it from the lock file. Its fields
+    # may be nil for a moment right after acquisition.
+    # kind: "worker" or "tui"; pid as written (an Integer).
+    Owner = Data.define(:pid, :kind, :started_at) do
+      def initialize(pid: nil, kind: nil, started_at: nil) = super
+
+      # The interactive TUI's: it reads no input files and takes no notes.
+      def tui? = kind == "tui"
+
+      def worker? = kind == "worker"
+    end
+
     # Take the lock, retrying for up to +wait+ seconds (another process's
     # #owner probe holds it for a moment). On success the owner's pid and kind
     # are written into the lock file for #owner to report.
@@ -42,8 +54,7 @@ module Samagotchi
 
     # The current owner, read without disturbing it.
     # @param session_dir [String]
-    # @return [Hash, nil] {"pid", "kind", "started_at"} while held (values may
-    #   be missing for a moment right after acquisition), nil when free
+    # @return [Owner, nil] while held, nil when free
     def self.owner(session_dir)
       File.open(path(session_dir), File::RDONLY) do |file|
         if file.flock(File::LOCK_SH | File::LOCK_NB)
@@ -59,7 +70,7 @@ module Samagotchi
 
           sleep(RETRY_INTERVAL / 5)
         end
-        data
+        Owner.new(pid: data["pid"], kind: data["kind"], started_at: data["started_at"])
       end
     rescue Errno::ENOENT
       nil

data/lib/samagotchi/plugin/api.rb

@@ -135,9 +135,10 @@ module Samagotchi
 
       # Run the block on a hook event (docs/hooks.md: :before_turn,
       # :after_turn, :before_tool_call, …), like a bundle's hooks/*.rb:
-      # the block gets the event hash, with event[:notify] and the other
-      # helpers, and the Context (a block may take the event alone). A
-      # block that raises is logged (not shown) and skipped.
+      # the block gets the event hash and the Context (a block may take the
+      # event alone); while it runs, ctx.notify and the other helpers act
+      # as this event's (Context#with_event). A block that raises is
+      # logged (not shown) and skipped.
       # @param priority [Integer] lower runs first among bundle hooks
       def on(event, priority: 100, &block)
         raise ArgumentError, "on(#{event.inspect}) needs a block" unless block
@@ -219,22 +220,15 @@ module Samagotchi
         end
         @tools.each { |tool| @registries.tools.register(tool[:name], source: @bundle, **Api.entry_fields(tool, context)) }
         @hooks.each do |hook|
-          bundle = @bundle
-          label = @label
           block = hook[:block]
-          context = @context
-          # A stream hook fires ~once a second: a broken one logs once a minute.
-          log_failure = Hooks.failure_log_gate(hook[:event])
-          @registries.hooks.register_bundle(bundle, hook[:event], hook_name: label.split(" ").first,
-                                                                  priority: hook[:priority]) do |event|
-            block.call(event, context)
-          rescue StandardError => e
-            next unless log_failure.call
-
-            # Logged only: a turn's live region is on screen.
-            Log.warn(:plugins, "plugin_hook_failed", bundle: bundle, event: hook[:event].to_s, error: e.class.name,
-                                                     msg: "#{label} #{hook[:event]} hook failed: #{e.message}")
+          # Logged only (echo: false): a turn's live region is on screen.
+          handler = Hooks.wrap(label: "#{@label} #{hook[:event]} hook", event: hook[:event], policy: :log,
+                               log: [:plugins, "plugin_hook_failed"], echo: false, fields: { bundle: @bundle }) do |event|
+            # ctx's helpers act as this event's while the block runs.
+            context ? context.with_event(event) { block.call(event, context) } : block.call(event, context)
           end
+          @registries.hooks.register_bundle(@bundle, hook[:event], hook_name: @label.split(" ").first,
+                                                                   priority: hook[:priority], &handler)
         end
         @inits.each do |init|
           block = init[:block]

data/lib/samagotchi/plugin/context.rb

@@ -19,7 +19,7 @@ module Samagotchi
     # the answer text.
     # +messages_partial+ says whether +messages+ leaves out a running turn;
     # +model_name+ and +state_dir+ are what ctx.sessions forks with.
-    # +steer+ takes (text, source), +stop_turn+ and +stop_generation+
+    # +steer+ takes (text, label), +stop_turn+ and +stop_generation+
     # (reason, label), each true when it acted on a running turn.
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
                       :ask_model, :model_name, :state_dir, :scratch, :steer, :stop_turn, :stop_generation, keyword_init: true)
@@ -35,7 +35,17 @@ module Samagotchi
     # they run for, the bundle's settings and storage, a log, and the
     # user-facing helpers hooks have. One per plugin, for the Engine's life:
     # each read is of the session now.
+    #
+    # The helpers (notify, ask_user, steer, stop_turn, stop_generation)
+    # are a plugin's one surface for them. Inside one of the plugin's event
+    # handlers (#with_event, on the handler's thread) they are that fire's
+    # event[:x]: stop_turn in before_tool_call also denies the pending
+    # call, and steer, stop_turn and stop_generation do nothing once the
+    # turn is over. Anywhere else (a command, an init task, a thread the
+    # handler started) they act on the session now, through the Host.
     class Context
+      # Thread.current key: {Context => the event its handler runs for}.
+      CURRENT_EVENTS = :samagotchi_plugin_current_events
       # Debug-log records tagged plugins, with bundle=<bundle> (tags are a
       # closed list, LogLine::TAGS).
       class Logger
@@ -104,11 +114,34 @@ module Samagotchi
       # a plugin can say what its answer is about.
       def messages_partial? = !!@host.messages_partial&.call
 
-      # One line to the user, labelled by the plugin, like a hook's
-      # event[:notify]. Every UI shows it, during a turn or between turns.
+      # Run +block+ as this plugin's handler for +event+: until it returns,
+      # the helpers called on this thread act as the event's own. Nests (a
+      # fire inside a handler gets its own event; the outer one is back
+      # after it); threads the block starts don't inherit it.
+      # @param event [Hash] the fire's event
+      def with_event(event)
+        events = (Thread.current[CURRENT_EVENTS] ||= {}.compare_by_identity)
+        had = events.key?(self)
+        previous = events[self]
+        events[self] = event
+        yield
+      ensure
+        if had
+          events[self] = previous
+        else
+          events&.delete(self)
+        end
+      end
+
+      # One line to the user, labelled by the plugin (in every UI by its
+      # bundle's name). Every UI shows it, during a turn or between turns.
       # @param level [Symbol] :info or :warn
       def notify(text, level: :info)
-        @host.notify.call(text.to_s, level, @label)
+        if (helper = event_helper(:notify))
+          helper.call(text.to_s, level: level)
+        else
+          @host.notify.call(text.to_s, level, @label)
+        end
         nil
       end
 
@@ -167,11 +200,15 @@ module Samagotchi
         @sessions ||= Sessions.new(@host)
       end
 
-      # A single-select question through the question flow, like a hook's
-      # event[:ask_user].
+      # A single-select question through the question flow. Inside a
+      # stream hook's handler (generation_progress) it asks no one (nil).
       # @return [Hash, nil] {selected:, freeform:, selected_indices:}, or nil
       #   (no one to ask, cancelled, bad options)
       def ask_user(question:, options:, header: nil, allow_freeform: false)
+        if (helper = event_helper(:ask_user))
+          return helper.call(question: question, options: options, header: header, allow_freeform: allow_freeform)
+        end
+
         @host.ask_user.call(question: question, options: options, header: header, allow_freeform: allow_freeform,
                             hook: @label)
       end
@@ -184,31 +221,49 @@ module Samagotchi
       # conversation as its own user message, shown in every UI as a nudge
       # from this bundle. It never starts a turn. True means queued: if the
       # model answers first, or the turn ends, it is dropped (logged).
-      # Callable from a hook, a command (an anytime one runs beside the
-      # turn) or your own thread.
+      # Callable from a handler (false from after_turn / session_end), a
+      # command (an anytime one runs beside the turn) or your own thread.
       # @return [Boolean] whether a turn was running and the text queued
       def steer(text)
-        !!@host.steer&.call(text.to_s, @bundle)
+        helper = event_helper(:steer)
+        return !!helper.call(text.to_s) if helper
+
+        !!@host.steer&.call(text.to_s, @label)
       end
 
-      # Stop the running turn, after a notice with +reason+, as a hook's
-      # event[:stop_turn] does (for commands and threads).
+      # Stop the running turn, after a notice with +reason+. From a
+      # before_tool_call handler it also denies the pending call; from
+      # after_turn / session_end it does nothing (false).
       # @return [Boolean] whether a running turn was stopped now
       def stop_turn(reason)
+        helper = event_helper(:stop_turn)
+        return !!helper.call(reason.to_s) if helper
+
         !!@host.stop_turn&.call(reason.to_s, @label)
       end
 
-      # Cut the generation that is streaming, as a hook's
-      # event[:stop_generation] does: the turn goes on and the model is
-      # asked again (retry.empty_answer), or with no retry left the turn
-      # ends as cancelled (hook). Shows nothing: post your own notice.
+      # Cut the generation that is streaming: the turn goes on and the
+      # model is asked again (retry.empty_answer), or with no retry left
+      # the turn ends as cancelled (hook). Shows nothing: post your own
+      # notice. From after_turn / session_end it does nothing (false).
       # @return [Boolean] whether a streaming generation was cut now
       def stop_generation(reason)
+        helper = event_helper(:stop_generation)
+        return !!helper.call(reason.to_s) if helper
+
         !!@host.stop_generation&.call(reason.to_s, @label)
       end
 
       private
 
+      # The event[:x] helper of the event this plugin's handler runs for on
+      # this thread, or nil (not in a handler).
+      def event_helper(name)
+        event = Thread.current[CURRENT_EVENTS]&.[](self)
+        helper = event[name] if event.is_a?(Hash)
+        helper.respond_to?(:call) ? helper : nil
+      end
+
       def deep_freeze(value)
         case value
         when Hash then value.to_h { |k, v| [deep_freeze(k), deep_freeze(v)] }.freeze

data/lib/samagotchi/plugin/loader.rb

@@ -98,10 +98,9 @@ module Samagotchi
       def instantiate(bundle_name, file, settings)
         namespace = fresh_namespace(bundle_name)
         namespace.module_eval(File.read(file), file, 1)
-        class_name = File.basename(file, ".rb").split("_").map(&:capitalize).join
-        klass = namespace.const_get(class_name, false)
+        klass = Hooks.class_for(file, namespace)
         plugin = Hooks.build_plugin(klass, settings)
-        raise ArgumentError, "#{class_name} does not respond to #register" unless plugin.respond_to?(:register)
+        raise ArgumentError, "#{klass.name.split("::").last} does not respond to #register" unless plugin.respond_to?(:register)
 
         plugin
       end

data/lib/samagotchi/sampling_settings.rb

@@ -12,17 +12,16 @@ module Samagotchi
     EMPTY = {}.freeze
 
     # @param target [HostRegistry::ModelTarget]
-    # @param names [Array<String>, nil] the model as typed, alias-resolved,
-    #   bare (the Engine's lookup names); default: the target's model and bare model
+    # @param names [Array<String>] the model's lookup names (HostRegistry#lookup_names)
     # @param models [Hash, nil] ConfigFile.model_settings (specs)
     # @return [Hash] frozen, symbol keys; may be empty
-    def self.for(target, names: nil, models: nil)
+    def self.for(target, names:, models: nil)
       resolve(target, names, models).first
     end
 
     # "temperature=0.6 presence_penalty=1.5 (hosts.work, models: qwen)" for
     # /model, or nil when nothing is configured.
-    def self.summary(target, names: nil, models: nil)
+    def self.summary(target, names:, models: nil)
       params, sources = resolve(target, names, models)
       return nil if params.empty?
 
@@ -44,7 +43,6 @@ module Samagotchi
       rescue StandardError
         {}
       end
-      names ||= [target.model, target.bare_model]
       host = target.entry.sampling || EMPTY
       key, model = ConfigFile.model_setting(names, :sampling, models: models)
       sources = []

data/lib/samagotchi/self_report.rb

@@ -97,11 +97,7 @@ module Samagotchi
       File.exist?(path) ? path : "#{path} (missing)"
     end
 
-    def hooks_dir(env)
-      data = ConfigFile.read_yaml(path: ConfigFile.global_path(env: env))
-      configured = data.is_a?(Hash) && data["hooks"].is_a?(Hash) ? data["hooks"]["hooks_dir"] : nil
-      Hooks::Loader.expand_path(configured || Hooks::Loader.default_hooks_dir(env), env)
-    end
+    def hooks_dir(env) = Hooks::Loader.hooks_dir(env)
 
     # Offline, so only the fallback: the running server's n_ctx wins at runtime.
     def context_window(env)
@@ -153,8 +149,7 @@ module Samagotchi
       entry, bare = registry.host_for_model(model)
       return "name-based (chat API: only strips thoughts)" if entry&.chat?
 
-      # As typed, the part after a host prefix (maybe an alias), alias-resolved, bare.
-      names = [model, registry.parse_qualified_model(model).last, ConfigFile.resolve_model_alias(model, env: env), bare]
+      names = registry.lookup_names(model)
       override = Config.resolve_with_origin("model.profile", env: env, cli_overrides: Config.cli_overrides)
       result = ModelProfile.resolve(names: names, entry: entry, client: nil, bare_model: bare, override: override,
                                     models: ConfigFile.model_settings(env: env))
@@ -172,8 +167,10 @@ module Samagotchi
 
     # The model's thinking level and where it came from (Thinking.resolve).
     def thinking_for(model, env)
-      target = HostRegistry.new(env: env).resolve(model)
-      level, source = Thinking.resolve(target, models: ConfigFile.model_settings(env: env))
+      registry = HostRegistry.new(env: env)
+      target = registry.resolve(model)
+      level, source = Thinking.resolve(target, names: registry.lookup_names(model, target: target),
+                                               models: ConfigFile.model_settings(env: env))
       source ? "#{level} (#{source})" : level.to_s
     rescue StandardError => e
       "(unknown: #{e.message})"

data/lib/samagotchi/send_command.rb

@@ -9,6 +9,8 @@ require_relative "image_store"
 require_relative "host_registry"
 require_relative "model_profile"
 require_relative "vision_support"
+require_relative "cli/command"
+require_relative "cli/flags"
 
 module Samagotchi
   # `chi send`: put text into sessions as the user's message, the same as
@@ -19,13 +21,15 @@ module Samagotchi
   # --new starts a session instead, and --wait blocks for the reply and
   # prints it: an agent's one-shot the user can watch in the web.
   class SendCommand
+    include CLI::Command
+
     CLIENT_ID = "cli:send"
     POLL_INTERVAL = ReplyWait::POLL_INTERVAL
     # No live worker this long while waiting: it died before it could mark
     # the session (a worker takes well under a second to start).
     WORKER_GONE_AFTER = 5
-    # The Bridge's cap on one turn's images (Bridge::MAX_TURN_IMAGES).
-    MAX_IMAGES = 20
+    # The cap on one turn's images the Bridge checks.
+    MAX_IMAGES = ImageStore::MAX_TURN_REFS
 
     USAGE = <<~TEXT
       Usage: chi send [-m TEXT] [--image PATH]... (ID|PREFIX)...
@@ -59,6 +63,19 @@ module Samagotchi
         Find ids with: chi sessions list --live [--scope=all] [--format tsv]
     TEXT
 
+    FLAGS = CLI::Flags.new(help: CLI::Command::HELP_WORDS) do |f|
+      f.value "-m", "--message"
+      f.switch "--new"
+      f.value "--dir"
+      f.value "--model"
+      f.value "--image", key: :images, repeat: true
+      f.switch "--wait"
+      f.value "--timeout"
+      # Starting a turn in every live session at once is too easy to do
+      # by accident.
+      f.refuse "--all", "there is no --all: name the sessions"
+    end
+
     # Whether +model_name+ (a session's; blank: the configured default)
     # takes images, decided as its worker decides before a turn with images
     # (Engine#turn_vision: VisionSupport, with models.<name>.vision under
@@ -72,7 +89,7 @@ module Samagotchi
       name = ModelProfile.required_model_name(model_name)
       aliased = ConfigFile.resolve_model_alias(name)
       target = registry.resolve(aliased)
-      names = [name, aliased, registry.parse_qualified_model(name).last, target.bare_model].compact.uniq
+      names = registry.lookup_names(name, target: target)
       entry = target.entry
       return VisionSupport.for(target, adapter: registry.adapter_for(entry), names: names) if entry.chat?
 
@@ -106,22 +123,17 @@ module Samagotchi
     #   2 usage; with --wait 0 answered, 3 waiting for an answer, 130
     #   Ctrl-C (the turn goes on)
     def run
-      options = parse or return 2
-      return 0 if options[:help]
+      options = parse
+      return options if options.is_a?(Integer)
 
       # With --wait stdout is the answer alone.
       @info = options[:wait] ? @stderr : @stdout
       prompt = compose(utf8(read_stdin), utf8(options[:message]))
       # Before the wait-only case, which would drop the images.
-      if prompt.nil? && !options[:images].empty?
-        usage_error("--image needs a message: pass -m TEXT or pipe it in")
-        return 2
-      end
+      return usage_error("--image needs a message: pass -m TEXT or pipe it in") if prompt.nil? && !options[:images].empty?
       return run_wait_only(options) if prompt.nil? && options[:wait] && !options[:new]
-      unless prompt
-        usage_error("no message: pass -m TEXT or pipe it in")
-        return 2
-      end
+      return usage_error("no message: pass -m TEXT or pipe it in") unless prompt
+
       begin
         prompt = SessionInbox.checked_text(prompt, noun: "message")
       rescue SessionInbox::NoteRejected => e
@@ -150,33 +162,15 @@ module Samagotchi
 
     private
 
+    def command_name = "chi send"
+
+    # @return [Hash, Integer] the options, or the exit status after the
+    #   help or a usage error
     def parse
-      options = { ids: [], images: [] }
-      until @argv.empty?
-        arg = @argv.shift
-        case arg
-        when "-h", "--help", "help"
-          @stdout.puts(USAGE)
-          return { help: true }
-        when "-m", "--message"
-          options[:message] = @argv.shift or return usage_error("#{arg} needs a value")
-        when /\A--message=(.*)\z/m then options[:message] = Regexp.last_match(1)
-        when "--new" then options[:new] = true
-        when "--dir", "--model"
-          options[arg.delete_prefix("--").to_sym] = @argv.shift or return usage_error("#{arg} needs a value")
-        when /\A--(dir|model)=(.*)\z/m then options[Regexp.last_match(1).to_sym] = Regexp.last_match(2)
-        when "--image" then options[:images] << (@argv.shift or return usage_error("#{arg} needs a value"))
-        when /\A--image=(.*)\z/m then options[:images] << Regexp.last_match(1)
-        when "--wait" then options[:wait] = true
-        when "--timeout" then options[:timeout] = @argv.shift or return usage_error("#{arg} needs a value")
-        when /\A--timeout=(.*)\z/ then options[:timeout] = Regexp.last_match(1)
-        # Starting a turn in every live session at once is too easy to do
-        # by accident.
-        when "--all" then return usage_error("there is no --all: name the sessions")
-        when /\A-/ then return usage_error("unknown option #{arg}")
-        else options[:ids] << arg
-        end
-      end
+      parsed = parse_flags(FLAGS, @argv, images: [])
+      return parsed if parsed.is_a?(Integer)
+
+      options = parsed.options.merge(ids: parsed.args)
       if options[:timeout]
         return usage_error("--timeout needs --wait") unless options[:wait]
 
@@ -470,18 +464,5 @@ module Samagotchi
     def utf8(text)
       text&.dup&.force_encoding(Encoding::UTF_8)&.scrub
     end
-
-    # stderr isn't buffered, stdout is when it's a pipe: flush the lines
-    # already printed, so the output keeps the order of the ids given.
-    def error_line(text)
-      @stdout.flush
-      @stderr.puts(text)
-    end
-
-    def usage_error(message)
-      error_line("chi send: #{message}")
-      @stderr.puts(USAGE)
-      nil
-    end
   end
 end