openclacky 0.9.2 → 0.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 634937d9d7a20aa0a76b046ba079ef2d82c398ac81d59014968f7dbeb325726c
-  data.tar.gz: 7cd5c7eab980c54b5da38b6744dbc21dd3ac48af00c541a609d5537d6867ee70
+  metadata.gz: d842684d3cae23106509a9e47be986d51e518f8b953e66011783b32e1a121a6e
+  data.tar.gz: 34a8ef45f736724fd7e8356e032a4cd1102bd1a28b47f412419895bd8575caf7
 SHA512:
-  metadata.gz: b874781caf58c502536666c33b8aff0c459076689909dd36bd82151f7092953d453d51b2e90259bbfdb6b2eb0ba389e5e56c083a1364118ca0a15edbef471e02
-  data.tar.gz: 1639031ccf11848ab3b8c2a18d3eb7d87c487dc1e13b856e4c0cdc8cb35e3ebf4c8001660ea607f013e64a40fa1ef09255915652af9d0bc44ad8ddf9c0b1dff2
+  metadata.gz: cc9f6ee3d0b8ebf01346261dfd9dbcf6a77654bc40632b5730432fbe5ce23c604f30135739507c1802e837a4baf6097609ba26397c9eea2ec4555b115cd73dc9
+  data.tar.gz: 20ad77eb3191fadd1d4340ce7a92b16489be68e83dc4d33fa1d2e802a821074d1964f9a1e7afadcd7cbf9846b81dabebd5cbd918441bb3b3528bfd6212fb5f56

data/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.3] - 2026-03-16
+
+### Added
+- **Brand logo banner on web server startup**: a styled block-font logo now displays in the terminal when `clacky server` launches, giving a polished startup experience
+- **BlockFont renderer replaces artii dependency**: the gem now ships its own high-quality block-font engine for rendering large ASCII logos, removing the external `artii` dependency and enabling full offline use
+- **Hover-to-expand token usage and session info bar**: hovering over the token usage line or session info bar in the WebUI now expands it to show full details, keeping the UI compact by default
+- **Redesigned setup panel with Back button and Custom provider support**: the model setup flow now includes a Back button for navigation and a dedicated "Custom provider" path, making it easier to configure non-standard API endpoints; also fixes a dropdown re-entry bug
+- **License activation via non-blocking top banner**: the brand activation flow no longer blocks the entire UI with a full-screen panel — it now shows a slim top banner, and activation is handled through a dedicated skill
+- **`startSoulSession` exposed on Onboard public interface**: third-party integrations can now trigger soul session initialization directly from the onboard module
+
+### Improved
+- **Browser tool simplified and config-driven**: the browser tool setup is now handled through a unified config object, removing ~250 lines of complex auto-restart logic and making the tool more predictable and maintainable
+- **Prompt caching more stable**: cache anchoring now uses the last assistant message as the stable boundary, reducing cache misses caused by system prompt variations; caching is correctly restored for both Anthropic and OpenRouter paths
+- **Message format extracted to dedicated modules**: OpenAI and Anthropic message formatting now live in separate modules (`Clacky::MessageFormat::OpenAI` and `Clacky::MessageFormat::Anthropic`), making the client code easier to read and test
+- **WeCom channel reliability**: auth failure handling is improved with proper reconnection logic; the `channel-setup` skill guidance is also updated for clarity
+- **Install script and license expiry handling**: the install script is streamlined, license-expired states are handled gracefully, and encrypted skills are decrypted at load time
+
+### Fixed
+- **Prompt cache stability across turns**: cache was occasionally invalidated between turns due to message boundary drift; now anchored reliably to the last assistant message
+- **`request_user_feedback` missing from session history replay**: feedback prompts sent during a session were not rendered when replaying history in the WebUI; they now appear correctly as assistant messages
+- **Brand activation banner not shown when API key is missing**: the banner now correctly appears even when no API key is configured, with a translated skip warning
+- **Zip extraction security**: zip files are now read in chunks with size verification, preventing potential zip-bomb or oversized-file issues
+
+### More
+- Remove browser tool auto-restart logic that was causing instability in headless environments
+- Add security design documentation
+
 ## [0.9.2] - 2026-03-15
 
 ### Fixed

data/docs/security-design.md

@@ -0,0 +1,109 @@
+# openclacky 安全设计方案
+
+> 创建时间：2026-03-14
+> 背景：用户反馈 openclacky 可以操作任意文件和电脑，感觉不安全。本文档梳理现有安全机制和待实施的安全策略。
+
+---
+
+## 一、现有安全机制
+
+| 机制 | 说明 |
+|---|---|
+| 权限模式 | CLI 默认 `confirm_safes`，危险操作需用户确认 |
+| SafeShell | `rm` → 软删除到 trash、`sudo` 拦截、`curl \| bash` 拦截 |
+| 文件 diff 预览 | `write`/`edit` 操作前展示变更内容 |
+| 安全日志 | 每个项目有 `~/.clacky/safety_logs/<hash>/safety.log` 记录拦截记录 |
+| 受保护文件 | `.env`、`.ssh/`、`.aws/`、`Gemfile` 等不能被删除 |
+
+### 权限模式说明
+
+| 模式 | 行为 | 适用场景 |
+|---|---|---|
+| `confirm_safes` | 只读操作自动执行，写/危险 shell 需用户确认 | **CLI 默认** |
+| `confirm_all` | 遇到 `request_user_feedback` 才等待人工 | WebUI session 默认 |
+| `auto_approve` | 全自动执行所有工具，无需确认 | 定时任务默认 |
+
+---
+
+## 二、现有安全薄弱点
+
+1. **`write` 工具无路径限制** — 可写到项目目录外的任意路径（如 `~/.bashrc`）
+2. **`shell` 和 `safe_shell` 同时注册** — AI 可能绕过 safe_shell 直接用 `shell`
+3. **WebUI 无认证** — 任何能访问本地端口的进程或局域网用户都能控制 Agent
+4. **write 覆盖无备份** — 文件被 AI 改写后无法恢复（rm 有软删除，write 没有）
+5. **安全机制不可见** — 用户感知不到现有保护，导致不信任
+
+---
+
+## 三、安全策略（待实施）
+
+### 🟢 第一梯队：低成本、高收益（推荐优先）
+
+#### 1. 操作审计日志
+- Agent 执行的每个 `write`/`edit`/`shell` 操作，写入 `~/.clacky/audit.log`
+- 格式：时间戳 + 项目 + 操作类型 + 详情
+- 提供 `clacky audit` 命令查看历史操作
+- **价值**：让用户看得见 AI 做了什么，信任感最强
+
+#### 2. 权限模式状态可见化
+- WebUI 顶部常驻显示当前权限级别，颜色区分
+  - 🔴 `auto_approve` — 全自动，无需确认
+  - 🟡 `confirm_safes` — 危险操作需确认（推荐）
+  - 🟢 `confirm_all` — 所有操作均需确认
+- CLI 启动时打印当前权限模式
+
+#### 3. 统一走 safe_shell（堵漏洞）
+- 移除裸 `shell` 工具，只保留 `safe_shell`
+- 确保所有 shell 命令都经过安全替换器处理
+- 成本极低，安全提升明显
+
+---
+
+### 🟡 第二梯队：中等成本、用户感知强
+
+#### 4. write/edit 路径白名单
+- 只允许写项目工作目录内的文件
+- 写项目外路径（如 `~/.bashrc`、`~/.ssh/`）需额外确认，或默认拒绝
+- 防止 AI 越界修改系统/用户配置文件
+
+#### 5. WebUI 本地认证 Token
+- 启动 Web 服务时生成随机 token，终端显示带 token 的访问链接
+- 防止本地其他进程或局域网内的人劫持 Agent
+- 参考：Jupyter Notebook 的成熟方案
+
+#### 6. write 操作自动备份（撤销支持）
+- `write` 覆盖文件前，自动备份原文件到 `~/.clacky/trash/`
+- 支持 `clacky undo` 恢复被 AI 改写的文件
+- 用户最担心的就是"AI 把我文件改了找不回来"
+
+---
+
+### 🔵 第三梯队：大投入、长期规划
+
+#### 7. 沙箱模式（Docker）
+- 可选的隔离执行环境，把 Agent 限制在容器内
+- 主机文件系统与 Agent 完全隔离
+- 适合高敏感场景，启动成本高、对体验有影响
+
+#### 8. 网络访问白名单
+- 控制 `web_fetch`/`curl` 能访问的域名范围
+- 适合企业级部署场景
+
+---
+
+## 四、实施优先级建议
+
+1. **审计日志** — 让用户"看得见"AI 做了什么，信任感提升最显著
+2. **write/edit 路径白名单** — 堵最大的安全漏洞
+3. **统一走 safe_shell** — 低成本堵漏，可顺手实施
+
+---
+
+## 五、让用户放心的核心原则
+
+> **安全机制不够，用户感知更重要。**
+
+- 用户能看到 AI 正在做什么（实时显示）
+- 用户能看到 AI 做过什么（审计日志）
+- 用户能撤销 AI 的操作（备份+恢复）
+- 用户能控制 AI 的权限（权限模式可见+可切换）

data/lib/clacky/agent/message_compressor_helper.rb

@@ -153,113 +153,126 @@ module Clacky
         )
       end
 
-      # Get recent messages while preserving tool_calls/tool_results pairs
-      # This ensures assistant messages with tool_calls are kept together with ALL their tool results
+      # Get recent messages while preserving tool_calls/tool_results pairs.
+      # Handles both canonical format (role: "tool") and legacy Anthropic-native
+      # format (role: "user" with tool_result content blocks).
       # @param messages [Array] All messages
       # @param count [Integer] Target number of recent messages to keep
       # @return [Array] Recent messages with complete tool pairs
       def get_recent_messages_with_tool_pairs(messages, count)
-        # This method ensures that assistant messages with tool_calls are always kept together
-        # with ALL their corresponding tool_results, maintaining the correct order.
-        # This is critical for Bedrock Claude API which validates the tool_calls/tool_results pairing.
-
         return [] if messages.nil? || messages.empty?
 
-        # Track which messages to include
         messages_to_include = Set.new
-
-        # Start from the end and work backwards
         i = messages.size - 1
         messages_collected = 0
 
         while i >= 0 && messages_collected < count
           msg = messages[i]
 
-          # Skip if already marked for inclusion
           if messages_to_include.include?(i)
             i -= 1
             next
           end
 
-          # Mark this message for inclusion
           messages_to_include.add(i)
           messages_collected += 1
 
-          # If this is an assistant message with tool_calls, we MUST include ALL corresponding tool results
-          if msg[:role] == "assistant" && msg[:tool_calls]
-            tool_call_ids = msg[:tool_calls].map { |tc| tc[:id] }
-
-            # Find all tool results that belong to this assistant message
-            # They should be in the messages immediately following this assistant message
-            j = i + 1
-            while j < messages.size
-              next_msg = messages[j]
-
-              # If we find a tool result for one of our tool_calls, include it
-              if next_msg[:role] == "tool" && tool_call_ids.include?(next_msg[:tool_call_id])
-                messages_to_include.add(j)
-              elsif next_msg[:role] != "tool"
-                # Stop when we hit a non-tool message (start of next turn)
-                break
-              end
-
-              j += 1
-            end
+          # assistant with tool_calls → also pull in all following tool results
+          if msg[:role] == "assistant" && msg[:tool_calls]&.any?
+            pull_tool_results_after(messages, i, messages_to_include)
           end
 
-          # If this is a tool result, make sure its assistant message is also included
-          if msg[:role] == "tool"
-            # Find the corresponding assistant message
-            j = i - 1
-            while j >= 0
-              prev_msg = messages[j]
-              if prev_msg[:role] == "assistant" && prev_msg[:tool_calls]
-                # Check if this assistant has the matching tool_call
-                has_matching_call = prev_msg[:tool_calls].any? { |tc| tc[:id] == msg[:tool_call_id] }
-                if has_matching_call
-                  unless messages_to_include.include?(j)
-                    messages_to_include.add(j)
-                    messages_collected += 1
-                  end
-
-                  # Also include all other tool results for this assistant message
-                  tool_call_ids = prev_msg[:tool_calls].map { |tc| tc[:id] }
-                  k = j + 1
-                  while k < messages.size
-                    result_msg = messages[k]
-                    if result_msg[:role] == "tool" && tool_call_ids.include?(result_msg[:tool_call_id])
-                      messages_to_include.add(k)
-                    elsif result_msg[:role] != "tool"
-                      break
-                    end
-                    k += 1
-                  end
-
-                  break
-                end
-              end
-              j -= 1
+          # tool result (canonical or legacy Anthropic) → also pull in its assistant
+          if tool_result_message?(msg)
+            pull_assistant_before(messages, i, messages_to_include) do |added|
+              messages_collected += 1 if added
             end
           end
 
           i -= 1
         end
 
-        # Extract the messages in their original order
         recent_messages = messages_to_include.to_a.sort.map { |idx| messages[idx] }
 
         # Truncate large tool results to prevent token bloat
         recent_messages.map do |msg|
-          if msg[:role] == "tool" && msg[:content].is_a?(String) && msg[:content].length > 2000
-            msg.merge(content: msg[:content][0..2000] + "...\n[Content truncated - exceeded 2000 characters]")
-          else
-            msg
-          end
+          truncate_tool_result(msg)
         end
       end
 
       private
 
+      # Returns true if msg is a tool result, regardless of storage format.
+      # Canonical: role:"tool"  |  Legacy Anthropic-native: role:"user" + tool_result blocks
+      def tool_result_message?(msg)
+        MessageFormat::OpenAI.tool_result_message?(msg) ||
+          MessageFormat::Anthropic.tool_result_message?(msg)
+      end
+
+      # Returns the tool_call IDs referenced in a tool result message.
+      def tool_result_ids(msg)
+        if MessageFormat::OpenAI.tool_result_message?(msg)
+          MessageFormat::OpenAI.tool_call_ids(msg)
+        else
+          MessageFormat::Anthropic.tool_use_ids(msg)
+        end
+      end
+
+      # Returns true if msg is a tool result that matches any of the given call IDs.
+      def tool_result_for?(msg, call_ids)
+        tool_result_message?(msg) && (tool_result_ids(msg) & call_ids).any?
+      end
+
+      # Mark all tool results immediately following messages[assistant_idx].
+      # Stops at the first non-tool-result message.
+      def pull_tool_results_after(messages, assistant_idx, include_set)
+        call_ids = messages[assistant_idx][:tool_calls].map { |tc| tc[:id] }
+        j = assistant_idx + 1
+        while j < messages.size
+          nxt = messages[j]
+          if tool_result_for?(nxt, call_ids)
+            include_set.add(j)
+          elsif !tool_result_message?(nxt)
+            break
+          end
+          j += 1
+        end
+      end
+
+      # Walk backwards from tool_result_idx to find and mark its assistant message.
+      # Also marks all sibling tool results for that assistant.
+      # Yields true if the assistant was newly added (for caller to increment count).
+      def pull_assistant_before(messages, tool_result_idx, include_set)
+        result_ids = tool_result_ids(messages[tool_result_idx])
+
+        j = tool_result_idx - 1
+        while j >= 0
+          prev = messages[j]
+          if prev[:role] == "assistant" && prev[:tool_calls]&.any?
+            call_ids = prev[:tool_calls].map { |tc| tc[:id] }
+            if (call_ids & result_ids).any?
+              newly_added = include_set.add?(j)
+              yield newly_added
+
+              # Also pull all sibling tool results for this assistant
+              pull_tool_results_after(messages, j, include_set)
+              break
+            end
+          end
+          j -= 1
+        end
+      end
+
+      # Truncate oversized tool result content to avoid token bloat.
+      def truncate_tool_result(msg)
+        if MessageFormat::OpenAI.tool_result_message?(msg) &&
+            msg[:content].is_a?(String) && msg[:content].length > 2000
+          msg.merge(content: msg[:content][0..2000] + "...\n[Content truncated - exceeded 2000 characters]")
+        else
+          msg
+        end
+      end
+
       # Save the messages being compressed to a chunk MD file for future recall
       # File path: ~/.clacky/sessions/{datetime}-{short_id}-chunk-{n}.md
       # @param original_messages [Array<Hash>] All messages before compression (excluding compression instruction)

data/lib/clacky/agent/session_serializer.rb

@@ -191,7 +191,15 @@ module Clacky
                 name     = tc[:name] || tc.dig(:function, :name) || ""
                 args_raw = tc[:arguments] || tc.dig(:function, :arguments) || {}
                 args     = args_raw.is_a?(String) ? (JSON.parse(args_raw) rescue args_raw) : args_raw
-                ui.show_tool_call(name, args)
+
+                # Special handling: request_user_feedback question is shown as an
+                # assistant message (matching real-time behavior), not as a tool call.
+                if name == "request_user_feedback"
+                  question = args.is_a?(Hash) ? (args[:question] || args["question"]).to_s : ""
+                  ui.show_assistant_message(question) unless question.empty?
+                else
+                  ui.show_tool_call(name, args)
+                end
               end
 
               # Emit token usage stored on this message (for history replay display)

data/lib/clacky/agent/skill_manager.rb

@@ -155,6 +155,13 @@ module Clacky
         skill = parsed[:skill]
         arguments = parsed[:arguments]
 
+        # Encrypted brand skills and fork-agent skills must run in an isolated subagent.
+        # Injecting their plaintext into @messages would expose confidential content to the LLM.
+        if skill.encrypted? || skill.fork_agent?
+          execute_skill_with_subagent(skill, arguments)
+          return
+        end
+
         # Expand skill content (substitutes $ARGUMENTS if present)
         expanded_content = skill.process_content(arguments, template_context: build_template_context)
 

data/lib/clacky/agent.rb

@@ -671,16 +671,24 @@ module Clacky
     private def format_tool_calls_for_api(tool_calls)
       return nil unless tool_calls
 
-      tool_calls.map do |call|
+      valid = tool_calls.filter_map do |call|
+        func = call[:function] || call
+        name = func[:name] || call[:name]
+        arguments = func[:arguments] || call[:arguments]
+        # Skip malformed tool calls with nil name or arguments
+        next if name.nil? || arguments.nil?
+
         {
           id: call[:id],
           type: call[:type] || "function",
           function: {
-            name: call[:name],
-            arguments: call[:arguments]
+            name: name,
+            arguments: arguments
           }
         }
       end
+
+      valid.any? ? valid : nil
     end
 
     private def register_builtin_tools

data/lib/clacky/banner.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "pastel"
+require_relative "version"
+require_relative "brand_config"
+require_relative "block_font"
+
+module Clacky
+  # Banner provides logo and branding for CLI and Web UI startup.
+  # Lightweight — no terminal UI dependencies.
+  class Banner
+    DEFAULT_CLI_LOGO = <<~'LOGO'
+   ██████╗ ██████╗ ███████╗███╗   ██╗ ██████╗██╗      █████╗  ██████╗██╗  ██╗██╗   ██╗
+  ██╔═══██╗██╔══██╗██╔════╝████╗  ██║██╔════╝██║     ██╔══██╗██╔════╝██║ ██╔╝╚██╗ ██╔╝
+  ██║   ██║██████╔╝█████╗  ██╔██╗ ██║██║     ██║     ███████║██║     █████╔╝  ╚████╔╝
+  ██║   ██║██╔═══╝ ██╔══╝  ██║╚██╗██║██║     ██║     ██╔══██║██║     ██╔═██╗   ╚██╔╝
+  ╚██████╔╝██║     ███████╗██║ ╚████║╚██████╗███████╗██║  ██║╚██████╗██║  ██╗   ██║
+   ╚═════╝ ╚═╝     ╚══════╝╚═╝  ╚═══╝ ╚═════╝╚══════╝╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝   ╚═╝
+    LOGO
+
+    TAGLINE = "[>] Your personal Assistant & Technical Co-founder"
+
+    def initialize
+      @pastel = Pastel.new
+      @brand  = BrandConfig.load
+    end
+
+    # Returns the CLI logo text.
+    # If branded, renders brand_command using BlockFont (big Unicode art).
+    # Falls back to default OPENCLACKY logo when not branded.
+    def cli_logo
+      if @brand.branded?
+        render_key = @brand.brand_command.to_s.strip
+        render_key = "clacky" if render_key.empty?
+        Clacky::BlockFont.render(render_key)
+      else
+        DEFAULT_CLI_LOGO
+      end
+    end
+
+    # Returns the tagline string.
+    def tagline
+      if @brand.branded?
+        @brand.brand_name.to_s
+      else
+        TAGLINE
+      end
+    end
+
+    # Renders the CLI logo as colored text
+    def colored_cli_logo
+      @pastel.bright_green(cli_logo)
+    end
+
+    # Renders the tagline as colored text
+    def colored_tagline
+      @pastel.bright_cyan(tagline)
+    end
+
+    # Renders a URL with bold + underline for emphasis
+    def highlight(url)
+      @pastel.bold.underline(url)
+    end
+  end
+end