samagotchi 0.2.0

data/lib/samagotchi/owner_lock.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "time"
+
+module Samagotchi
+  # The single-owner lock of a session: whichever process runs the session's
+  # Engine (a SessionManager worker or the in-process TUI) holds an exclusive
+  # flock on `<session_dir>/owner.lock` for its lifetime. A second would-be
+  # owner backs off, so one session never gets two Engines.
+  #
+  # flock locks belong to the open file description: the kernel releases them
+  # when the owner exits (however it dies), Ruby opens files close-on-exec so a
+  # spawned grandchild never inherits one, and probing from another descriptor
+  # (even in the owner's own process) never releases the owner's lock.
+  class OwnerLock
+    FILE = "owner.lock"
+    DEFAULT_WAIT = 2.0
+    RETRY_INTERVAL = 0.05
+    OWNER_READ_ATTEMPTS = 10
+
+    # 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.
+    # @param session_dir [String]
+    # @param kind [String] "worker" or "tui"
+    # @return [OwnerLock, nil] nil when another owner holds it
+    def self.acquire(session_dir, kind:, wait: DEFAULT_WAIT)
+      FileUtils.mkdir_p(session_dir)
+      file = File.open(path(session_dir), File::RDWR | File::CREAT, 0o644)
+      deadline = monotonic_now + wait.to_f
+      until file.flock(File::LOCK_EX | File::LOCK_NB)
+        if monotonic_now >= deadline
+          file.close
+          return nil
+        end
+        sleep(RETRY_INTERVAL)
+      end
+      new(file, kind: kind)
+    end
+
+    # 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
+    def self.owner(session_dir)
+      File.open(path(session_dir), File::RDONLY) do |file|
+        if file.flock(File::LOCK_SH | File::LOCK_NB)
+          file.flock(File::LOCK_UN)
+          return nil
+        end
+        # A new owner truncates, then writes: retry briefly rather than
+        # report an owner of unknown kind.
+        data = {}
+        OWNER_READ_ATTEMPTS.times do
+          data = parse(File.read(file.path))
+          break unless data.empty?
+
+          sleep(RETRY_INTERVAL / 5)
+        end
+        data
+      end
+    rescue Errno::ENOENT
+      nil
+    end
+
+    # @return [Boolean] whether this session has ever had a lock-taking owner
+    #   (workers from before the lock only left a pid file)
+    def self.lock_file?(session_dir)
+      File.exist?(path(session_dir))
+    end
+
+    def self.path(session_dir)
+      File.join(session_dir, FILE)
+    end
+
+    def self.parse(raw)
+      data = JSON.parse(raw.to_s)
+      data.is_a?(Hash) ? data : {}
+    rescue JSON::ParserError
+      {}
+    end
+    private_class_method :parse
+
+    def self.monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+    private_class_method :monotonic_now
+
+    attr_reader :kind
+
+    def initialize(file, kind:)
+      @file = file
+      @kind = kind.to_s
+      @file.truncate(0)
+      @file.rewind
+      @file.write(JSON.generate("pid" => Process.pid, "kind" => @kind, "started_at" => Time.now.iso8601(3)))
+      @file.flush
+    end
+
+    # Release the lock (process exit releases it too).
+    def release
+      return if @file.closed?
+
+      @file.flock(File::LOCK_UN)
+      @file.close
+    end
+  end
+end

data/lib/samagotchi/pending_input_queue.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # Thread-safe FIFO of user steering messages submitted while a turn is
+  # running. UIs (TUI, web, background workers) are push-only producers;
+  # KernelLoop drains the queue at iteration boundaries and injects the
+  # messages into the conversation. True mid-stream injection is impossible
+  # with llama.cpp's /completion API, so draining only happens between full
+  # LLM responses / tool dispatches.
+  #
+  # Usage:
+  #   queue = PendingInputQueue.new
+  #   queue.push("please also check the specs")
+  #   kernel.run(messages, pending_input: queue.method(:drain))
+  class PendingInputQueue
+    def initialize
+      @mutex = Mutex.new
+      @messages = []
+    end
+
+    # Append a message to the queue. Nil/empty strings are ignored.
+    def push(text)
+      text = text.to_s
+      return if text.empty?
+
+      @mutex.synchronize { @messages << text }
+      nil
+    end
+
+    # Remove and return all queued messages in FIFO order. Non-blocking.
+    # @return [Array<String>]
+    def drain
+      @mutex.synchronize do
+        drained = @messages
+        @messages = []
+        drained
+      end
+    end
+
+    def empty?
+      @mutex.synchronize { @messages.empty? }
+    end
+
+    def size
+      @mutex.synchronize { @messages.size }
+    end
+  end
+end

data/lib/samagotchi/plugin/api.rb

@@ -0,0 +1,362 @@
+# frozen_string_literal: true
+
+require_relative "../log"
+require_relative "../tools/args"
+require_relative "service"
+require_relative "tool_result"
+
+module Samagotchi
+  module Plugin
+    # What a plugin's #register(chi) gets (docs/plugins.md). Each call
+    # stages a registration and checks it; Loader commits them all once
+    # #register returns, so a plugin that raises halfway adds nothing.
+    class Api
+      COMMAND_NAME = %r{\A/[a-z][a-z0-9_-]{0,31}\z}
+      TOOL_NAME = /\A[a-z][a-z0-9_]{0,47}\z/
+      PARAM_NAME = /\A[a-z_][a-z0-9_]*\z/i
+
+      # @param bundle [String]
+      # @param label [String] "<file> (bundle <name>)": what hooks and
+      #   failures are named by
+      # @param registries [Registries]
+      # @param context [Context, nil] what handlers get as ctx
+      def initialize(bundle:, label:, registries:, context: nil)
+        @bundle = bundle
+        @label = label
+        @registries = registries
+        @context = context
+        @hooks = []
+        @commands = []
+        @tools = []
+        @services = []
+        @inits = []
+        @committed = false
+      end
+
+      # The Context the plugin's handlers get, for #register itself: its
+      # settings, log, data_dir, and ctx.notify / ctx.card, which, shown
+      # while chi starts, wait for the first turn (beside the plugins' load
+      # warnings).
+      # @return [Context, nil]
+      def ctx = @context
+
+      # A slash command the session runs: the block gets the text after the
+      # name (stripped, "" for none) and the Context, and returns what to
+      # 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)
+      def command(name, description, anytime: false, &block)
+        raise ArgumentError, "command #{name.inspect} needs a block" unless block
+        name = name.to_s
+        raise ArgumentError, "command name #{name.inspect} must look like /name (a-z, 0-9, _ and -)" unless name.match?(COMMAND_NAME)
+        if (taken = @registries.commands.entries.find { |entry| entry.name == name })
+          raise ArgumentError, "command #{name} is already registered (#{taken.source})"
+        end
+        raise ArgumentError, "command #{name} is registered twice" if @commands.any? { |cmd| cmd[:name] == name }
+
+        @commands << { name: name, description: description.to_s, anytime: anytime ? true : false, block: block }
+        nil
+      end
+
+      # A tool the model can call: the block gets the call's arguments (a
+      # frozen Hash, string keys, typed by the schema: see Tools::Args) and
+      # the Context, and returns the result text ("Error: …" marks a
+      # failure). A raise is the model's "Error: <message>".
+      # @param name [String] a-z, 0-9 and _; a name the session already has
+      #   is a load error
+      # @param params [Hash] name => a JSON Schema property ({type:,
+      #   description:, enum:, items:, properties:, …}) plus required: true
+      # @param schema [Hash, nil] instead of params: the parameters as one
+      #   JSON Schema object ({type: "object", properties:, required: […]}),
+      #   an MCP server's inputSchema for example
+      # @param label [String, nil] the activity line's action
+      # @param preview [#call, nil] args → the activity line's params
+      # @param targets [#call, nil] args → what guardrail rules match: a Hash
+      #   with paths: (absolute or relative to the cwd), command: (a shell
+      #   command) and cwd:, each optional
+      def tool(name, description, params: {}, schema: nil, label: nil, preview: nil, targets: nil, &block)
+        spec = Api.tool_spec(name, description, params: params, schema: schema, label: label, preview: preview,
+                                                targets: targets, &block)
+        if (taken = @registries.tools[spec[:name]])
+          raise ArgumentError, "tool #{spec[:name]} is already registered (#{taken.source})"
+        end
+        raise ArgumentError, "tool #{spec[:name]} is registered twice" if @tools.any? { |tool| tool[:name] == spec[:name] }
+
+        @tools << spec
+        nil
+      end
+
+      # The plugin's whole tool set, after #register (a plugin whose tools
+      # are known only later: an MCP server that listed them). The block
+      # gets a set whose #tool takes #tool's arguments; what it declares
+      # replaces the plugin's tools from the next turn on: its tools not in
+      # the set go, new or changed ones are registered, and the system
+      # prompts are built again if anything changed. Safe from any thread:
+      # the set is staged, and the turn thread applies it before the
+      # turn's first model request. A name another bundle (or chi) has is
+      # left out, with a notice.
+      # @raise [ArgumentError] a bad tool (as #tool), or called in #register
+      def replace_tools
+        raise ArgumentError, "replace_tools needs a block" unless block_given?
+        raise ArgumentError, "replace_tools is for after register (use chi.tool there)" unless @committed
+
+        set = ToolSet.new
+        yield set
+        if (stage = @registries.stage_tools)
+          stage.call(@bundle, set.specs, @context)
+        elsif Api.apply_tools(@registries.tools, @bundle, set.specs, @context)[:changed]
+          tools_changed!
+        end
+        nil
+      end
+
+      # What #replace_tools' block declares tools on.
+      class ToolSet
+        # @return [Array<Hash>]
+        attr_reader :specs
+
+        def initialize
+          @specs = []
+        end
+
+        # As Api#tool.
+        def tool(name, description, params: {}, schema: nil, label: nil, preview: nil, targets: nil, &block)
+          spec = Api.tool_spec(name, description, params: params, schema: schema, label: label, preview: preview,
+                                                  targets: targets, &block)
+          raise ArgumentError, "tool #{spec[:name]} is registered twice" if @specs.any? { |s| s[:name] == spec[:name] }
+
+          @specs << spec
+          nil
+        end
+      end
+
+      # 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.
+      # @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
+        raise ArgumentError, "on: the event must be a Symbol or String" unless event.is_a?(Symbol) || event.is_a?(String)
+
+        @hooks << { event: event.to_sym, priority: Integer(priority), block: block }
+        nil
+      end
+
+      # A long-lived thing the plugin keeps (a server process): the block
+      # starts it and returns what #value gives; in it, svc.on_stop { }
+      # says how to stop it. It starts on first svc.value, or now with
+      # eager: true (a raise then fails the plugin's load, unless the
+      # plugin rescues it). The Engine stops its services when it shuts
+      # down (the REPL or the session's worker exits), newest first.
+      # @param name [String, Symbol] unique in the plugin
+      # @return [Service]
+      def service(name, eager: false, &block)
+        raise ArgumentError, "service #{name.inspect} needs a block" unless block
+        name = "#{@bundle}:#{name}"
+        raise ArgumentError, "service #{name} is registered twice" if @services.any? { |svc| svc.name == name }
+        raise ArgumentError, "this chi has no services (plugins: false)" unless @registries.services
+
+        service = @registries.services.add(Service.new(name, &block))
+        @services << service
+        service.start if eager
+        service
+      end
+
+      # Slow setup (downloading a model, indexing a repo, logging in, an
+      # MCP server's first start) that must not hold chi's start: the block
+      # runs on its own thread once the session's UI can show it, not in
+      # #register. It gets the Context (ctx.cancelled? says chi is shutting
+      # down) and returns a short summary ("3 tools") or raises (the UIs
+      # show a warn card). Every UI shows it running (the label) and done.
+      # @param label [String] what it does, shown while it runs
+      # @param provides_tools [Boolean] it registers tools (chi.replace_tools):
+      #   a turn sent meanwhile waits for it before its first model request,
+      #   up to +timeout+; a Ctrl-C ends the wait
+      # @param quiet [Boolean] shown only if it fails (a background refresh)
+      # @param timeout [Numeric, nil] seconds a turn waits for it (default 60)
+      # @param failed [String, nil] the warn card's short title if it raises
+      #   ("chrome didn't start"; default "setup failed", the label then
+      #   leads the card's body)
+      def init(label, provides_tools: false, quiet: false, timeout: nil, failed: nil, &block)
+        raise ArgumentError, "init needs a block" unless block
+        raise ArgumentError, "init needs a label" if label.to_s.strip.empty?
+        raise ArgumentError, "this chi runs no init tasks (plugins: false)" unless @registries.init
+
+        @inits << { label: label.to_s.strip, provides_tools: provides_tools ? true : false, quiet: quiet ? true : false,
+                    timeout: timeout && Float(timeout), failed: failed.to_s.strip.empty? ? nil : failed.to_s.strip,
+                    block: block }
+        nil
+      end
+
+      # Stop the services the plugin started: its load failed after all.
+      def abort!
+        @services.reverse_each(&:stop)
+        nil
+      end
+
+      # Say the session's tools changed after #register (a plugin that
+      # registers tools late): the system prompts are built again for the
+      # next turn, so the model sees the new set. That costs the server its
+      # cached prompt prefix once, so call it only when the set changed.
+      def tools_changed!
+        @registries.tools_changed&.call
+        nil
+      end
+
+      # Register what was staged. Called by Loader after #register.
+      def commit!
+        context = @context
+        @commands.each do |cmd|
+          block = cmd[:block]
+          @registries.commands.register(cmd[:name], cmd[:description], anytime: cmd[:anytime], source: @bundle) do |args|
+            block.call(args, context)
+          end
+        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
+          @registries.hooks.register_bundle(bundle, hook[:event], hook_name: label.split(" ").first,
+                                                                  priority: hook[:priority]) do |event|
+            block.call(event, context)
+          rescue StandardError => e
+            # 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}")
+          end
+        end
+        @inits.each do |init|
+          block = init[:block]
+          @registries.init.call(@bundle, init[:label], @label, provides_tools: init[:provides_tools], quiet: init[:quiet],
+                                                              timeout: init[:timeout], failed: init[:failed]) do
+            block.call(context)
+          end
+        end
+        @committed = true
+      end
+
+      # @return [Hash] how many of each it registered (for the log)
+      def counts = { commands: @commands.size, tools: @tools.size, hooks: @hooks.size, services: @services.size,
+                     inits: @inits.size }
+
+      # A checked tool declaration (#tool's arguments).
+      # @return [Hash] {name:, schema:, label:, preview:, targets:, block:}
+      def self.tool_spec(name, description, params: {}, schema: nil, label: nil, preview: nil, targets: nil, &block)
+        raise ArgumentError, "tool #{name.inspect} needs a block" unless block
+        name = name.to_s
+        raise ArgumentError, "tool name #{name.inspect} must be a-z, 0-9 and _ (at most 48)" unless name.match?(TOOL_NAME)
+        raise ArgumentError, "tool #{name}: preview must respond to #call" if preview && !preview.respond_to?(:call)
+        raise ArgumentError, "tool #{name}: targets must respond to #call" if targets && !targets.respond_to?(:call)
+
+        parameters = schema ? schema_parameters(name, schema) : params_schema(name, params)
+        { name: name, schema: { name: name, description: description.to_s, parameters: parameters },
+          label: label&.to_s, preview: preview, targets: targets, block: block }
+      end
+
+      # Make +bundle+'s tools in +registry+ the +specs+: its tools not in
+      # them go; a new one, or one whose schema or label changed, is
+      # registered (a changed one again, at the end); an unchanged one is
+      # kept as it is. A name another source has is left out. Called on
+      # the turn thread (Engine#apply_staged_tools!).
+      # @return [Hash] {changed: Boolean, skipped: [String] (why)}
+      def self.apply_tools(registry, bundle, specs, context)
+        wanted = specs.to_h { |spec| [spec[:name], spec] }
+        changed = false
+        registry.entries.each do |entry|
+          next unless entry.source == bundle
+          next if (spec = wanted[entry.name]) && spec[:schema] == entry.schema && spec[:label] == entry.label
+
+          registry.unregister(entry.name)
+          changed = true
+        end
+        skipped = []
+        specs.each do |spec|
+          if (taken = registry[spec[:name]])
+            skipped << "tool #{spec[:name]} is already registered (#{taken.source})" unless taken.source == bundle
+            next
+          end
+
+          registry.register(spec[:name], source: bundle, **entry_fields(spec, context))
+          changed = true
+        end
+        { changed: changed, skipped: skipped }
+      end
+
+      # Registry#register's keywords for a tool declaration: its block
+      # wrapped as a handler (typed args, the Context), preview, targets.
+      def self.entry_fields(spec, context)
+        block = spec[:block]
+        preview = spec[:preview]
+        targets = spec[:targets]
+        parameters = spec[:schema][:parameters]
+        {
+          schema: spec[:schema], label: spec[:label],
+          handler: lambda { |call, _kctx|
+            result = block.call(Api.args_of(call, parameters), context)
+            # A String (a ToolResult too, with its images) as it is.
+            result.is_a?(String) ? result : result.to_s
+          },
+          preview: preview && ->(call) { preview.call(Api.args_of(call, parameters))&.to_s },
+          targets: targets && ->(call) { targets.call(Api.args_of(call, parameters)) }
+        }
+      end
+
+      # A tool call's arguments as a plugin sees them: the parsers' args:
+      # (a call built without one, in a spec say: the call without its
+      # name), string keys, typed by +parameters+, frozen.
+      def self.args_of(call, parameters = nil)
+        given = call[:args].is_a?(Hash) ? call[:args] : call.reject { |key, _| key == :name || key == :args }
+        Tools::Args.coerce(given, parameters).freeze
+      end
+
+      # A JSON Schema with symbol keys (property names included), as
+      # ToolDeclarations::TOOL_SCHEMAS has them.
+      def self.symbolize(value)
+        case value
+        when Hash then value.to_h { |key, item| [key.to_sym, symbolize(item)] }
+        when Array then value.map { |item| symbolize(item) }
+        else value
+        end
+      end
+
+      # The parameters object from params: (name => property spec).
+      def self.params_schema(name, params)
+        raise ArgumentError, "tool #{name}: params must be a Hash" unless params.is_a?(Hash)
+
+        required = []
+        properties = params.each_with_object({}) do |(param, spec), acc|
+          param = param.to_s
+          raise ArgumentError, "tool #{name}: parameter name #{param.inspect} is not a plain word" unless param.match?(PARAM_NAME)
+          raise ArgumentError, "tool #{name}: parameter #{param} must be a Hash {type:, description:}" unless spec.is_a?(Hash)
+
+          spec = Api.symbolize(spec)
+          required << param if spec.delete(:required) == true
+          acc[param.to_sym] = { type: (spec.delete(:type) || "string").to_s, description: spec.delete(:description).to_s }.merge(spec)
+        end
+        { type: "object", properties: properties, required: required }
+      end
+      private_class_method :params_schema
+
+      # The parameters object from schema: (a JSON Schema object).
+      def self.schema_parameters(name, schema)
+        raise ArgumentError, "tool #{name}: schema must be a Hash" unless schema.is_a?(Hash)
+
+        schema = Api.symbolize(schema)
+        raise ArgumentError, "tool #{name}: schema must be {type: \"object\", properties: {…}}" unless schema.fetch(:type, "object").to_s == "object"
+
+        properties = schema[:properties] || {}
+        raise ArgumentError, "tool #{name}: schema properties must be a Hash" unless properties.is_a?(Hash)
+
+        { type: "object", properties: properties, required: Array(schema[:required]).map(&:to_s) }
+          .merge(schema.except(:type, :properties, :required))
+      end
+      private_class_method :schema_parameters
+    end
+  end
+end