openclacky 1.2.7 → 1.2.9

data/lib/clacky/patch_loader.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "yaml"
+
+begin
+  require "prism"
+rescue LoadError
+  # Prism is a stdlib on Ruby 3.3+. On older Rubies we fall back to
+  # RubyVM::AbstractSyntaxTree (available since 2.6).
+end
+
+module Clacky
+  # Runtime patch layer. Loads user/AI-authored patches from ~/.clacky/patches/
+  # that override existing methods via Module#prepend, WITHOUT touching the
+  # installed gem source (so `gem update` never loses them).
+  #
+  # Each patch lives in its own directory:
+  #   ~/.clacky/patches/<id>/
+  #     meta.yml    declares target + a fingerprint of the original method source
+  #     patch.rb    a prepend module that overrides the target method
+  #
+  # Safety — fingerprint drift:
+  #   meta.yml records a SHA256 of the targeted method's source at authoring time.
+  #   Before applying, the loader recomputes the fingerprint of the method as it
+  #   exists in the CURRENTLY installed gem. If they differ, the upstream code has
+  #   changed and the patch may no longer be valid, so by default the patch is
+  #   DISABLED (moved to _disabled/) rather than applied — a stale patch must never
+  #   silently corrupt behavior.
+  #
+  # meta.yml:
+  #   id: fix-web-search-timeout
+  #   description: bump default timeout to 30s
+  #   target: "Clacky::Tools::WebSearch#execute"   # '#' = instance, '.' = class method
+  #   fingerprint: "a3f8c…"
+  #   gem_version: "0.7.0"
+  #   on_mismatch: disable                         # disable | warn (default disable)
+  module PatchLoader
+    DEFAULT_DIR  = File.expand_path("~/.clacky/patches")
+    DISABLED_DIR = "_disabled"
+
+    Result = Struct.new(:applied, :disabled, :skipped, keyword_init: true)
+
+    class << self
+      def load_all(dir: DEFAULT_DIR)
+        result = Result.new(applied: [], disabled: [], skipped: [])
+        if Dir.exist?(dir)
+          Dir.glob(File.join(dir, "*", "meta.yml")).sort.each do |meta_path|
+            patch_dir = File.dirname(meta_path)
+            next if File.basename(File.dirname(patch_dir)) == DISABLED_DIR
+
+            apply_one(patch_dir, meta_path, result)
+          end
+        end
+        @last_result = result
+        result
+      end
+
+      def last_result
+        @last_result || load_all
+      end
+
+      # Generate a ready-to-edit patch (meta.yml + patch.rb) for a target method.
+      # Computes the current fingerprint automatically so the author never does it
+      # by hand. The patch.rb skeleton prepends a module that overrides the method
+      # and calls super by default.
+      # @param target [String] "Const::Path#method" or "Const::Path.method"
+      # @return [String] path to the new patch directory
+      def scaffold(id, target, description: "", dir: DEFAULT_DIR)
+        slug = id.to_s.strip.downcase.gsub(/[^a-z0-9_-]+/, "-").gsub(/\A-+|-+\z/, "")
+        raise ArgumentError, "invalid patch id: #{id.inspect}" if slug.empty?
+
+        fp = fingerprint(target)  # also validates the target resolves
+
+        patch_dir = File.join(dir, slug)
+        raise ArgumentError, "patch already exists: #{patch_dir}" if Dir.exist?(patch_dir)
+
+        FileUtils.mkdir_p(patch_dir)
+        File.write(File.join(patch_dir, "meta.yml"), <<~YAML)
+          id: #{slug}
+          description: #{description.to_s.empty? ? "(describe what this fixes)" : description}
+          target: "#{target}"
+          fingerprint: "#{fp}"
+          gem_version: "#{Clacky::VERSION}"
+          on_mismatch: disable
+        YAML
+        File.write(File.join(patch_dir, "patch.rb"), patch_skeleton(slug, target))
+        patch_dir
+      end
+
+      def patch_skeleton(slug, target)
+        const_name, sep, method_name = target.partition(/[#.]/)
+        mod_const = "Patch_#{slug.gsub(/[^a-zA-Z0-9_]/, "_")}"
+        prepend_target = sep == "#" ? const_name : "#{const_name}.singleton_class"
+
+        <<~RUBY
+          # frozen_string_literal: true
+
+          # Patch for #{target}
+          # Only edit the method body below. Call `super` to keep the original behavior.
+          module #{mod_const}
+            def #{method_name}(*args, **kwargs, &blk)
+              # TODO: your fix here. Examples:
+              #   result = super
+              #   result
+              super
+            end
+          end
+
+          #{prepend_target}.prepend(#{mod_const})
+        RUBY
+      end
+
+      # Recompute the fingerprint of a target's method as currently installed.
+      # @param target [String] "Const::Path#instance_method" or "Const::Path.class_method"
+      # @return [String] SHA256 hex of the method's source
+      # @raise [RuntimeError] if the target can't be resolved
+      def fingerprint(target)
+        meth = original_method(resolve_method(target))
+        file, lineno = meth.source_location
+        raise "no source location for #{target} (defined in C or eval?)" unless file && lineno
+
+        first, last = method_line_range(file, lineno, meth.name, meth)
+        raise "cannot locate source for #{target} in #{file}:#{lineno}" unless first && last
+
+        lines = File.readlines(file)[(first - 1)...last]
+        Digest::SHA256.hexdigest(lines.join)
+      end
+
+      def method_line_range(file, lineno, name, meth)
+        if defined?(Prism)
+          range = prism_line_range(file, lineno, name)
+          return range if range
+        end
+
+        ast_line_range(meth)
+      end
+
+      def prism_line_range(file, lineno, name)
+        result = Prism.parse_file(file)
+        return nil unless result.success?
+
+        node = find_def_at(result.value, lineno, name.to_sym)
+        return nil unless node
+
+        loc = node.location
+        [loc.start_line, loc.end_line]
+      end
+
+      def find_def_at(node, lineno, name)
+        return nil unless node
+
+        if node.is_a?(Prism::DefNode) && node.name == name && node.location.start_line == lineno
+          return node
+        end
+
+        node.compact_child_nodes.each do |child|
+          found = find_def_at(child, lineno, name)
+          return found if found
+        end
+        nil
+      end
+
+      def ast_line_range(meth)
+        return nil unless defined?(RubyVM::AbstractSyntaxTree)
+
+        node = RubyVM::AbstractSyntaxTree.of(meth)
+        return nil unless node
+
+        [node.first_lineno, node.last_lineno]
+      rescue StandardError
+        nil
+      end
+
+      # Walk past any methods introduced by our own patches (files under the
+      # patches dir) so the fingerprint always reflects the original upstream
+      # definition, even after a prepend has already been applied.
+      def original_method(meth)
+        current = meth
+        while current
+          file, = current.source_location
+          break if file.nil? || !file.start_with?(DEFAULT_DIR)
+
+          nxt = current.super_method
+          break if nxt.nil?
+
+          current = nxt
+        end
+        current
+      end
+
+      def resolve_method(target)
+        if target.include?("#")
+          const_name, method_name = target.split("#", 2)
+          const = resolve_const(const_name)
+          const.instance_method(method_name.to_sym)
+        elsif target.include?(".")
+          const_name, method_name = target.split(".", 2)
+          const = resolve_const(const_name)
+          const.method(method_name.to_sym)
+        else
+          raise "invalid target (need '#' or '.'): #{target}"
+        end
+      end
+
+      def apply_one(patch_dir, meta_path, result)
+        id = File.basename(patch_dir)
+        meta = YAMLCompat.load_file(meta_path) || {}
+        target = meta["target"].to_s
+        recorded = meta["fingerprint"].to_s
+
+        if target.empty? || recorded.empty?
+          result.skipped << [id, "meta.yml missing target or fingerprint"]
+          log(:warn, id, result.skipped.last[1])
+          return
+        end
+
+        current = begin
+          fingerprint(target)
+        rescue StandardError => e
+          result.skipped << [id, "cannot fingerprint #{target}: #{e.message}"]
+          log(:warn, id, result.skipped.last[1])
+          return
+        end
+
+        if current != recorded
+          handle_mismatch(patch_dir, id, meta, result)
+          return
+        end
+
+        patch_rb = File.join(patch_dir, "patch.rb")
+        unless File.exist?(patch_rb)
+          result.skipped << [id, "patch.rb not found"]
+          log(:warn, id, result.skipped.last[1])
+          return
+        end
+
+        require patch_rb
+        result.applied << id
+        log(:info, id, "applied → #{target}")
+      rescue StandardError, ScriptError => e
+        result.skipped << [id, e.message]
+        log(:warn, id, e.message)
+      end
+
+      def handle_mismatch(patch_dir, id, meta, result)
+        reason = "fingerprint mismatch — upstream code for #{meta["target"]} changed"
+        if meta["on_mismatch"].to_s == "warn"
+          result.skipped << [id, "#{reason} (kept, not applied)"]
+          log(:warn, id, result.skipped.last[1])
+          return
+        end
+
+        disable!(patch_dir, id)
+        result.disabled << [id, reason]
+        log(:warn, id, "#{reason} — disabled")
+      end
+
+      def disable!(patch_dir, id)
+        base = File.dirname(patch_dir)
+        dest_root = File.join(base, DISABLED_DIR)
+        FileUtils.mkdir_p(dest_root)
+        dest = File.join(dest_root, id)
+        FileUtils.rm_rf(dest)
+        FileUtils.mv(patch_dir, dest)
+      rescue StandardError => e
+        log(:error, id, "failed to disable: #{e.message}")
+      end
+
+      def resolve_const(name)
+        name.split("::").reject(&:empty?).inject(Object) do |mod, part|
+          mod.const_get(part)
+        end
+      end
+
+      def log(level, id, msg)
+        Clacky::Logger.public_send(level, "[PatchLoader] #{id}: #{msg}")
+      end
+    end
+  end
+end

data/lib/clacky/providers.rb

@@ -41,6 +41,17 @@ module Clacky
           "dsk-deepseek-v4-flash",
           "or-gemini-3-1-pro"
         ],
+        # Image generation models served by the openclacky platform
+        # gateway. The gateway exposes a standard OpenAI-compatible
+        # /v1/images/generations endpoint, so the same OpenAICompat
+        # provider class handles them. `or-` prefix mirrors the chat
+        # model naming — these are routed through the OpenRouter
+        # backend by the platform.
+        "image_models" => [
+          "or-gemini-3-pro-image",
+          "or-gpt-image-2"
+        ],
+        "default_image_model" => "or-gpt-image-2",
         # Provider-level default: the Claude family served here is vision-capable.
         "capabilities" => { "vision" => true }.freeze,
         # Model-level overrides: DeepSeek models routed through this provider
@@ -123,6 +134,13 @@ module Clacky
           /\Aanthropic\// => "anthropic-messages",
           /\Aclaude[-.]/  => "anthropic-messages"
         }.freeze,
+        # Image generation via OpenRouter is currently routed through the
+        # openclacky platform gateway (see "openclacky" provider above) which
+        # handles the OpenRouter chat-completions + modalities translation.
+        # Direct OpenRouter image config is not exposed here — leave empty
+        # until we ship a dedicated client-side adapter for that protocol.
+        "image_models" => [],
+        "default_image_model" => nil,
         "website_url" => "https://openrouter.ai/keys"
       }.freeze,
 
@@ -305,6 +323,12 @@ module Clacky
           "gpt-5.5" => "gpt-5.4-mini",
           "gpt-5.4" => "gpt-5.4-mini"
         },
+        # OpenAI's image generation model — same /v1/images/generations
+        # endpoint, so the OpenAICompat image provider handles it.
+        "image_models" => [
+          "gpt-image-2"
+        ],
+        "default_image_model" => "gpt-image-2",
         "website_url" => "https://platform.openai.com/api-keys"
       }.freeze,
 
@@ -342,6 +366,8 @@ module Clacky
 
     }.freeze
 
+    MEDIA_KINDS = %w[image video audio].freeze
+
     class << self
       # Check if a provider preset exists
       # @param provider_id [String] The provider identifier (e.g., "anthropic", "openrouter")
@@ -446,6 +472,62 @@ module Clacky
         preset&.dig("models") || []
       end
 
+      # Get available image generation models for a provider.
+      # Returns an empty array when the provider doesn't declare any —
+      # callers should treat that as "image generation not supported by this provider".
+      # @param provider_id [String] The provider identifier
+      # @return [Array<String>] List of image model names
+      def image_models(provider_id)
+        preset = PRESETS[provider_id]
+        preset&.dig("image_models") || []
+      end
+
+      # Video generation models — placeholder. No provider supports video
+      # via Clacky yet; once they do, declare "video_models" alongside
+      # "image_models" in the relevant PRESETS entry and this returns it.
+      def video_models(provider_id)
+        preset = PRESETS[provider_id]
+        preset&.dig("video_models") || []
+      end
+
+      # Audio generation models — same placeholder pattern as video_models.
+      def audio_models(provider_id)
+        preset = PRESETS[provider_id]
+        preset&.dig("audio_models") || []
+      end
+
+      # Unified entry for media model lookup by kind.
+      # @param provider_id [String]
+      # @param kind [String] one of "image" / "video" / "audio"
+      # @return [Array<String>]
+      def media_models(provider_id, kind)
+        case kind.to_s
+        when "image" then image_models(provider_id)
+        when "video" then video_models(provider_id)
+        when "audio" then audio_models(provider_id)
+        else []
+        end
+      end
+
+      # Default media model for a kind under a provider. Falls back to the
+      # first declared model when no explicit default is set in the preset.
+      # Used by AgentConfig#derive_media_models! to pick which model to
+      # surface when the user is on "auto" mode.
+      def default_media_model(provider_id, kind)
+        preset = PRESETS[provider_id]
+        return nil unless preset
+        explicit = preset["default_#{kind}_model"]
+        return explicit if explicit
+        media_models(provider_id, kind).first
+      end
+
+      # The set of media kinds Clacky knows about. Drives UI rendering and
+      # derivation loops — adding a new modality means listing it here plus
+      # adding the corresponding generator class.
+      def media_kinds
+        MEDIA_KINDS
+      end
+
       # Get the lite model for a provider.
       # @param provider_id [String] The provider identifier
       # @param primary_model [String, nil] The currently-selected primary model name.

data/lib/clacky/server/channel/adapters/base.rb

@@ -15,6 +15,10 @@ module Clacky
         @registry[platform.to_sym]
       end
 
+      def self.unregister(platform)
+        @registry.delete(platform.to_sym)
+      end
+
       def self.all
         @registry.values
       end

data/lib/clacky/server/channel/channel_manager.rb

@@ -511,7 +511,7 @@ module Clacky
         platform = event[:platform].to_s
         count    = @mutex.synchronize { @session_counters[platform] += 1 }
         name     = "#{platform}-#{count}"
-        session_id = @session_builder.call(name: name, working_dir: Dir.home, source: :channel)
+        session_id = @session_builder.call(name: name, source: :channel)
         bind_key_to_session(key, session_id)
 
         # Create a long-lived ChannelUIController for this session and subscribe it

data/lib/clacky/server/channel/user_adapter_loader.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Clacky
+  module Channel
+    module Adapters
+      # Loads user-defined channel adapters from ~/.clacky/channels/<name>/adapter.rb.
+      #
+      # Each adapter file is plain Ruby that defines a subclass of
+      # Clacky::Channel::Adapters::Base and self-registers via Adapters.register,
+      # exactly like the bundled adapters. This loader only discovers and requires
+      # those files after the built-in adapters are loaded — the existing
+      # self-registration mechanism then takes over with no further wiring.
+      #
+      # A broken adapter (syntax error, missing interface methods) is isolated:
+      # it is skipped with a logged warning and never aborts the load of others.
+      module UserAdapterLoader
+        DEFAULT_DIR = File.expand_path("~/.clacky/channels")
+
+        # Required class/instance methods a user adapter must implement to be usable.
+        REQUIRED_CLASS_METHODS    = %i[platform_id platform_config].freeze
+        REQUIRED_INSTANCE_METHODS = %i[start stop send_text].freeze
+
+        Result = Struct.new(:loaded, :skipped, keyword_init: true)
+
+        # @param dir [String] directory to scan (override for tests)
+        # @return [Result] names loaded and skipped (with reasons)
+        def self.load_all(dir: DEFAULT_DIR)
+          result = Result.new(loaded: [], skipped: [])
+          if Dir.exist?(dir)
+            Dir.glob(File.join(dir, "*", "adapter.rb")).sort.each do |path|
+              name = File.basename(File.dirname(path))
+              load_one(path, name, result)
+            end
+          end
+          @last_result = result
+          result
+        end
+
+        # The result of the most recent load_all (set at startup). Lets `channel_verify`
+        # report status without re-requiring files (require is idempotent and would
+        # otherwise report already-loaded adapters as "did not register").
+        def self.last_result
+          @last_result || load_all
+        end
+
+        def self.load_one(path, name, result)
+          before = Adapters.all.dup
+
+          require path
+
+          newly = Adapters.all - before
+          klass = newly.last
+
+          unless klass
+            result.skipped << [name, "did not register an adapter (missing Adapters.register?)"]
+            log_skip(name, result.skipped.last[1])
+            return
+          end
+
+          if (missing = interface_gaps(klass)).any?
+            unregister(klass)
+            result.skipped << [name, "missing required methods: #{missing.join(", ")}"]
+            log_skip(name, result.skipped.last[1])
+            return
+          end
+
+          result.loaded << name
+          Clacky::Logger.info("[UserAdapterLoader] Loaded channel adapter '#{name}' → :#{klass.platform_id}")
+        rescue StandardError, ScriptError => e
+          result.skipped << [name, e.message]
+          log_skip(name, e.message)
+        end
+
+        def self.interface_gaps(klass)
+          missing = REQUIRED_CLASS_METHODS.reject { |m| klass.respond_to?(m) }
+          # Base defines stub instance methods that only raise NotImplementedError,
+          # so method_defined? alone passes via inheritance. Require the subclass to
+          # actually override them — i.e. the method's owner must not be Base.
+          missing += REQUIRED_INSTANCE_METHODS.reject do |m|
+            klass.method_defined?(m) && klass.instance_method(m).owner != Base
+          end
+          missing
+        end
+
+        def self.unregister(klass)
+          platform = (klass.platform_id if klass.respond_to?(:platform_id))
+          return unless platform
+
+          Adapters.unregister(platform)
+        end
+
+        def self.log_skip(name, reason)
+          Clacky::Logger.warn("[UserAdapterLoader] Skipped channel adapter '#{name}': #{reason}")
+        end
+
+        # Generate a ready-to-edit adapter skeleton at ~/.clacky/channels/<name>/adapter.rb.
+        # The skeleton already self-registers and implements the full interface with
+        # TODO markers — the author only fills in the method bodies.
+        # @return [String] path to the generated adapter.rb
+        def self.scaffold(name, dir: DEFAULT_DIR)
+          slug = name.to_s.strip.downcase.gsub(/[^a-z0-9_]+/, "_").gsub(/\A_+|_+\z/, "")
+          raise ArgumentError, "invalid channel name: #{name.inspect}" if slug.empty?
+
+          target_dir = File.join(dir, slug)
+          path = File.join(target_dir, "adapter.rb")
+          raise ArgumentError, "adapter already exists: #{path}" if File.exist?(path)
+
+          FileUtils.mkdir_p(target_dir)
+          File.write(path, skeleton(slug))
+          path
+        end
+
+        def self.skeleton(slug)
+          const = slug.split("_").map(&:capitalize).join
+          <<~RUBY
+            # frozen_string_literal: true
+
+            # User-defined channel adapter for ":#{slug}".
+            # Edit the TODO sections, then it loads automatically on next start.
+            # Verify with: clacky channel verify
+
+            module Clacky
+              module Channel
+                module Adapters
+                  class #{const}Adapter < Base
+                    def self.platform_id
+                      :#{slug}
+                    end
+
+                    # Map raw config (channels.yml `#{slug}` section) to a symbol-keyed hash.
+                    def self.platform_config(data)
+                      {
+                        # TODO: pull your credentials out of `data`
+                        # token: data["IM_#{slug.upcase}_TOKEN"] || data["token"]
+                      }.compact
+                    end
+
+                    def initialize(config)
+                      @config = config
+                    end
+
+                    # Begin receiving messages. Blocks until #stop — runs inside a Thread.
+                    # Yield one standardized event Hash per inbound message.
+                    def start(&on_message)
+                      # TODO: connect to your platform and loop, calling on_message.call(event)
+                      raise NotImplementedError
+                    end
+
+                    def stop
+                      # TODO: close connections / stop the read loop
+                    end
+
+                    # Send a plain text (or Markdown) message to a chat.
+                    # @return [Hash] { message_id: String }
+                    def send_text(chat_id, text, reply_to: nil)
+                      # TODO: call your platform's send API
+                      raise NotImplementedError
+                    end
+
+                    # Optional: validate config; return array of error strings (empty = ok).
+                    def validate_config(config)
+                      []
+                    end
+
+                    Adapters.register(platform_id, self)
+                  end
+                end
+              end
+            end
+          RUBY
+        end
+      end
+    end
+  end
+end

data/lib/clacky/server/channel.rb

@@ -31,3 +31,8 @@ require_relative "channel/adapters/dingtalk/adapter"
 require_relative "channel/channel_config"
 require_relative "channel/channel_ui_controller"
 require_relative "channel/channel_manager"
+
+# Discover and load user-defined adapters from ~/.clacky/channels/.
+# Must run after the bundled adapters so user adapters can extend or override.
+require_relative "channel/user_adapter_loader"
+Clacky::Channel::Adapters::UserAdapterLoader.load_all