openclacky 1.3.3 → 1.3.4

data/lib/clacky/api_extension.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Clacky
+  # Base class for user-defined HTTP API extensions loaded from
+  # ~/.clacky/api_ext/<name>/handler.rb. Subclasses use a tiny route DSL
+  # (get/post/put/patch/delete) to expose endpoints under
+  #   /api/ext/<name>/<sub-path>
+  #
+  # The framework wires up access-key auth, timeouts, JSON error envelopes,
+  # path-parameter parsing, and a curated handler context — extension authors
+  # only fill in business logic.
+  #
+  # Minimal example (~/.clacky/api_ext/my-dashboard/handler.rb):
+  #
+  #   class MyDashboardExt < Clacky::ApiExtension
+  #     get "/summary" do
+  #       json(sessions: session_manager.list.size)
+  #     end
+  #   end
+  #
+  # Mounted automatically at: GET /api/ext/my-dashboard/summary
+  class ApiExtension
+    HTTP_METHODS = %i[get post put patch delete].freeze
+    MAX_TIMEOUT  = 600
+    DEFAULT_TIMEOUT = 10
+
+    Route = Struct.new(:method, :pattern, :regex, :param_names, :block, :options, keyword_init: true)
+
+    class Halt < StandardError
+      attr_reader :status, :payload, :content_type
+
+      def initialize(status, payload, content_type)
+        super("api_ext halt #{status}")
+        @status       = status
+        @payload      = payload
+        @content_type = content_type
+      end
+    end
+
+    class << self
+      # Registry of all loaded ApiExtension subclasses, keyed by extension id
+      # (== directory name == mount prefix segment).
+      def registry
+        @registry ||= {}
+      end
+
+      def register(ext_id, klass)
+        registry[ext_id] = klass
+      end
+
+      def reset_registry!
+        @registry = {}
+        @pending_subclasses = []
+      end
+
+      # Captures every subclass at the moment its `class` body finishes being
+      # required — the loader pops the most recent one off this list to bind
+      # an ext_id/dir without relying on ObjectSpace scans.
+      def pending_subclasses
+        @pending_subclasses ||= []
+      end
+
+      def inherited(subclass)
+        super
+        Clacky::ApiExtension.pending_subclasses << subclass
+      end
+
+      # Per-subclass state — inherited classes carry their own routes/options.
+      def routes
+        @routes ||= []
+      end
+
+      def class_timeout
+        @class_timeout
+      end
+
+      def public_paths
+        @public_paths ||= []
+      end
+
+      def ext_id
+        @ext_id
+      end
+
+      def ext_id=(value)
+        @ext_id = value
+      end
+
+      def ext_dir
+        @ext_dir
+      end
+
+      def ext_dir=(value)
+        @ext_dir = value
+      end
+
+      def meta
+        @meta ||= {}
+      end
+
+      def meta=(value)
+        @meta = value || {}
+      end
+
+      # Set a default timeout (seconds) for every handler in this class.
+      # Per-route override available via `get "/x", timeout: 30 do ... end`.
+      def timeout(seconds)
+        raise ArgumentError, "timeout must be > 0" unless seconds.is_a?(Numeric) && seconds > 0
+        raise ArgumentError, "timeout exceeds MAX_TIMEOUT (#{MAX_TIMEOUT}s)" if seconds > MAX_TIMEOUT
+
+        @class_timeout = seconds.to_f
+      end
+
+      # Mark a route as not requiring access-key auth. Caller must also
+      # declare `public: true` in meta.yml for the framework to honor this.
+      def public_endpoint(pattern)
+        public_paths << normalize_pattern(pattern)
+      end
+
+      HTTP_METHODS.each do |verb|
+        define_method(verb) do |pattern, **opts, &block|
+          raise ArgumentError, "missing handler block for #{verb.upcase} #{pattern}" unless block
+
+          per_route_timeout = opts[:timeout]
+          if per_route_timeout
+            raise ArgumentError, "timeout must be > 0" unless per_route_timeout.is_a?(Numeric) && per_route_timeout > 0
+            raise ArgumentError, "timeout exceeds MAX_TIMEOUT (#{MAX_TIMEOUT}s)" if per_route_timeout > MAX_TIMEOUT
+          end
+
+          normalized = normalize_pattern(pattern)
+          regex, param_names = compile_pattern(normalized)
+          routes << Route.new(
+            method:      verb,
+            pattern:     normalized,
+            regex:       regex,
+            param_names: param_names,
+            block:       block,
+            options:     opts.dup
+          )
+        end
+      end
+
+      def normalize_pattern(pattern)
+        pattern = pattern.to_s
+        pattern = "/#{pattern}" unless pattern.start_with?("/")
+        pattern = pattern.chomp("/")
+        pattern.empty? ? "/" : pattern
+      end
+
+      def compile_pattern(pattern)
+        param_names = []
+        regex_str = pattern.gsub(%r{:([a-zA-Z_][a-zA-Z0-9_]*)}) do |_match|
+          param_names << Regexp.last_match(1).to_sym
+          "([^/]+)"
+        end
+        [Regexp.new("\\A#{regex_str}\\z"), param_names]
+      end
+    end
+
+    attr_reader :req, :res, :route, :params
+
+    def initialize(req:, res:, route:, params:, http_server:)
+      @req         = req
+      @res         = res
+      @route       = route
+      @params      = params
+      @http_server = http_server
+    end
+
+    def invoke
+      instance_exec(&route.block)
+    end
+
+    # ---- handler context (white-listed access to host process) ----
+
+    def json(*args, **kwargs)
+      if args.empty?
+        # Treat kwargs as the body: json(foo: 1, bar: 2)
+        # For non-200 status, pass an explicit hash: json({foo: 1}, status: 422)
+        raise Halt.new(200, JSON.generate(kwargs), "application/json; charset=utf-8")
+      elsif args.size == 1
+        status = kwargs[:status] || 200
+        raise Halt.new(status, JSON.generate(args[0]), "application/json; charset=utf-8")
+      else
+        raise ArgumentError, "json: expected (hash) or (key: value, ...)"
+      end
+    end
+
+    def text(str, status: 200)
+      raise Halt.new(status, str.to_s, "text/plain; charset=utf-8")
+    end
+
+    def error!(message, status: 400, **extra)
+      payload = { error: message.to_s }
+      payload.merge!(extra) unless extra.empty?
+      raise Halt.new(status, JSON.generate(payload), "application/json; charset=utf-8")
+    end
+
+    def json_body
+      @json_body ||= begin
+        return {} if req.body.nil? || req.body.empty?
+        JSON.parse(req.body)
+      rescue JSON::ParserError
+        {}
+      end
+    end
+
+    def query
+      @query ||= req.query || {}
+    end
+
+    def data_path(*parts)
+      base = File.join(self.class.ext_dir, "data")
+      FileUtils.mkdir_p(base)
+      File.join(base, *parts.map(&:to_s))
+    end
+
+    def ext_dir
+      self.class.ext_dir
+    end
+
+    def ext_id
+      self.class.ext_id
+    end
+
+    def config
+      self.class.meta["config"] || {}
+    end
+
+    def session_manager
+      @http_server&.instance_variable_get(:@session_manager)
+    end
+
+    def agent_config
+      @http_server&.instance_variable_get(:@agent_config)
+    end
+
+    def server_start_time
+      @http_server&.instance_variable_get(:@start_time)
+    end
+
+    def logger
+      @logger ||= ScopedLogger.new(self.class.ext_id)
+    end
+
+    # Lightweight wrapper that prefixes log lines with the extension id.
+    class ScopedLogger
+      def initialize(ext_id)
+        @prefix = "[api_ext:#{ext_id}]"
+      end
+
+      %i[debug info warn error].each do |level|
+        define_method(level) do |msg|
+          Clacky::Logger.public_send(level, "#{@prefix} #{msg}")
+        end
+      end
+    end
+  end
+end

data/lib/clacky/api_extension_loader.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Clacky
+  # Discovers and loads user-defined HTTP API extensions from
+  # ~/.clacky/api_ext/<name>/handler.rb. Each handler is expected to define a
+  # subclass of Clacky::ApiExtension; the subclass is auto-registered with the
+  # framework and its routes become available under /api/ext/<name>/.
+  #
+  # A broken extension (syntax error, missing base class, route conflict) is
+  # isolated: skipped with a logged warning, never aborts the load of others.
+  module ApiExtensionLoader
+    DEFAULT_DIR  = File.expand_path("~/.clacky/api_ext")
+    DISABLED_DIR = "_disabled"
+
+    Result = Struct.new(:loaded, :skipped, keyword_init: true)
+
+    class << self
+      def load_all(dir: DEFAULT_DIR)
+        result = Result.new(loaded: [], skipped: [])
+        Clacky::ApiExtension.reset_registry!
+
+        if Dir.exist?(dir)
+          Dir.glob(File.join(dir, "*", "handler.rb")).sort.each do |handler_path|
+            ext_dir = File.dirname(handler_path)
+            ext_id  = File.basename(ext_dir)
+            next if ext_id == DISABLED_DIR || ext_id.start_with?("_")
+            load_one(ext_id, ext_dir, handler_path, result)
+          end
+        end
+
+        @last_result = result
+        log_summary(result)
+        result
+      end
+
+      def last_result
+        @last_result || load_all
+      end
+
+      def load_one(ext_id, ext_dir, handler_path, result)
+        meta = read_meta(ext_dir)
+        before = Clacky::ApiExtension.pending_subclasses.size
+
+        require handler_path
+
+        new_subclasses = Clacky::ApiExtension.pending_subclasses[before..] || []
+        klass = new_subclasses.last
+
+        unless klass
+          result.skipped << [ext_id, "no Clacky::ApiExtension subclass defined in handler.rb"]
+          log_skip(ext_id, result.skipped.last[1])
+          return
+        end
+
+        klass.ext_id  = ext_id
+        klass.ext_dir = ext_dir
+        klass.meta    = meta
+
+        if klass.routes.empty?
+          result.skipped << [ext_id, "no routes declared (use get/post/... DSL)"]
+          log_skip(ext_id, result.skipped.last[1])
+          Clacky::ApiExtension.registry.delete(ext_id)
+          return
+        end
+
+        if (gap = validate_public_endpoints(klass, meta))
+          result.skipped << [ext_id, gap]
+          log_skip(ext_id, gap)
+          return
+        end
+
+        Clacky::ApiExtension.register(ext_id, klass)
+        result.loaded << ext_id
+        public_count = klass.public_paths.size
+        suffix = public_count > 0 ? " (#{public_count} public)" : ""
+        Clacky::Logger.info("[ApiExtensionLoader] Loaded '#{ext_id}' — #{klass.routes.size} route(s)#{suffix}")
+      rescue StandardError, ScriptError => e
+        result.skipped << [ext_id, e.message]
+        log_skip(ext_id, e.message)
+      end
+
+      private def read_meta(ext_dir)
+        path = File.join(ext_dir, "meta.yml")
+        return {} unless File.exist?(path)
+
+        YAMLCompat.load_file(path) || {}
+      rescue StandardError => e
+        Clacky::Logger.warn("[ApiExtensionLoader] Failed to read meta.yml in #{ext_dir}: #{e.message}")
+        {}
+      end
+
+      private def validate_public_endpoints(klass, meta)
+        return nil if klass.public_paths.empty?
+        return nil if meta["public"] == true
+
+        "uses public_endpoint but meta.yml is missing 'public: true'"
+      end
+
+      private def log_skip(ext_id, reason)
+        Clacky::Logger.warn("[ApiExtensionLoader] Skipped '#{ext_id}': #{reason}")
+      end
+
+      private def log_summary(result)
+        return if result.loaded.empty? && result.skipped.empty?
+
+        total_routes = result.loaded.sum { |id| Clacky::ApiExtension.registry[id]&.routes&.size || 0 }
+        Clacky::Logger.info("[ApiExtensionLoader] #{result.loaded.size} extension(s), #{total_routes} route(s); #{result.skipped.size} skipped")
+      end
+
+      # Generate a starter handler.rb at ~/.clacky/api_ext/<name>/handler.rb.
+      # Returns the path to the generated file.
+      def scaffold(name, dir: DEFAULT_DIR)
+        slug = name.to_s.strip.downcase.gsub(/[^a-z0-9_-]+/, "-").gsub(/\A-+|-+\z/, "")
+        raise ArgumentError, "invalid api_ext name: #{name.inspect}" if slug.empty?
+
+        target_dir = File.join(dir, slug)
+        path = File.join(target_dir, "handler.rb")
+        raise ArgumentError, "api_ext already exists: #{path}" if File.exist?(path)
+
+        FileUtils.mkdir_p(target_dir)
+        File.write(path, skeleton(slug))
+        path
+      end
+
+      private def skeleton(slug)
+        const = slug.split(/[-_]/).map(&:capitalize).join + "Ext"
+        <<~RUBY
+          # frozen_string_literal: true
+
+          # Custom HTTP API extension mounted at /api/ext/#{slug}/
+          # Scaffolded by `clacky api_ext_new #{slug}` — fill in the routes you need.
+          class #{const} < Clacky::ApiExtension
+            get "/hello" do
+              json(message: "hello from #{slug}")
+            end
+
+            # Examples — uncomment and adapt:
+            #
+            # post "/items" do
+            #   body = json_body
+            #   error!("name required", status: 422) unless body["name"]
+            #   File.write(data_path("items.json"), body.to_json)
+            #   json(ok: true)
+            # end
+            #
+            # get "/items/:id" do
+            #   json(id: params[:id])
+            # end
+          end
+        RUBY
+      end
+    end
+  end
+end

data/lib/clacky/cli.rb

@@ -268,8 +268,9 @@ module Clacky
           config.save
         end
 
-        # Refresh UI bar
+        # Refresh UI bar and model list
         ui_controller.config[:model] = config.model_name
+        ui_controller.available_models = config.model_names
         ui_controller.update_sessionbar(
           tasks: agent.total_tasks,
           cost: agent.total_cost
@@ -836,11 +837,12 @@ module Clacky
             say "Error: Rich UI requires Ruby >= 2.6. Use --ui ui2 on Ruby #{RUBY_VERSION}.", :red
             exit 1
           end
-          require_relative "rich_ui_controller"
+          require_relative "rich_ui"
           RichUIController.new(
             working_dir: working_dir,
             mode: agent_config.permission_mode.to_s,
             model: agent_config.model_name,
+            model_names: agent_config.model_names,
             theme: options[:theme]
           )
         else
@@ -901,6 +903,21 @@ module Clacky
           agent_config.permission_mode = new_mode.to_sym
         end
 
+        # Set up model switch handler (from /model slash command)
+        ui_controller.on_model_switch do |model, persist|
+          next unless agent_config.switch_model_by_name(model)
+
+          id = agent_config.current_model_id
+          agent.switch_model_by_id(id)
+          if persist
+            agent_config.set_default_model_by_id(id)
+            agent_config.save
+            ui_controller.show_success("Model switched to #{model} (saved)")
+          else
+            ui_controller.show_success("Model switched to #{model} (session only)")
+          end
+        end
+
         # Set up time machine handler (ESC key)
         ui_controller.on_time_machine do
           handle_time_machine_command(ui_controller, agent, session_manager)
@@ -921,6 +938,16 @@ module Clacky
           end
 
           if (not current_task_thread&.alive?) && input_was_empty
+            # Rich UI: require double-tap Ctrl+C to exit.  When the user
+            # just copied terminal-native text selection, the viewport
+            # has no knowledge of the selection, yet Ctrl+C must not exit.
+            # First press only sets the warning; second press exits.
+            if ui_controller.respond_to?(:ctrl_c_warning) && !ui_controller.ctrl_c_warning
+              ui_controller.instance_variable_set(:@ctrl_c_warning, "Press Ctrl+C again to exit")
+              ui_controller.set_input_tips("Press Ctrl+C again to exit.", type: :info)
+              next
+            end
+
             # Save final session state before exit
             if session_manager && agent.total_tasks > 0
               session_data = agent.to_session_data(status: :exited)
@@ -1038,7 +1065,13 @@ module Clacky
               # Update session bar with agent's cumulative stats
               ui_controller.update_sessionbar(tasks: agent.total_tasks, cost: agent.total_cost)
             rescue Clacky::AgentInterrupted, StandardError => e
-              handle_agent_exception(ui_controller, agent, session_manager, e)
+              begin
+                handle_agent_exception(ui_controller, agent, session_manager, e)
+              rescue StandardError => ex
+                # If handle_agent_exception itself raises (e.g. UI in bad state),
+                # prevent the thread from dying with an unhandled exception.
+                $stderr.puts "[cli] handle_agent_exception failed: #{ex.class}: #{ex.message}"
+              end
             ensure
               current_task_thread = nil
               # Start idle timer after agent completes
@@ -1181,6 +1214,63 @@ module Clacky
       exit 1 if result.skipped.any?
     end
 
+    desc "api_ext_new NAME", "Scaffold a custom HTTP API extension at ~/.clacky/api_ext/NAME/"
+    long_desc <<-LONGDESC
+      Generate a ready-to-edit HTTP API extension skeleton. The skeleton mounts
+      a sample route under /api/ext/NAME/ — fill in your routes, then verify with
+      `clacky api_ext_verify`.
+
+      Examples:
+        $ clacky api_ext_new my-dashboard
+    LONGDESC
+    def api_ext_new(name)
+      path = Clacky::ApiExtensionLoader.scaffold(name)
+      puts "Created api extension: #{path}"
+      puts "Edit the routes, then run: clacky api_ext_verify"
+    rescue ArgumentError => e
+      warn "Error: #{e.message}"
+      exit 1
+    end
+
+    desc "api_ext_verify", "Load user API extensions and report which are valid"
+    def api_ext_verify
+      result = Clacky::ApiExtensionLoader.load_all
+
+      if result.loaded.empty? && result.skipped.empty?
+        puts "No api extensions found in ~/.clacky/api_ext/"
+        return
+      end
+
+      result.loaded.each do |id|
+        klass = Clacky::ApiExtension.registry[id]
+        public_count = klass.public_paths.size
+        suffix = public_count > 0 ? " (#{public_count} public)" : ""
+        puts "[OK]   #{id} — #{klass.routes.size} route(s)#{suffix}"
+      end
+      result.skipped.each { |(n, reason)| puts "[SKIP] #{n} — #{reason}" }
+      exit 1 if result.skipped.any?
+    end
+
+    desc "api_ext_list", "List loaded API extensions and their routes"
+    def api_ext_list
+      Clacky::ApiExtensionLoader.load_all if Clacky::ApiExtension.registry.empty?
+
+      if Clacky::ApiExtension.registry.empty?
+        puts "No api extensions loaded."
+        return
+      end
+
+      Clacky::ApiExtension.registry.each do |id, klass|
+        public_tag = klass.public_paths.any? ? " (public)" : ""
+        puts "#{id}#{public_tag}"
+        klass.routes.each do |route|
+          full_path = "/api/ext/#{id}#{route.pattern}".chomp("/")
+          full_path = "/api/ext/#{id}/" if full_path == "/api/ext/#{id}"
+          puts "  #{route.method.to_s.upcase.ljust(6)} #{full_path}"
+        end
+      end
+    end
+
     desc "billing", "Show billing summary and usage statistics"
     long_desc <<-LONGDESC
       Display billing summary with token usage and cost breakdown.

data/lib/clacky/client.rb

@@ -515,6 +515,12 @@ module Clacky
       end
     end
 
+    def reset_connections!
+      @bedrock_connection = nil
+      @openai_connection = nil
+      @anthropic_connection = nil
+    end
+
     def bedrock_connection
       current_epoch = Clacky::ProxyConfig.epoch
       if @bedrock_connection.nil? ||
@@ -598,11 +604,24 @@ module Clacky
       return { success: true, status: response.status } if response.status == 200
 
       error_body = JSON.parse(response.body) rescue nil
+      error_code = extract_error_code(error_body)
+
+      translated = case response.status
+      when 402       then I18n.t("llm.error.insufficient_credit")
+      when 400       then I18n.t("llm.error.rate_limit_400")
+      when 401       then I18n.t("llm.error.invalid_api_key")
+      when 403       then I18n.t("llm.error.403.#{error_code || "default"}")
+      when 404       then I18n.t("llm.error.endpoint_not_found")
+      when 429       then I18n.t("llm.error.rate_limit_429")
+      when 500..599  then I18n.t("llm.error.server_error", status: response.status)
+      else                extract_error_message(error_body, response.body)
+      end
+
       {
         success:    false,
         status:     response.status,
-        error:      extract_error_message(error_body, response.body),
-        error_code: extract_error_code(error_body)
+        error:      translated,
+        error_code: error_code
       }
     end
 
@@ -620,7 +639,7 @@ module Clacky
 
       if error_code == "insufficient_credit" || response.status == 402
         raise InsufficientCreditError.new(
-          "[LLM] Insufficient credit: #{error_message}",
+          "[LLM] #{I18n.t("llm.error.insufficient_credit")}",
           error_code: "insufficient_credit",
           provider_id: @provider_id
         )
@@ -632,19 +651,25 @@ module Clacky
         # However, some proxy/relay providers do — so we inspect the message first.
         # Also, Bedrock returns ThrottlingException as 400 instead of 429.
         if error_message.match?(/ThrottlingException|unavailable|quota/i)
-          hint = error_message.match?(/quota/i) ? " (possibly out of credits)" : ""
-          raise RetryableError, "[LLM] Rate limit or service issue: #{error_message}#{hint}"
+          raise RetryableError, "[LLM] #{I18n.t("llm.error.rate_limit_400")}"
         end
 
         # True bad request — our message was malformed. Roll back history so the
         # broken message is not replayed on the next user turn.
-        raise BadRequestError, "[LLM] Client request error: #{error_message}"
-      when 401 then raise AgentError, "[LLM] Invalid API key"
-      when 403 then raise AgentError, "[LLM] Access denied: #{error_message}"
-      when 404 then raise AgentError, "[LLM] API endpoint not found: #{error_message}"
-      when 429 then raise RetryableError, "[LLM] Rate limit exceeded, please wait a moment"
-      when 500..599 then raise RetryableError, "[LLM] Service temporarily unavailable (#{response.status}), retrying..."
-      else raise AgentError, "[LLM] Unexpected error (#{response.status}): #{error_message}"
+        raise BadRequestError.new(
+          "[LLM] Client request error: #{error_message}",
+          display_message: "[LLM] #{I18n.t("llm.error.bad_request")}"
+        )
+      when 401 then raise AgentError, "[LLM] #{I18n.t("llm.error.invalid_api_key")}"
+      when 403
+        i18n_key = "llm.error.403.#{error_code}"
+        translated = I18n.t(i18n_key)
+        translated = I18n.t("llm.error.403.default") if translated == i18n_key
+        raise AgentError, "[LLM] #{translated}"
+      when 404 then raise AgentError, "[LLM] #{I18n.t("llm.error.endpoint_not_found")}"
+      when 429 then raise RetryableError, "[LLM] #{I18n.t("llm.error.rate_limit_429")}"
+      when 500..599 then raise RetryableError, "[LLM] #{I18n.t("llm.error.server_error", status: response.status)}"
+      else raise AgentError, "[LLM] #{I18n.t("llm.error.unexpected", status: response.status)}"
       end
     end
 
@@ -652,7 +677,7 @@ module Clacky
     def check_html_response(response)
       body = response.body.to_s.lstrip
       if body.start_with?("<!DOCTYPE", "<!doctype", "<html", "<HTML")
-        raise RetryableError, "[LLM] Service temporarily unavailable (received HTML error page), retrying..."
+        raise RetryableError, "[LLM] #{I18n.t("llm.error.html_response")}"
       end
     end
 

data/lib/clacky/default_agents/_panels/git/panel.js

@@ -196,6 +196,6 @@
   }, {
     panel: "git",
     order: 10,
-    tab: { id: "changes", label: (typeof I18n !== "undefined" ? (I18n.t("changes.tab") !== "changes.tab" ? I18n.t("changes.tab") : "Git 管理") : "Git 管理") },
+    tab: { id: "changes", label: () => t("changes.tab") },
   });
 })();

data/lib/clacky/default_agents/_panels/time_machine/panel.js

@@ -635,6 +635,6 @@
   }, {
     panel: "time_machine",
     order: 20,
-    tab: { id: "tm", label: t("tm.tab", "时光机") },
+    tab: { id: "tm", label: () => t("tm.tab") },
   });
 })();