openclacky 1.2.10 → 1.2.13

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
@@ -502,6 +533,11 @@ module Clacky
               end
             end
 
+            # If the assistant ended its turn with a question, treat this as
+            # an in-flight conversation (agent is awaiting the user's reply)
+            # and skip skill evolution — the task isn't truly complete yet.
+            awaiting_user_feedback = true if ends_with_question
+
             break
           end
 
@@ -595,6 +631,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
@@ -620,6 +661,7 @@ module Clacky
         # Safety net: ensure any lingering progress spinner is stopped.
         # Normal paths close their own spinners; this guards against exceptions
         # raised between a progress slot's active/done pair.
+        Clacky::Logger.warn("[ph_debug] agent_run_ensure")
         @ui&.show_progress(phase: "done")
 
         # Shred any decrypted-script tmpdirs created during this run for encrypted brand skills.
@@ -808,6 +850,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)
@@ -1199,7 +1242,7 @@ module Clacky
         # Skip malformed tool calls with nil name or arguments
         next if name.nil? || arguments.nil?
 
-        {
+        formatted = {
           id: call[:id],
           type: call[:type] || "function",
           function: {
@@ -1207,6 +1250,8 @@ module Clacky
             arguments: arguments
           }
         }
+        formatted[:extra_content] = call[:extra_content] if call[:extra_content]
+        formatted
       end
 
       valid.any? ? valid : nil

data/lib/clacky/agent_config.rb

@@ -615,14 +615,17 @@ module Clacky
     def find_model_by_type(type)
       kind = type.to_s
       if Clacky::Providers::MEDIA_KINDS.include?(kind)
-        custom = @models.find { |m| m["type"] == kind }
-        return custom if custom
-        return derive_media_model(kind)
+        entry = @models.find { |m| m["type"] == kind }
+        return nil if entry && entry["disabled"]
+        if entry && entry["base_url"].to_s.strip != "" && entry["api_key"].to_s.strip != ""
+          return entry
+        end
+        return derive_media_model(kind, model_override: entry && entry["model"])
       end
       @models.find { |m| m["type"] == type }
     end
 
-    private def derive_media_model(kind)
+    private def derive_media_model(kind, model_override: nil)
       default = find_model_by_type("default")
       return nil unless default
 
@@ -632,7 +635,16 @@ module Clacky
       )
       return nil unless provider_id
 
-      model_name = Clacky::Providers.default_media_model(provider_id, kind)
+      if model_override && !model_override.to_s.strip.empty?
+        available = Clacky::Providers.media_models(provider_id, kind)
+        if available.include?(model_override)
+          model_name = model_override
+        else
+          model_name = Clacky::Providers.default_media_model(provider_id, kind)
+        end
+      else
+        model_name = Clacky::Providers.default_media_model(provider_id, kind)
+      end
       return nil if model_name.nil? || model_name.to_s.empty?
 
       {
@@ -662,35 +674,67 @@ module Clacky
     #   "available"  [Array<String>]      — auto-source candidates from preset
     def media_state(kind)
       kind = kind.to_s
-      custom = @models.find { |m| m["type"] == kind }
-      auto   = custom ? nil : derive_media_model(kind)
-      entry  = custom || auto
+      raw_entry = @models.find { |m| m["type"] == kind }
+
+      if raw_entry && raw_entry["disabled"]
+        default = find_model_by_type("default")
+        default_provider = default && Clacky::Providers.resolve_provider(
+          base_url: default["base_url"], api_key: default["api_key"]
+        )
+        available = default_provider ? Clacky::Providers.media_models(default_provider, kind) : []
+        aliases  = default_provider ? Clacky::Providers.media_model_aliases(default_provider, kind) : {}
+        return {
+          "configured" => false,
+          "source"     => "off",
+          "model"      => nil,
+          "base_url"   => nil,
+          "provider"   => nil,
+          "available"  => available,
+          "aliases"    => aliases,
+          "stale"      => false
+        }
+      end
+
+      is_custom = raw_entry &&
+                  raw_entry["base_url"].to_s.strip != "" &&
+                  raw_entry["api_key"].to_s.strip != ""
+      override_model = raw_entry && !is_custom ? raw_entry["model"] : nil
+
+      entry = if is_custom
+                raw_entry
+              else
+                derive_media_model(kind, model_override: override_model)
+              end
 
       provider_id = if entry
                       Clacky::Providers.resolve_provider(
-                        base_url: entry["base_url"],
-                        api_key:  entry["api_key"]
+                        base_url: entry["base_url"], api_key: entry["api_key"]
                       )
                     end
 
-      available_provider_id = if custom
+      available_provider_id = if is_custom
                                 provider_id
                               else
                                 default = find_model_by_type("default")
                                 default && Clacky::Providers.resolve_provider(
-                                  base_url: default["base_url"],
-                                  api_key:  default["api_key"]
+                                  base_url: default["base_url"], api_key: default["api_key"]
                                 )
                               end
       available = available_provider_id ? Clacky::Providers.media_models(available_provider_id, kind) : []
+      aliases   = available_provider_id ? Clacky::Providers.media_model_aliases(available_provider_id, kind) : {}
+
+      stale = !!(override_model && entry && entry["model"] != override_model)
 
       {
         "configured" => !entry.nil?,
-        "source"     => custom ? "custom" : (auto ? "auto" : "off"),
+        "source"     => is_custom ? "custom" : (entry ? "auto" : "off"),
         "model"      => entry && entry["model"],
         "base_url"   => entry && entry["base_url"],
         "provider"   => provider_id,
-        "available"  => available
+        "available"  => available,
+        "aliases"    => aliases,
+        "stale"      => stale,
+        "requested_model" => stale ? override_model : nil
       }
     end
 

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/cli.rb

@@ -50,6 +50,7 @@ module Clacky
     option :verbose, type: :boolean, aliases: "-v", default: false, desc: "Show detailed output"
     option :path, type: :string, desc: "Project directory path (defaults to current directory)"
     option :continue, type: :boolean, aliases: "-c", desc: "Continue most recent session"
+    option :fork, type: :string, desc: "Fork a session by number or session ID prefix (creates a copy)"
     option :list, type: :boolean, aliases: "-l", desc: "List recent sessions"
     option :attach, type: :string, aliases: "-a", desc: "Attach to session by number or keyword"
     option :json, type: :boolean, default: false, desc: "Output NDJSON to stdout (for scripting/piping)"
@@ -140,6 +141,9 @@ module Clacky
       elsif options[:attach]
         agent = load_session_by_number(client_factory.call, agent_config, session_manager, working_dir, options[:attach], profile: agent_profile)
         is_session_load = !agent.nil?
+      elsif options[:fork]
+        agent = fork_session(client_factory.call, agent_config, session_manager, working_dir, options[:fork], profile: agent_profile)
+        is_session_load = !agent.nil?
       end
 
       # Create new agent if no session loaded
@@ -549,8 +553,59 @@ module Clacky
         Clacky::Agent.from_session(client, agent_config, session_data, profile: resolved_profile)
       end
 
+      def fork_session(client, agent_config, session_manager, working_dir, identifier, profile:)
+        # Get a larger list to search through (for ID prefix matching)
+        sessions = session_manager.all_sessions(current_dir: working_dir, limit: 100)
+
+        if sessions.empty?
+          say "No sessions found.", :yellow
+          return nil
+        end
+
+        session_data = nil
+
+        # Same resolution logic as load_session_by_number
+        if identifier.match?(/^\d+$/) && identifier.to_i <= 99
+          index = identifier.to_i - 1
+          if index < 0 || index >= sessions.size
+            say "Invalid session number. Use -l to list available sessions.", :red
+            exit 1
+          end
+          session_data = sessions[index]
+        else
+          matching_sessions = sessions.select { |s| s[:session_id].start_with?(identifier) }
+          if matching_sessions.empty?
+            say "No session found matching ID prefix: #{identifier}", :red
+            say "Use -l to list available sessions.", :yellow
+            exit 1
+          elsif matching_sessions.size > 1
+            say "Multiple sessions found matching '#{identifier}':", :yellow
+            matching_sessions.each_with_index do |session, idx|
+              created_at = Time.parse(session[:created_at]).strftime("%Y-%m-%d %H:%M")
+              s_id = session[:session_id][0..7]
+              name = session[:name].to_s.empty? ? "Unnamed session" : session[:name]
+              say "  #{idx + 1}. [#{s_id}] #{created_at} - #{name}", :cyan
+            end
+            say "\nPlease use a more specific prefix.", :yellow
+            exit 1
+          else
+            session_data = matching_sessions.first
+          end
+        end
+
+        fork_data = session_manager.fork(session_data[:session_id])
+        return nil unless fork_data
+
+        # Fall back to CLI --agent flag for sessions that predate agent_profile
+        restored_profile = fork_data[:agent_profile].to_s
+        resolved_profile = restored_profile.empty? ? profile : restored_profile
+
+        Clacky::Agent.from_session(client, agent_config, fork_data, profile: resolved_profile)
+      end
+
       # Handle agent error/interrupt with cleanup
       def handle_agent_exception(ui_controller, agent, session_manager, exception)
+        Clacky::Logger.warn("[ph_debug] handle_agent_exception", klass: exception.class.name, msg: exception.message.to_s[0, 200])
         ui_controller.show_progress(phase: "done")
         ui_controller.set_idle_status
 

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."