openclacky 1.2.10 → 1.2.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b32940868f1d61791afd615ff73dbaf72dc80c111f9f9435ef939ef39ae5dec
-  data.tar.gz: be8efa7ee318c3f174ddbbdf1f5b2754705eb6a5d3f263aa11cbe5539b198e8f
+  metadata.gz: 451817565cffdf7b1efcdf5e741cea76af0451a8d9900804e2aa3c6a5384ba4a
+  data.tar.gz: 0232ede01332162004abc1638a8a03b41095c44c68198ce6327e5f5fc815f49a
 SHA512:
-  metadata.gz: abcbed799ca8feed1a41e39a72bd8e6a5e9184c8e76a67bac79f9bee07f88ebf6b639102d6cfcd6527bf80b7b3c9bda5665f131bf81a164b9a14b963cad1ea47
-  data.tar.gz: 829bc77c06483853c1d568d04a528a9611c6e7f775b38b6c6fdebe04c5a5ae6974328bb1ac9c0f8cb1afe0765a60795061157b65860eaf26e8bb7368dadb2b8e
+  metadata.gz: 3a88a963b238a35fc25d5791b752981179290a88b27d176285647668711b91360a1d4c656677536fda84d18d0fa05fe67ad8364bdf0f7dbbba0a31a007156cbd
+  data.tar.gz: 124b77cbeec34494c8d35d58f1735459ba50da7c112a13a35c8038bbe89ee81412cf60107f4f926ad870efbbf65621b369f4bb5f1de67b477032b14dbad338d3

data/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.12] - 2026-06-05
+
+### Fixed
+- Remove ruby_rich C extension dependency that caused installation failures
+
+## [1.2.11] - 2026-06-05
+
+### Added
+- Logo branding in sidebar footer with link to official website
+- Onboarding charge tips for new users to understand billing
+- WebUI tool panel expand/collapse toggle for better space management
+- Region parameter for CDN and install script switching (CN vs global)
+- Automated Feishu app creation via OAuth device flow — no more manual App ID/Secret entry
+- Feishu group chat history with sender name identification
+- Cron job entry sorting by enabled status and running state indicator
+- Quick switch model selector: show only active model name in card, rename sub-model
+- API server now binds to non-local IP by default for LAN access
+
+### Improved
+- Sequential image generation now shows tips when generation is slow
+- Startup time reduced significantly
+- Clear GEM_HOME during Ruby 3 installation to avoid gem conflicts
+
+### Fixed
+- Uninstall crashes when brand.yml has no product_name configured
+- Tool calls go stale after channel interrupt, causing silent failures
+- Sanitize tool names to prevent invalid characters
+- Completion summary now accumulates correctly across supplementary message relays
+- WSL install exit code 2 (network unreachable) now propagates properly
+- Recycled sessions now sorted by deletion time instead of creation time
+- Idle status now updates correctly after server restart
+
 ## [1.2.10] - 2026-06-03
 
 ### Added
@@ -14,7 +46,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - WSL network connectivity pre-check before installation
 - MiniMax M3 provider with vision support and pricing
 - One-click exchange rate update in settings
-- Rich TUI controller for terminal interaction
+- Rich TUI controller (experimental, enable with `--ui rich`) for terminal interaction
 
 ### Improved
 - WebUI working directory selector UX

data/lib/clacky/agent/session_serializer.rb

@@ -266,7 +266,7 @@ module Clacky
 
         page.each do |round|
           msg = round[:user_msg]
-          raw_text    = extract_text_from_content(msg[:content])
+          raw_text    = msg[:display_text] || extract_text_from_content(msg[:content])
           # Images: recovered from inline image_url blocks in content (carry data_url for <img> rendering)
           image_files = extract_image_files_from_content(msg[:content])
           # Disk files (PDF, doc, etc.): stored in display_files on the user message at send time

data/lib/clacky/agent/tool_registry.rb

@@ -88,6 +88,9 @@ module Clacky
     #   3. Alias lookup (e.g. "read_file" → "file_reader")
     # Returns the canonical tool name, or nil if nothing matched.
     def resolve(name)
+      return nil if name.nil?
+
+      name = sanitize_name(name)
       return name if @tools.key?(name)
 
       downcased = name.downcase
@@ -139,5 +142,12 @@ module Clacky
     def by_category(category)
       @tools.values.select { |tool| tool.category == category }
     end
+
+    private def sanitize_name(name)
+      cleaned = name.to_s
+      cleaned = cleaned.split(/<\|/, 2).first.to_s
+      cleaned = cleaned.split(/[\s,;|]/, 2).first.to_s
+      cleaned.strip
+    end
   end
 end

data/lib/clacky/agent.rb

@@ -104,6 +104,7 @@ module Clacky
       @pending_injections = []     # Pending inline skill injections to flush after observe()
       @pending_script_tmpdirs = [] # Decrypted-script tmpdirs to shred when agent.run completes
       @pending_error_rollback = false  # Deferred rollback flag set by restore_session on error
+      @last_run_interrupted = false    # Set when run() exits via AgentInterrupted; tells the next run() to keep the task-start snapshot (continuation of the same task across a relay, not a brand-new task)
 
       # Compression tracking
       @compression_level = 0  # Tracks how many times we've compressed (for progressive summarization)
@@ -251,7 +252,7 @@ module Clacky
       @name = new_name.to_s.strip
     end
 
-    def run(user_input, files: [])
+    def run(user_input, files: [], display_text: nil)
       # Show the "thinking" indicator as early as possible so the user gets
       # immediate feedback after sending a message. Without this the UI stays
       # silent during synchronous setup work (system prompt assembly, file
@@ -263,24 +264,33 @@ module Clacky
       # Start new task for Time Machine
       task_id = start_new_task
 
-      @start_time = Time.now
-      @task_truncation_count = 0  # Reset truncation counter for each task
-      @task_timeout_hint_injected = false  # Reset read-timeout hint injection (see LlmCaller)
-      @task_upstream_truncation_hint_injected = false  # Reset upstream-truncation hint injection (see LlmCaller)
-      @task_cost_source = :estimated  # Reset for new task
-      # Note: Do NOT reset @previous_total_tokens here - it should maintain the value from the last iteration
-      # across tasks to correctly calculate delta tokens in each iteration
-      @task_start_iterations = @iterations  # Track starting iterations for this task
-      @task_start_cost = @total_cost  # Track starting cost for this task
-      # Track cache stats for current task
-      @task_cache_stats = {
-        cache_creation_input_tokens: 0,
-        cache_read_input_tokens: 0,
-        prompt_tokens: 0,
-        completion_tokens: 0,
-        total_requests: 0,
-        cache_hit_requests: 0
-      }
+      # Continuation of a previously-interrupted task (e.g. user sent a
+      # supplementary message without stopping the running task) keeps the
+      # existing task-start snapshot so the completion summary accumulates
+      # iterations/cost/duration across the relay, instead of resetting and
+      # only counting the post-interrupt portion.
+      if @last_run_interrupted
+        @last_run_interrupted = false
+      else
+        @start_time = Time.now
+        @task_truncation_count = 0  # Reset truncation counter for each task
+        @task_timeout_hint_injected = false  # Reset read-timeout hint injection (see LlmCaller)
+        @task_upstream_truncation_hint_injected = false  # Reset upstream-truncation hint injection (see LlmCaller)
+        @task_cost_source = :estimated  # Reset for new task
+        # Note: Do NOT reset @previous_total_tokens here - it should maintain the value from the last iteration
+        # across tasks to correctly calculate delta tokens in each iteration
+        @task_start_iterations = @iterations  # Track starting iterations for this task
+        @task_start_cost = @total_cost  # Track starting cost for this task
+        # Track cache stats for current task
+        @task_cache_stats = {
+          cache_creation_input_tokens: 0,
+          cache_read_input_tokens: 0,
+          prompt_tokens: 0,
+          completion_tokens: 0,
+          total_requests: 0,
+          cache_hit_requests: 0
+        }
+      end
 
       # Deferred error rollback: if the previous session ended with an error,
       # trim history back to just before that failed user message now — at the
@@ -348,6 +358,7 @@ module Clacky
       end
 
       @history.append({ role: "user", content: user_content, task_id: task_id, created_at: Time.now.to_f,
+                        display_text: display_text,
                         display_files: display_files.empty? ? nil : display_files })
       @total_tasks += 1
 
@@ -477,14 +488,34 @@ module Clacky
           # truncation pattern, we still won't silently exit while the model
           # is mid-tool_call.
           if response[:tool_calls].nil? || response[:tool_calls].empty?
-            # [DIAG] Pin down exactly which sub-condition triggered the task exit.
+            content_str = response[:content].to_s
+            stripped = content_str.strip
+            ends_with_question = stripped.end_with?("?", "？")
+            finish_reason_str = response[:finish_reason].to_s
+            completion_tokens = response.dig(:token_usage, :completion_tokens)
+
             Clacky::Logger.info("agent.loop_break_normal",
               session_id: @session_id,
               iteration: @iterations,
               branch: (response[:tool_calls].nil? ? "tool_calls_nil" : "tool_calls_empty"),
-              finish_reason: response[:finish_reason].to_s,
-              tool_calls_count: (response[:tool_calls] || []).size
+              finish_reason: finish_reason_str,
+              tool_calls_count: (response[:tool_calls] || []).size,
+              completion_tokens: completion_tokens,
+              max_tokens: @config.max_tokens,
+              content_len: content_str.length,
+              content_ends_with_question: ends_with_question
             )
+
+            if finish_reason_str == "length"
+              Clacky::Logger.warn("agent.loop_break_on_length",
+                session_id: @session_id,
+                iteration: @iterations,
+                completion_tokens: completion_tokens,
+                max_tokens: @config.max_tokens,
+                content_len: content_str.length,
+                content_tail: content_str[-200, 200]
+              )
+            end
             if response[:content] && !response[:content].empty?
               emit_assistant_message(response[:content], reasoning_content: response[:reasoning_content])
             end
@@ -595,6 +626,11 @@ module Clacky
         @hooks.trigger(:on_complete, result)
         result
       rescue Clacky::AgentInterrupted
+        # Mark this run as interrupted so the next run() (e.g. user's
+        # supplementary message during a running task) keeps the existing
+        # task-start snapshot — the completion summary should reflect the
+        # entire task across the relay, not just the post-interrupt portion.
+        @last_run_interrupted = true
         # Let CLI handle the interrupt message
         raise
       rescue StandardError => e
@@ -808,6 +844,7 @@ module Clacky
       # reasoning_content so every outgoing payload satisfies the provider's
       # "reasoning_content must be passed back" contract.
       msg[:reasoning_content] = response[:reasoning_content] if response[:reasoning_content]
+      check_stale!
       @history.append(msg)
 
       # Close the thinking spinner before returning. The caller (run loop)

data/lib/clacky/anthropic_stream_aggregator.rb

@@ -19,9 +19,16 @@ module Clacky
       @usage = {}
       @last_input_tokens = 0
       @last_output_tokens = 0
+      @parse_failures = 0
+      @frames_seen = 0
+      @bytes_seen = 0
     end
 
+    attr_reader :parse_failures, :frames_seen, :bytes_seen
+
     def handle(event, data_str)
+      @bytes_seen += data_str.to_s.bytesize
+      @frames_seen += 1
       data = parse_or_nil(data_str)
       return unless data
 
@@ -99,7 +106,16 @@ module Clacky
 
     private def parse_or_nil(s)
       JSON.parse(s)
-    rescue JSON::ParserError
+    rescue JSON::ParserError => e
+      @parse_failures += 1
+      if @parse_failures == 1
+        Clacky::Logger.warn("stream.parse_failure",
+          provider: "anthropic",
+          error: "#{e.class}: #{e.message}",
+          frame_head: s.to_s[0, 200],
+          frame_bytes: s.to_s.bytesize
+        )
+      end
       nil
     end
 

data/lib/clacky/bedrock_stream_aggregator.rb

@@ -29,9 +29,16 @@ module Clacky
       @usage = {}
       @last_input_tokens = 0
       @last_output_tokens = 0
+      @parse_failures = 0
+      @frames_seen = 0
+      @bytes_seen = 0
     end
 
+    attr_reader :parse_failures, :frames_seen, :bytes_seen
+
     def handle(event, data_str)
+      @bytes_seen += data_str.to_s.bytesize
+      @frames_seen += 1
       data = parse_or_nil(data_str)
       return unless data
 
@@ -101,7 +108,16 @@ module Clacky
 
     private def parse_or_nil(s)
       JSON.parse(s)
-    rescue JSON::ParserError
+    rescue JSON::ParserError => e
+      @parse_failures += 1
+      if @parse_failures == 1
+        Clacky::Logger.warn("stream.parse_failure",
+          provider: "bedrock",
+          error: "#{e.class}: #{e.message}",
+          frame_head: s.to_s[0, 200],
+          frame_bytes: s.to_s.bytesize
+        )
+      end
       nil
     end
 

data/lib/clacky/client.rb

@@ -260,6 +260,7 @@ module Clacky
       end
 
       result = aggregator.to_h
+      log_stream_summary("bedrock", aggregator, result["stopReason"])
       # A complete Converse stream always emits stopReason in its messageStop
       # frame. Its absence means the upstream cut the stream mid-response,
       # leaving a half-written message; retry rather than accept the truncation.
@@ -318,6 +319,7 @@ module Clacky
       end
 
       result = aggregator.to_h
+      log_stream_summary("anthropic", aggregator, result["stop_reason"])
       # A complete Messages stream always emits stop_reason in its message_delta
       # frame. Its absence means the upstream cut the stream mid-response,
       # leaving a half-written message; retry rather than accept the truncation.
@@ -380,6 +382,7 @@ module Clacky
       end
 
       result = aggregator.to_h
+      log_stream_summary("openai", aggregator, result.dig("choices", 0, "finish_reason"))
       # A complete chat-completion stream always terminates with a frame
       # carrying finish_reason. Its absence means the upstream cut the stream
       # mid-response (e.g. proxy idle-timeout, connection reset that Faraday
@@ -462,6 +465,24 @@ module Clacky
       "/model/#{model}/converse-stream"
     end
 
+    # Emit a one-line summary of a streaming response when something looks
+    # off (parse failures, missing terminal frame). No-op on the happy path
+    # to keep logs quiet.
+    private def log_stream_summary(provider, aggregator, terminal_marker)
+      parse_failures = aggregator.respond_to?(:parse_failures) ? aggregator.parse_failures.to_i : 0
+      missing_terminal = terminal_marker.nil?
+      return if parse_failures.zero? && !missing_terminal
+
+      Clacky::Logger.warn("stream.summary",
+        provider: provider,
+        frames_seen: aggregator.respond_to?(:frames_seen) ? aggregator.frames_seen : nil,
+        bytes_seen: aggregator.respond_to?(:bytes_seen) ? aggregator.bytes_seen : nil,
+        parse_failures: parse_failures,
+        saw_done: aggregator.respond_to?(:saw_done?) ? aggregator.saw_done? : nil,
+        terminal_marker_present: !missing_terminal
+      )
+    end
+
     # Pull complete SSE frames out of a buffer and yield them as (event, data).
     # An SSE frame ends at a blank line ("\n\n"); incomplete trailing data
     # stays in the buffer for the next chunk. Frames without an explicit
@@ -565,9 +586,10 @@ module Clacky
 
       error_body = JSON.parse(response.body) rescue nil
       {
-        success: false,
-        status:  response.status,
-        error:   extract_error_message(error_body, response.body)
+        success:    false,
+        status:     response.status,
+        error:      extract_error_message(error_body, response.body),
+        error_code: extract_error_code(error_body)
       }
     end
 

data/lib/clacky/default_skills/channel-manager/SKILL.md

@@ -99,90 +99,95 @@ Ask:
 
 ### Feishu setup
 
-Feishu now offers a one-click **Agent App** (智能体应用) that auto-configures all
-required permissions, events, and publishing for you — no Bot capability toggle,
-no permission JSON, no event subscription, no version/release steps. Just create
-the app and copy the credentials. The connection mode is unchanged (long
-connection / WebSocket), handled entirely by the server.
+Use the setup script to create the Feishu app automatically via OAuth 2.0 Device Authorization Grant.
+The user only needs to scan a QR code once.
 
-#### Step 1 — Open the Agent App creation page
+#### Step 1 — Run setup script as a background session
 
-1. Navigate: `open https://open.feishu.cn/page/launcher?from=backend_oneclick`. Pass `isolated: true`. If the browser is not configured (the `open` call fails), just give the user the URL and ask them to open it manually in any browser — the rest of the flow is fully manual and does not need browser automation.
-2. If a login page or QR code is shown, tell the user to scan/log in and wait for "done".
+```
+terminal(command: "ruby SKILL_DIR/feishu_setup.rb", background: true)
+```
 
-#### Step 2 — Create the Agent App
+Keep polling the session. The script will print:
+- `SCAN_URL:<url>` — the QR code URL
+- `EXPIRE_IN:<seconds>` — how long the URL is valid
 
-3. After login, the page lands on **创建飞书智能体应用 (Create Feishu Agent App)**.
-   Guide the user: "Enter an app name (e.g. Open Clacky), then click **立即创建 (Create Now)**. Reply done."
-   (The avatar is auto-assigned at random and can be changed anytime — it does not affect setup.)
-   Wait for "done".
+Once you see these lines, tell the user immediately:
+- zh: "请在飞书中打开以下链接（或扫码）完成授权，链接 <expire_in> 秒内有效：\n<url>"
+- en: "Open this link in Feishu (or scan the QR code) to authorize. Valid for <expire_in>s:\n<url>"
 
-#### Step 3 — Copy credentials
+Continue polling until the response contains an `exit_code`. When the session ends successfully, stdout will contain:
+- `APP_ID:<app_id>`
+- `APP_SECRET:<app_secret>`
 
-4. The page jumps to **创建成功 (Created Successfully)**, showing `App ID` and `App Secret`.
-   The Secret is masked by default. Guide the user: "Click the eye icon next to **App Secret** to reveal it,
-   then copy both values and paste here. Reply with: App ID: xxx, App Secret: xxx"
-   Wait for the reply. Parse `app_id` (starts with `cli_`) and `app_secret`. Trim whitespace and
-   make sure the two values are not swapped.
+Parse both values.
 
-#### Step 4 — Save credentials
+#### Step 2 — Save credentials
 
-5. Run:
-   ```bash
-   curl -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/feishu \
-     -H "Content-Type: application/json" \
-     -d '{"app_id":"<APP_ID>","app_secret":"<APP_SECRET>","domain":"https://open.feishu.cn"}'
-   ```
-   **CRITICAL: This curl call is the ONLY way to save credentials. NEVER write `~/.clacky/channels.yml`
-   or any file under `~/.clacky/channels/` directly. The server API handles persistence, hot-reload,
-   and establishing the long connection.**
+```bash
+curl -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/feishu \
+  -H "Content-Type: application/json" \
+  -d '{"app_id":"<APP_ID>","app_secret":"<APP_SECRET>","domain":"https://open.feishu.cn"}'
+```
+
+**CRITICAL: This curl call is the ONLY way to save credentials. NEVER write `~/.clacky/channels.yml`
+or any file under `~/.clacky/channels/` directly. The server API handles persistence, hot-reload,
+and establishing the long connection.**
+
+On success: tell the user the following (zh), then **continue to Step 3 (Feishu CLI)**:
 
-On success: tell the user "✅ Feishu channel configured!" and **continue to Step 5 (Feishu CLI)**.
+zh: "✅ 飞书通道已配置成功！现在你可以通过飞书与智能助手进行私聊和群聊，也支持阅读飞书文档。"
+en: "✅ Feishu channel configured! You can now chat with the assistant via Feishu DMs or group chats, and read Feishu Docs."
 
 ---
 
-#### Step 5 — Optional: install Feishu CLI
+#### Step 3 — Optional: install Feishu CLI
 
-Reach here after the channel is configured (Step 4 succeeded). Read `app_id` and `app_secret` from `~/.clacky/channels.yml` (under `channels.feishu`) for the install commands below.
+Reach here after the channel is configured (Step 2 succeeded). Read `app_id` and `app_secret` from `~/.clacky/channels.yml` (under `channels.feishu`) for the install commands below.
 
 Call `request_user_feedback`:
 
 zh:
 ```json
 {
-  \"question\": \"是否要安装「飞书 CLI」？装好之后 AI 可以帮你操作飞书云文档等能力。不装也 OK。\",
-  "options": ["启用", "跳过"]
+  \"question\": \"是否安装飞书 CLI？安装后将解锁更多飞书能力，例如创建、编辑、删除云文档。\",
+  "options": ["安装", "跳过"]
 }
 ```
 
 en:
 ```json
 {
-  "question": "Install Feishu CLI? With it, the AI can help you work with Feishu Docs and more. Skipping is fine.",
-  "options": ["Enable", "Skip"]
+  "question": "Install Feishu CLI? It unlocks more Feishu capabilities, such as creating, editing, and deleting Docs.",
+  "options": ["Install", "Skip"]
 }
 ```
 
 If the user picks Skip, stop — setup is complete.
 
-If the user picks Enable, run:
+If the user picks Enable, run the following **in order**:
 
+**Step 3a** — Install and configure (single terminal call):
 ```bash
 lark-cli --version > /dev/null 2>&1 || npm install -g @larksuite/cli
 echo -n "<APP_SECRET>" | lark-cli config init --app-id <APP_ID> --app-secret-stdin --brand feishu
 ruby "SKILL_DIR/install_feishu_skills.rb"
-lark-cli auth login --recommend
 ```
 
-The last command blocks up to 10 minutes waiting for browser authorization — make sure the runner's timeout is ≥ 600s.
+**Step 3b** — Start authorization as a background session:
+```
+terminal(command: "lark-cli auth login --recommend", background: true)
+```
+
+This returns a `session_id`. Keep polling with `terminal(session_id: <id>, input: "")` every few seconds.
 
-Once you see the authorization URL in the command's stdout, tell the user (do **not** wait for a reply — the CLI's blocking poll will return on its own when authorization completes):
+Once you see the authorization URL appear in the output, tell the user immediately (do **not** wait for their reply):
 - zh: "请在浏览器中打开下方链接完成授权：\n<URL>"
 - en: "Open this URL in your browser to authorize:\n<URL>"
 
-**Do not kill and restart this command** — restarting invalidates the device code and breaks the link the user already opened. The "hang" is just polling; wait it out.
+Continue polling until the response contains an `exit_code` (meaning the session has ended). **Do not kill the session** — restarting invalidates the device code.
 
-When `lark-cli auth login` returns successfully, tell the user:
+When the session ends with `exit_code: 0`, tell the user:
 - zh: "✅ 飞书 CLI 已就绪。"
 - en: "✅ Feishu CLI is ready."
 

data/lib/clacky/default_skills/channel-manager/feishu_setup.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module FeishuSetup
+  ENDPOINT            = "/oauth/v1/app/registration"
+  DEFAULT_DOMAIN      = "https://accounts.feishu.cn"
+  DEFAULT_LARK_DOMAIN = "https://accounts.larksuite.com"
+  SDK_NAME            = "ruby-sdk"
+
+  class SetupError < StandardError
+    attr_reader :code, :description
+    def initialize(code, description)
+      @code = code
+      @description = description
+      super("#{code}: #{description}")
+    end
+  end
+
+  class AppAccessDeniedError < SetupError; end
+  class AppExpiredError      < SetupError; end
+
+  def self.run(app_name: nil, app_desc: nil, on_qr_code:, on_status_change: nil,
+               domain: DEFAULT_DOMAIN, lark_domain: DEFAULT_LARK_DOMAIN)
+    base_url        = domain
+    domain_switched = false
+
+    init_res = post(base_url, action: "init")
+    methods  = init_res["supported_auth_methods"] || []
+    unless methods.include?("client_secret")
+      raise SetupError.new("unsupported_auth_method", "client_secret not supported")
+    end
+
+    begin_res = post(base_url,
+      action:            "begin",
+      archetype:         "PersonalAgent",
+      auth_method:       "client_secret",
+      request_user_info: "open_id"
+    )
+
+    device_code = begin_res["device_code"]
+    interval    = (begin_res["interval"] || 5).to_i
+    expire_in   = (begin_res["expires_in"] || 600).to_i
+    qr_url      = build_qr_url(begin_res["verification_uri_complete"], app_name: app_name, app_desc: app_desc)
+
+    on_qr_code.call(qr_url, expire_in)
+
+    deadline = Time.now + expire_in
+
+    loop do
+      raise AppExpiredError.new("expired_token", "polling timed out") if Time.now >= deadline
+
+      poll_res = post(base_url, action: "poll", device_code: device_code)
+
+      if poll_res["client_id"] && poll_res["client_secret"]
+        return { client_id: poll_res["client_id"], client_secret: poll_res["client_secret"] }
+      end
+
+      user_info = poll_res["user_info"] || {}
+      if user_info["tenant_brand"] == "lark" && !domain_switched
+        base_url        = lark_domain
+        domain_switched = true
+        on_status_change&.call("domain_switched")
+        next
+      end
+
+      case poll_res["error"]
+      when "authorization_pending"
+        on_status_change&.call("polling")
+        sleep interval
+      when "slow_down"
+        interval += 5
+        on_status_change&.call("slow_down")
+        sleep interval
+      when "access_denied"
+        raise AppAccessDeniedError.new("access_denied", poll_res["error_description"].to_s)
+      when "expired_token"
+        raise AppExpiredError.new("expired_token", poll_res["error_description"].to_s)
+      else
+        err = poll_res["error"].to_s
+        raise SetupError.new(err, poll_res["error_description"].to_s) unless err.empty?
+        sleep interval
+      end
+    end
+  end
+
+  private_class_method def self.post(base_url, params)
+    uri               = URI("#{base_url}#{ENDPOINT}")
+    http              = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl      = uri.scheme == "https"
+    http.open_timeout = 10
+    http.read_timeout = 30
+    req               = Net::HTTP::Post.new(uri.path, "Content-Type" => "application/x-www-form-urlencoded")
+    req.body          = URI.encode_www_form(params)
+    JSON.parse(http.request(req).body)
+  end
+
+  private_class_method def self.build_qr_url(uri_complete, app_name: nil, app_desc: nil)
+    uri              = URI.parse(uri_complete)
+    params           = URI.decode_www_form(uri.query.to_s).to_h
+    params["from"]   = "sdk"
+    params["tp"]     = "sdk"
+    params["source"] = SDK_NAME
+    params["name"]   = app_name if app_name
+    params["desc"]   = app_desc if app_desc
+    uri.query        = URI.encode_www_form(params)
+    uri.to_s
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  product_name = ENV.fetch("CLACKY_PRODUCT_NAME", "OpenClacky")
+  date_suffix  = Time.now.strftime("%Y%m%d")
+  app_desc     = "Your personal assistant powered by #{product_name}"
+
+  result = FeishuSetup.run(
+    app_name: "#{product_name} #{date_suffix}",
+    app_desc: app_desc,
+    on_qr_code: lambda { |url, expire_in|
+      puts "SCAN_URL:#{url}"
+      puts "EXPIRE_IN:#{expire_in}"
+      $stdout.flush
+    },
+    on_status_change: lambda { |status|
+      $stderr.puts "[feishu-setup] status=#{status}"
+    }
+  )
+
+  puts "APP_ID:#{result[:client_id]}"
+  puts "APP_SECRET:#{result[:client_secret]}"
+  $stdout.flush
+end

data/lib/clacky/default_skills/media-gen/SKILL.md

@@ -32,6 +32,11 @@ Do NOT try to fall back to `terminal` + a hand-written `curl https://api.openai.
 
 ## Step 2 — Generate the image
 
+### ⚠️  Important: generation speed & concurrency
+
+- **Image generation can be slow — up to 2 minutes per image depending on the model.** Before calling the API, warn the user that it may take a minute or two. The curl request blocks until the image is ready; do NOT run it in the background.
+- **One at a time only.** Never generate multiple images concurrently (e.g. by running several `curl` commands simultaneously or in a script loop). Each call consumes significant server-side resources, and parallel requests will almost certainly cause timeouts. If the user wants several images, generate them **sequentially**, one after another.
+
 ```bash
 curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/media/image \
   -H "Content-Type: application/json" \