openclacky 1.0.2 → 1.0.4

data/lib/clacky/default_agents/coding/system_prompt.md

@@ -3,7 +3,7 @@ users complete software development projects. You are responsible for developmen
 
 Your role is to:
 - Understand project requirements and translate them into technical solutions
-- Write clean, maintainable, and well-documented code
+- Write clean, maintainable code
 - Follow best practices and industry standards
 - Explain technical concepts in simple terms when needed
 - Proactively identify potential issues and suggest improvements
@@ -15,3 +15,53 @@ Working process:
 3. You should frequently refer to the existing codebase. For unclear instructions,
    prioritize understanding the codebase first before answering or taking action.
    Always read relevant code files to understand the project structure, patterns, and conventions.
+
+## Code Style
+
+- **Default to writing no comments.** Only add one when the WHY is non-obvious: a hidden constraint, a subtle invariant, a workaround for a specific bug, or behavior that would surprise a reader.
+- Don't explain WHAT the code does — well-named identifiers already do that.
+- Don't reference the current task, fix, or callers ("used by X", "added for the Y flow", "handles the case from issue #123"). These belong in the PR description and rot as the codebase evolves.
+- Never write multi-paragraph docstrings or multi-line comment blocks — one short line max.
+
+## File Modification Rules
+
+- **ALWAYS prefer `edit` over `write`.** Use `write` only for creating entirely new files or complete rewrites.
+- When editing text from `file_reader` output, preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix.
+- Ensure `old_string` is unique in the file. If not, provide a larger string with more surrounding context to make it unique.
+- Use `replace_all` only when you genuinely need to change every occurrence.
+- When referencing specific functions or pieces of code, include `file_path:line_number` to help the user navigate.
+
+## Git Safety Protocol
+
+- NEVER update git config (user.name, user.email, etc.)
+- NEVER run destructive commands: `git push --force`, `git reset --hard`, `git checkout .`, `git clean -f`
+- NEVER skip hooks (`--no-verify`, `--no-gpg-sign`)
+- When staging files, prefer `git add <specific-file>` over `git add -A` or `git add .`
+- Always create NEW commits rather than amending existing ones
+- Never amend published commits
+- Only create commits when requested by the user. If unclear, ask first.
+
+## Error Handling
+
+- Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal code and framework guarantees.
+- Only validate at system boundaries (user input, external APIs).
+- Don't use feature flags or backwards-compatibility shims when you can just change the code.
+
+## Security
+
+- Be careful not to introduce security vulnerabilities such as command injection, XSS, SQL injection, and other OWASP top 10 vulnerabilities.
+- If you notice insecure code, immediately fix it.
+- Prioritize writing safe, secure, and correct code.
+
+## Testing
+
+- For UI or frontend changes, start the dev server and verify in a browser before reporting the task as complete.
+- Type checking and test suites verify code correctness, not feature correctness — if you can't test the UI, say so explicitly rather than claiming success.
+- When the user asks you to run tests, do so and report the results.
+
+## Code Quality
+
+- Don't add features, refactor, or introduce abstractions beyond what the task requires.
+- A bug fix doesn't need surrounding cleanup; a one-shot operation doesn't need a helper.
+- Three similar lines is better than a premature abstraction.
+- No half-finished implementations either.

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

@@ -4,9 +4,10 @@ description: |
   Configure IM platform channels (Feishu, WeCom, Weixin) for openclacky.
   Uses browser automation for navigation; guides the user to paste credentials and perform UI steps.
   Trigger on: "channel setup", "setup feishu", "setup wecom", "setup weixin", "setup wechat", "channel config",
-  "channel status", "channel enable", "channel disable", "channel reconfigure", "channel doctor".
-  Subcommands: setup, status, enable <platform>, disable <platform>, reconfigure, doctor.
-argument-hint: "setup | status | enable <platform> | disable <platform> | reconfigure | doctor"
+  "channel status", "channel enable", "channel disable", "channel reconfigure", "channel doctor",
+  "send message to weixin", "send message to feishu", "send message to wecom".
+  Subcommands: setup, status, enable <platform>, disable <platform>, reconfigure, doctor, send.
+argument-hint: "setup | status | enable <platform> | disable <platform> | reconfigure | doctor | send <platform> <message>"
 allowed-tools:
   - Bash
   - Read
@@ -33,6 +34,7 @@ Configure IM platform channels for openclacky.
 | `channel disable feishu/wecom/weixin` | disable |
 | `channel reconfigure` | reconfigure |
 | `channel doctor` | doctor |
+| `send <message> to weixin/feishu/wecom` | send |
 
 ---
 
@@ -98,7 +100,7 @@ ruby "SKILL_DIR/feishu_setup.rb"
 - The script completed successfully.
 - Config is already written to `~/.clacky/channels.yml`.
 - Tell the user: "✅ Feishu channel configured automatically! The channel is ready."
-- **Stop here — do not proceed to manual steps.**
+- **Skip Step 2 (manual fallback) and continue to Step 3.**
 
 **If exit code is non-0:**
 - Check stdout for the error message.
@@ -197,7 +199,61 @@ curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/in
   -d '{"app_id":"<APP_ID>","app_secret":"<APP_SECRET>"}'
 ```
 
-Check for `"code":0`. On success: "✅ Feishu channel configured."
+Check for `"code":0`. On success: continue to Step 3 (below).
+
+##### Phase 9 — done
+
+Step 2 ends here. **Continue to Step 3.**
+
+---
+
+#### Step 3 — Optional: install Feishu CLI
+
+Reach here from either Step 1 success or end of Step 2. 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": ["启用", "跳过"]
+}
+```
+
+en:
+```json
+{
+  "question": "Install Feishu CLI? With it, the AI can operate Feishu Docs, Sheets, Bitable, Wiki, Calendar, Tasks and almost every Feishu capability — not just chat, but actually get things done. Skipping is fine.",
+  "options": ["Enable", "Skip"]
+}
+```
+
+If the user picks Skip, stop — setup is complete.
+
+If the user picks Enable, run:
+
+```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
+npx -y skills add larksuite/cli -y -g
+ruby "SKILL_DIR/import_lark_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.
+
+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):
+- 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.
+
+When `lark-cli auth login` returns successfully, tell the user:
+- zh: "✅ 飞书 CLI 已就绪。"
+- en: "✅ Feishu CLI is ready."
+
+**Stop — setup is fully complete.**
 
 ---
 
@@ -347,6 +403,58 @@ Check each item, report ✅ / ❌ with remediation:
 
 ---
 
+## `send`
+
+Proactively send a message to a user via an IM channel adapter.
+
+### Parse the request
+
+Extract two things from the user's instruction:
+- **platform** — one of `weixin`, `feishu`, `wecom`
+- **message** — the text content to send
+
+If the platform cannot be inferred, ask the user to clarify.
+
+### Step 1 — Resolve target user (optional)
+
+If the user specified a `user_id`, use it directly.
+
+Otherwise, list known users first:
+
+```bash
+curl -s http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/<platform>/users
+```
+
+- If the list is **empty**: tell the user "No known users for `<platform>`. The target user must send at least one message to the bot before proactive messaging is possible." Stop here.
+- If there is **exactly one** user: use it silently.
+- If there are **multiple** users: show the list and ask which one to send to, unless the user already specified one.
+
+### Step 2 — Send the message
+
+```bash
+curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/<platform>/send \
+  -H "Content-Type: application/json" \
+  -d '{"message": "<message>", "user_id": "<user_id>"}'
+```
+
+**Response handling:**
+
+| HTTP status | Meaning | Action |
+|---|---|---|
+| `200 { ok: true }` | Delivered | Tell user: "✅ Message sent to `<platform>`." |
+| `400` platform not running | Adapter is stopped | Tell user the platform is not running and suggest `channel enable <platform>`. |
+| `400` no context_token | Token missing | Explain: "The bot has no active session token for this user. Ask the user to send any message to the bot first, then retry." |
+| `503` no known users | Nobody has messaged the bot | Same guidance as empty user list above. |
+| Other error | Unexpected | Show the error message from the response body. |
+
+### Constraints & notes
+
+- **Weixin (iLink protocol)**: Every outbound message requires a `context_token` that is obtained from the most recent inbound message from that user. The token is cached in memory and reset on server restart. If the server was restarted since the user last wrote, the token is gone and the send will fail — the user must message the bot again.
+- **Feishu / WeCom**: No token required. As long as the adapter is running and the `user_id` / `chat_id` is valid, the message will be delivered.
+- This feature is intended for **proactive notifications** (e.g. task completion, reminders). It is not a replacement for the normal reply flow triggered by inbound messages.
+
+---
+
 ## Security
 
 - Always mask secrets in output (last 4 chars only).

data/lib/clacky/default_skills/channel-setup/import_lark_skills.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'pathname'
+
+# Import lark-cli's official Skills from ~/.agents/skills/lark-* into
+# ~/.clacky/skills/lark-imports/<name>/.
+#
+# Background:
+#   lark-cli ships ~24 SKILL.md files (lark-doc, lark-sheets, lark-base, ...)
+#   that teach the agent how to use `lark-cli`. They are normally installed
+#   under ~/.agents/skills/lark-*, which openclacky's SkillLoader does NOT
+#   scan. This importer copies them into ~/.clacky/skills/lark-imports/ so
+#   they become discoverable via the standard skill description-matching
+#   mechanism.
+#
+# This is intentionally a small, dedicated importer (not a generic external
+# skills tool) — it only handles the lark-cli case for the feishu channel
+# setup flow. Failures are non-fatal: the bot itself remains functional even
+# if Skills cannot be exposed.
+#
+# Usage:
+#   importer = Clacky::ChannelSetup::LarkSkillsImporter.new
+#   result = importer.run
+#   # result => { copied: 24, skipped: 0, errors: [] }
+
+module Clacky
+  module ChannelSetup
+    class LarkSkillsImporter
+      DEFAULT_SOURCE_DIR = File.join(Dir.home, '.agents', 'skills')
+      DEFAULT_TARGET_DIR = File.join(Dir.home, '.clacky', 'skills', 'lark-imports')
+      SKILL_PREFIX       = 'lark-'
+
+      # @param source_dir [String] directory containing lark-cli installed skills
+      # @param target_dir [String] destination under ~/.clacky/skills/
+      def initialize(source_dir: DEFAULT_SOURCE_DIR, target_dir: DEFAULT_TARGET_DIR)
+        @source_dir = Pathname.new(source_dir).expand_path
+        @target_dir = Pathname.new(target_dir).expand_path
+      end
+
+      # Run the import. Returns a result hash; never raises on per-skill errors.
+      # @return [Hash] { copied: Integer, skipped: Integer, errors: Array<String> }
+      def run
+        return { copied: 0, skipped: 0, errors: ["source not found: #{@source_dir}"] } unless @source_dir.directory?
+
+        skill_dirs = discover_lark_skills
+        return { copied: 0, skipped: 0, errors: [] } if skill_dirs.empty?
+
+        FileUtils.mkdir_p(@target_dir)
+
+        copied = 0
+        errors = []
+        skill_dirs.each do |src|
+          begin
+            copy_skill(src)
+            copied += 1
+          rescue StandardError => e
+            errors << "#{src.basename}: #{e.message}"
+          end
+        end
+
+        { copied: copied, skipped: 0, errors: errors }
+      end
+
+      # Discover candidate lark-* skill directories under @source_dir.
+      # A directory qualifies when it (a) starts with "lark-" and (b) contains a SKILL.md.
+      # @return [Array<Pathname>]
+      private def discover_lark_skills
+        @source_dir.children
+                   .select { |p| p.directory? && p.basename.to_s.start_with?(SKILL_PREFIX) }
+                   .select { |p| p.join('SKILL.md').exist? }
+                   .sort_by { |p| p.basename.to_s }
+      end
+
+      # Copy a single skill directory into @target_dir, replacing any existing copy
+      # so re-runs always reflect the latest version.
+      # @param src [Pathname]
+      private def copy_skill(src)
+        dst = @target_dir.join(src.basename.to_s)
+        FileUtils.rm_rf(dst) if dst.exist?
+        FileUtils.mkdir_p(dst)
+        src.children.each { |child| FileUtils.cp_r(child, dst) }
+      end
+    end
+  end
+end
+
+# CLI entry point — invoked by SKILL.md after the user opts in to lark-cli.
+# Usage:
+#   ruby import_lark_skills.rb
+# Prints a one-line summary; exits 0 even when nothing to copy (treat empty
+# source as a soft skip — the script may run before `npx skills add`).
+if $PROGRAM_NAME == __FILE__
+  result = Clacky::ChannelSetup::LarkSkillsImporter.new.run
+  puts "[lark-import] copied=#{result[:copied]} errors=#{result[:errors].size}"
+  result[:errors].each { |e| warn "[lark-import] #{e}" }
+end

data/lib/clacky/default_skills/onboard/SKILL.md

@@ -55,7 +55,7 @@ Example (English):
 > Let's take 30 seconds to personalize your experience — I'll ask just a couple of quick things.
 
 Example (Chinese):
-> 嗨！我是你的专属小龙虾一号
+> 嗨！我是你的专属员工一号
 > 只需 30 秒完成个性化设置，我会问你两个简单问题。
 
 ### A.3. Ask the user to name the AI (card)

data/lib/clacky/default_skills/persist-memory/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: persist-memory
+description: Persist information to long-term memory at ~/.clacky/memories/. Use when the user asks you to remember/note something, or when reviewing a finished conversation for facts worth keeping. Handles file naming, topic merging, frontmatter, and size limits.
+fork_agent: true
+user-invocable: false
+auto_summarize: true
+forbidden_tools:
+  - web_search
+  - web_fetch
+  - browser
+---
+
+# Persist Memory Subagent
+
+You are a **Memory Persistence Subagent** — a pure executor. The caller has already decided that something must be written. Your job is to write it correctly: pick the right file, merge with existing content, respect the size limit.
+
+You do NOT decide whether to write. If the task description tells you to persist X, you persist X.
+
+## Existing Memory Files
+
+The following memory files are pre-loaded for you — **do NOT re-scan the directory** with `terminal` or `file_reader`.
+
+<%= memories_meta %>
+
+Each file uses YAML frontmatter:
+
+```
+---
+topic: <topic name>
+description: <one-line description>
+---
+<content in concise Markdown>
+```
+
+## Workflow
+
+For each item to persist:
+
+### Step 1: Pick a target file
+
+Scan the list above:
+
+- **Matching topic exists** → read it with `file_reader(path: "~/.clacky/memories/<filename>")`, integrate the new info, drop stale parts, then `write` the updated version back.
+- **No match** → create a new file at `~/.clacky/memories/<topic-slug>.md`.
+  - Slug: lowercase, hyphen-separated, descriptive (e.g. `deployment-target.md`, `code-style-preferences.md`).
+
+### Step 2: Write the file
+
+Use the `write` tool. Always include the YAML frontmatter shown above.
+
+## Hard constraints (CRITICAL)
+
+- Each file MUST stay under **4000 characters of content** (after the frontmatter).
+- If merging would exceed this limit, remove the least important information — do NOT split into multiple files for the same topic.
+- Write concise, factual Markdown — no fluff, no redundant headings.
+- One topic per file. Don't bundle unrelated facts together.
+- Do NOT use `terminal` or `file_reader` to list the memories directory — the list above is authoritative.
+
+When done, briefly state what was written (e.g. "Updated deployment-target.md") or `No memory updates needed.` if the task description didn't actually require any writes.

data/lib/clacky/providers.rb

@@ -146,12 +146,16 @@ module Clacky
         "default_model" => "kimi-k2.6",
         "models" => ["kimi-k2.6", "kimi-k2.5"],
         # Moonshot operates two regional endpoints with identical APIs & model
-        # lineup — mainland China (.cn) and international (.ai). Kimi does not
-        # distinguish pay-as-you-go vs coding-plan at the base_url level, so
-        # only two variants are needed. Listing both here lets find_by_base_url
-        # identify either one as provider "kimi", so downstream capability
-        # checks, fallback chains, and provider-specific behaviours work
-        # regardless of which endpoint the user configured.
+        # lineup — mainland China (.cn) and international (.ai). These are the
+        # pay-as-you-go Open Platform endpoints; the subscription-billed
+        # Coding Plan lives at api.kimi.com/coding with the unified
+        # `kimi-for-coding` model alias and is exposed as a separate
+        # top-level "kimi-coding" preset (different domain, distinct billing
+        # model, marketed by Moonshot as the standalone Kimi Code product).
+        # Listing both PAYG variants here lets find_by_base_url identify
+        # either one as provider "kimi", so downstream capability checks,
+        # fallback chains, and provider-specific behaviours work regardless
+        # of which endpoint the user configured.
         "endpoint_variants" => [
           { "label" => "Mainland China", "label_key" => "settings.models.baseurl.variant.mainland_cn",   "base_url" => "https://api.moonshot.cn/v1", "region" => "cn"   }.freeze,
           { "label" => "International",  "label_key" => "settings.models.baseurl.variant.international", "base_url" => "https://api.moonshot.ai/v1", "region" => "intl" }.freeze
@@ -161,6 +165,44 @@ module Clacky
         "website_url" => "https://platform.moonshot.cn/console/api-keys"
       }.freeze,
 
+      "kimi-coding" => {
+        "name" => "Kimi Code (Coding Plan)",
+        # Subscription-billed Kimi Code endpoint — separate product from the
+        # PAYG Moonshot Open Platform (api.moonshot.cn/v1 / .ai/v1). Uses the
+        # unified `kimi-for-coding` model alias which the Coding Plan backend
+        # routes to the appropriate K2 variant (Kimi-k2.6 today; 262K context,
+        # 32K max output, supports vision/video/reasoning).
+        #
+        # Why anthropic-messages: Moonshot exposes the Coding Plan via two
+        # URLs on the same domain — an Anthropic-format endpoint at
+        # api.kimi.com/coding/ (used by Claude Code via ANTHROPIC_BASE_URL)
+        # and an OpenAI-compatible endpoint at api.kimi.com/coding/v1 (used
+        # by Roo Code etc.). We route through anthropic-messages so
+        # cache_control fields round-trip byte-for-byte (the OpenAI shim is
+        # lossy for cache_control semantics — see OpenRouter preset above
+        # for the same reason). Verified against the live endpoint: response
+        # payload includes cache_creation_input_tokens / cache_read_input_tokens,
+        # so the cache layer is real on this backend.
+        #
+        # User-Agent gate: this endpoint enforces a UA-prefix whitelist
+        # limited to first-party coding agents (Kimi CLI, Claude Code, Roo
+        # Code, Kilo Code, ...). Requests carrying openclacky's default
+        # Faraday UA are rejected with HTTP 403 access_terminated_error.
+        # Client#anthropic_connection injects a Claude Code-shaped UA when
+        # @provider_id == "kimi-coding" — see the comment in client.rb for
+        # the policy rationale.
+        #
+        # Source: https://www.kimi.com/code/docs/third-party-tools/other-coding-agents.html
+        "base_url" => "https://api.kimi.com/coding",
+        "api" => "anthropic-messages",
+        "default_model" => "kimi-for-coding",
+        "models" => ["kimi-for-coding"],
+        # K2.6 backend behind the alias is multimodal (image + video input,
+        # reasoning). Same vision capability as the PAYG kimi preset.
+        "capabilities" => { "vision" => true }.freeze,
+        "website_url" => "https://www.kimi.com/code"
+      }.freeze,
+
       "anthropic" => {
         "name" => "Anthropic (Claude)",
         "base_url" => "https://api.anthropic.com",

data/lib/clacky/server/channel/adapters/weixin/adapter.rb

@@ -393,6 +393,13 @@ module Clacky
             @ctx_mutex.synchronize { @context_tokens[user_id] }
           end
 
+          # Return all user IDs for which we have a cached context_token.
+          # Used by ChannelManager#known_users so callers can enumerate
+          # users reachable for proactive messaging.
+          def context_token_user_ids
+            @ctx_mutex.synchronize { @context_tokens.keys.dup }
+          end
+
           # Split text into ≤2000 Unicode character chunks per iLink protocol recommendation.
           # Priority: split at \n\n, then \n, then space, then hard cut.
           def split_message(text, limit: 2000)

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

@@ -77,6 +77,74 @@ module Clacky
         @mutex.synchronize { @adapters.map(&:platform_id) }
       end
 
+      # Proactively send a message to a user on the given platform.
+      #
+      # For Weixin (iLink protocol) a context_token is required for every outbound
+      # message.  This method looks up the most-recently cached token for user_id.
+      # If no token is found the message cannot be delivered and nil is returned.
+      #
+      # For Feishu and WeCom the chat_id / user_id is sufficient — no token needed.
+      #
+      # @param platform [Symbol, String] e.g. :weixin, :feishu, :wecom
+      # @param user_id  [String]         IM user identifier
+      # @param message  [String]         plain-text (or markdown) message to send
+      # @return [Hash, nil]  adapter result hash, or nil on failure
+      def send_to_user(platform, user_id, message)
+        platform = platform.to_sym
+        adapter  = @mutex.synchronize { @adapters.find { |a| a.platform_id == platform } }
+
+        unless adapter
+          Clacky::Logger.warn("[ChannelManager] send_to_user: no running adapter for :#{platform}")
+          return nil
+        end
+
+        Clacky::Logger.info("[ChannelManager] send_to_user :#{platform} → #{user_id}")
+        adapter.send_text(user_id, message)
+      rescue StandardError => e
+        Clacky::Logger.error("[ChannelManager] send_to_user failed: #{e.message}")
+        nil
+      end
+
+      # Return a list of known user IDs for the given platform.
+      # Collected from every message that has been processed since the server started.
+      # Weixin stores context_tokens keyed by user_id; feishu/wecom track chat_ids
+      # via the session binding table in the registry.
+      #
+      # @param platform [Symbol, String]
+      # @return [Array<String>]
+      def known_users(platform)
+        platform = platform.to_sym
+        adapter  = @mutex.synchronize { @adapters.find { |a| a.platform_id == platform } }
+        return [] unless adapter
+
+        # Weixin adapter exposes @context_tokens whose keys are user_ids
+        if adapter.respond_to?(:context_token_user_ids)
+          return adapter.context_token_user_ids
+        end
+
+        # Fallback: scan session registry for channel_keys matching this platform.
+        # Key formats depend on binding_mode:
+        #   :user       → "platform:user:USER_ID"
+        #   :chat       → "platform:chat:CHAT_ID"
+        #   :chat_user  → "platform:chat:CHAT_ID:user:USER_ID"
+        #
+        # For send_text we need the chat_id (Feishu/WeCom use chat_id as the
+        # receive_id for outbound messages), so we extract the chat portion.
+        prefix = "#{platform}:"
+        ids = []
+        @registry.list.each do |summary|
+          @registry.with_session(summary[:id]) do |s|
+            (s[:channel_keys] || []).each do |key|
+              next unless key.start_with?(prefix)
+
+              remainder = key.sub(prefix, "") # e.g. "chat:OC_ID:user:OU_ID" or "user:UID" or "chat:CID"
+              ids << extract_chat_id(remainder)
+            end
+          end
+        end
+        ids.compact.uniq
+      end
+
       # Hot-reload a single platform adapter with updated config.
       # Stops the existing adapter (if running), then starts a new one if enabled.
       # @param platform [Symbol]
@@ -367,6 +435,29 @@ module Clacky
         end
       end
 
+      # Extract the chat_id from the remainder of a channel_key (after removing "platform:" prefix).
+      #
+      # Possible formats:
+      #   "chat:CHAT_ID:user:USER_ID"  → CHAT_ID  (chat_user mode)
+      #   "chat:CHAT_ID"               → CHAT_ID  (chat mode)
+      #   "user:USER_ID"               → USER_ID  (user mode — use user_id as fallback)
+      #
+      # For Feishu/WeCom send_text, the chat_id is what's needed as receive_id.
+      private def extract_chat_id(remainder)
+        if remainder.start_with?("chat:")
+          # "chat:CHAT_ID:user:USER_ID" or "chat:CHAT_ID"
+          after_chat = remainder.sub("chat:", "")
+          # If there's a ":user:" segment, strip it and everything after
+          idx = after_chat.index(":user:")
+          idx ? after_chat[0...idx] : after_chat
+        elsif remainder.start_with?("user:")
+          # user-only mode: no chat_id available, use user_id
+          remainder.sub("user:", "")
+        else
+          remainder
+        end
+      end
+
       def safe_stop_adapter(adapter)
         adapter.stop
       rescue StandardError => e

data/lib/clacky/server/discover.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require "socket"
+
+module Clacky
+  module Server
+    # Discover locally-running Clacky server(s) by scanning PID files
+    # written by Master at /tmp/clacky-master-<port>.pid.
+    #
+    # Used by the CLI (bare `clacky agent` mode) to auto-detect a sibling
+    # server process, so skills that call back into the server (channels,
+    # browser, scheduler, etc.) can work without the user manually setting
+    # CLACKY_SERVER_HOST / CLACKY_SERVER_PORT.
+    #
+    # Fast and side-effect free: only reads files and sends signal 0.
+    # Does NOT probe the TCP port (avoids false positives from stale files
+    # but also avoids noisy connection attempts).
+    module Discover
+      PID_FILE_GLOB = File.join(Dir.tmpdir, "clacky-master-*.pid").freeze
+      PID_FILE_REGEX = /clacky-master-(\d+)\.pid\z/.freeze
+
+      module_function
+
+      # Find the first live Clacky server on this machine.
+      #
+      # @return [Hash, nil] { host: "127.0.0.1", port: Integer, pid: Integer } or nil
+      def find_local
+        find_all_local.first
+      end
+
+      # Find all live Clacky servers on this machine.
+      #
+      # A PID file is considered "live" when:
+      #   1. The filename matches clacky-master-<port>.pid
+      #   2. Its contents parse as a positive integer
+      #   3. Process.kill(0, pid) confirms the PID is alive
+      #
+      # Stale PID files (process gone) are silently ignored. We do NOT
+      # delete them here — that's the owning server's responsibility.
+      #
+      # @return [Array<Hash>] sorted by port ascending
+      def find_all_local
+        Dir.glob(PID_FILE_GLOB).filter_map do |path|
+          m = path.match(PID_FILE_REGEX)
+          next nil unless m
+
+          port = m[1].to_i
+          next nil if port <= 0
+
+          pid_str = File.read(path).strip rescue nil
+          next nil if pid_str.nil? || pid_str.empty?
+
+          pid = pid_str.to_i
+          next nil if pid <= 0
+
+          next nil unless process_alive?(pid)
+
+          { host: "127.0.0.1", port: port, pid: pid }
+        end.sort_by { |e| e[:port] }
+      end
+
+      # @param pid [Integer]
+      # @return [Boolean]
+      def process_alive?(pid)
+        Process.kill(0, pid)
+        true
+      rescue Errno::ESRCH, Errno::EPERM
+        # ESRCH — no such process; EPERM — process exists but owned by someone else
+        # (still technically alive, but we can't safely assume it's "our" server)
+        false
+      rescue StandardError
+        false
+      end
+    end
+  end
+end