feat: integrate Feishu bridge runtime with card-based approval flow

.gitignore

@@ -3,3 +3,7 @@ node_modules/
 .DS_Store
 npm-debug.log*
 .codex-telegram-claws-state.json
+bridge/claude-to-im/dist/
+bridge/claude-to-im/config.env
+bridge/claude-to-im/.env
+bridge/claude-to-im/.env.*

README.md

@@ -125,6 +125,21 @@ Development mode:
 npm run dev
 ```
 
+### Feishu Bridge (Card Permission Approval)
+
+This repo now vendors a full `claude-to-im` runtime under `bridge/claude-to-im`,
+so you can run Feishu with card-based permission approval flow from this project.
+Default bridge home is isolated at `~/.codexclaw-bridge` to avoid conflicts with existing standalone `claude-to-im` installs.
+
+```bash
+npm run feishu:setup
+npm run feishu:install
+npm run feishu:start
+npm run feishu:status
+```
+
+More details: `docs/feishu-bridge.md`
+
 Validation:
 
 ```bash

bridge/claude-to-im/.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+*.tgz
+.env
+config.env

bridge/claude-to-im/CLAUDE.md

@@ -0,0 +1,20 @@
+# CLAUDE.md — Project Guidelines for claude-to-im-skill
+
+## Replying to GitHub Issues
+
+When replying to user-reported issues, always include a **self-help prompt** at the end of the reply. Guide users to use their AI coding assistant (Claude Code / Codex) to diagnose and fix the problem themselves. Example:
+
+> **自助排查提示：** 你可以直接在 Claude Code（或 Codex）中发送以下提示，让 AI 帮你诊断问题：
+>
+> ```
+> 请帮我排查 claude-to-im 桥接服务的问题。
+> 1. 读取 ~/.claude-to-im/logs/bridge.log 最近 50 行日志
+> 2. 读取 ~/.claude-to-im/config.env 检查配置是否正确
+> 3. 运行 bash ~/.claude/skills/claude-to-im/scripts/doctor.sh 并分析输出
+> 4. 根据日志和配置给出具体的修复建议
+> ```
+
+This approach:
+- Reduces maintainer burden by enabling users to self-diagnose
+- Leverages the fact that users already have an AI coding assistant installed
+- Provides actionable next steps rather than just error explanations

bridge/claude-to-im/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 op7418
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bridge/claude-to-im/README.md

@@ -0,0 +1,255 @@
+# Claude-to-IM Skill
+
+Bridge Claude Code / Codex to IM platforms — chat with AI coding agents from Telegram, Discord, Feishu/Lark, or QQ.
+
+[中文文档](README_CN.md)
+
+> **Want a desktop GUI instead?** Check out [CodePilot](https://github.com/op7418/CodePilot) — a full-featured desktop app with visual chat interface, session management, file tree preview, permission controls, and more. This skill was extracted from CodePilot's IM bridge module for users who prefer a lightweight, CLI-only setup.
+
+---
+
+## How It Works
+
+This skill runs a background daemon that connects your IM bots to Claude Code or Codex sessions. Messages from IM are forwarded to the AI coding agent, and responses (including tool use, permission requests, streaming previews) are sent back to your chat.
+
+```
+You (Telegram/Discord/Feishu/QQ)
+  ↕ Bot API
+Background Daemon (Node.js)
+  ↕ Claude Agent SDK or Codex SDK (configurable via CTI_RUNTIME)
+Claude Code / Codex → reads/writes your codebase
+```
+
+## Features
+
+- **Four IM platforms** — Telegram, Discord, Feishu/Lark, QQ — enable any combination
+- **Interactive setup** — guided wizard collects tokens with step-by-step instructions
+- **Permission control** — tool calls require explicit approval via inline buttons (Telegram/Discord) or text `/perm` commands (Feishu/QQ)
+- **Streaming preview** — see Claude's response as it types (Telegram & Discord)
+- **Session persistence** — conversations survive daemon restarts
+- **Secret protection** — tokens stored with `chmod 600`, auto-redacted in all logs
+- **Zero code required** — install the skill and run `/claude-to-im setup`, that's it
+
+## Prerequisites
+
+- **Node.js >= 20**
+- **Claude Code CLI** (for `CTI_RUNTIME=claude` or `auto`) — installed and authenticated (`claude` command available)
+- **Codex CLI** (for `CTI_RUNTIME=codex` or `auto`) — `npm install -g @openai/codex`. Auth: run `codex auth login`, or set `OPENAI_API_KEY` (optional, for API mode)
+
+## Installation
+
+### npx skills (recommended)
+
+```bash
+npx skills add op7418/Claude-to-IM-skill
+```
+
+### Git clone
+
+```bash
+git clone https://github.com/op7418/Claude-to-IM-skill.git ~/.claude/skills/claude-to-im
+```
+
+Clones the repo directly into your personal skills directory. Claude Code discovers it automatically.
+
+### Symlink
+
+If you prefer to keep the repo elsewhere (e.g., for development):
+
+```bash
+git clone https://github.com/op7418/Claude-to-IM-skill.git ~/code/Claude-to-IM-skill
+mkdir -p ~/.claude/skills
+ln -s ~/code/Claude-to-IM-skill ~/.claude/skills/claude-to-im
+```
+
+### Codex
+
+If you use [Codex](https://github.com/openai/codex), clone directly into the Codex skills directory:
+
+```bash
+git clone https://github.com/op7418/Claude-to-IM-skill.git ~/.codex/skills/claude-to-im
+```
+
+Or use the provided install script for automatic dependency installation and build:
+
+```bash
+# Clone and install (copy mode)
+git clone https://github.com/op7418/Claude-to-IM-skill.git ~/code/Claude-to-IM-skill
+bash ~/code/Claude-to-IM-skill/scripts/install-codex.sh
+
+# Or use symlink mode for development
+bash ~/code/Claude-to-IM-skill/scripts/install-codex.sh --link
+```
+
+### Verify installation
+
+**Claude Code:** Start a new session and type `/` — you should see `claude-to-im` in the skill list. Or ask Claude: "What skills are available?"
+
+**Codex:** Start a new session and say "claude-to-im setup" or "start bridge" — Codex will recognize the skill and run the setup wizard.
+
+## Quick Start
+
+### 1. Setup
+
+```
+/claude-to-im setup
+```
+
+The wizard will guide you through:
+
+1. **Choose channels** — pick Telegram, Discord, Feishu, QQ, or any combination
+2. **Enter credentials** — the wizard explains exactly where to get each token, which settings to enable, and what permissions to grant
+3. **Set defaults** — working directory, model, and mode
+4. **Validate** — tokens are verified against platform APIs immediately
+
+### 2. Start
+
+```
+/claude-to-im start
+```
+
+The daemon starts in the background. You can close the terminal — it keeps running.
+
+### 3. Chat
+
+Open your IM app and send a message to your bot. Claude Code will respond.
+
+When Claude needs to use a tool (edit a file, run a command), you'll see a permission prompt with **Allow** / **Deny** buttons right in the chat (Telegram/Discord), or a text `/perm` command prompt (Feishu/QQ).
+
+## Commands
+
+All commands are run inside Claude Code or Codex:
+
+| Claude Code | Codex (natural language) | Description |
+|---|---|---|
+| `/claude-to-im setup` | "claude-to-im setup" / "配置" | Interactive setup wizard |
+| `/claude-to-im start` | "start bridge" / "启动桥接" | Start the bridge daemon |
+| `/claude-to-im stop` | "stop bridge" / "停止桥接" | Stop the bridge daemon |
+| `/claude-to-im status` | "bridge status" / "状态" | Show daemon status |
+| `/claude-to-im logs` | "查看日志" | Show last 50 log lines |
+| `/claude-to-im logs 200` | "logs 200" | Show last 200 log lines |
+| `/claude-to-im reconfigure` | "reconfigure" / "修改配置" | Update config interactively |
+| `/claude-to-im doctor` | "doctor" / "诊断" | Diagnose issues |
+
+## Platform Setup Guides
+
+The `setup` wizard provides inline guidance for every step. Here's a summary:
+
+### Telegram
+
+1. Message `@BotFather` on Telegram → `/newbot` → follow prompts
+2. Copy the bot token (format: `123456789:AABbCc...`)
+3. Recommended: `/setprivacy` → Disable (for group use)
+4. Find your User ID: message `@userinfobot`
+
+### Discord
+
+1. Go to [Discord Developer Portal](https://discord.com/developers/applications) → New Application
+2. Bot tab → Reset Token → copy it
+3. Enable **Message Content Intent** under Privileged Gateway Intents
+4. OAuth2 → URL Generator → scope `bot` → permissions: Send Messages, Read Message History, View Channels → copy invite URL
+
+### Feishu / Lark
+
+1. Go to [Feishu Open Platform](https://open.feishu.cn/app) (or [Lark](https://open.larksuite.com/app))
+2. Create Custom App → get App ID and App Secret
+3. **Batch-add permissions**: go to "Permissions & Scopes" → use batch configuration to add all required scopes (the `setup` wizard provides the exact JSON)
+4. Enable Bot feature under "Add Features"
+5. **Events & Callbacks**: select **"Long Connection"** as event dispatch method → add `im.message.receive_v1` event
+6. **Publish**: go to "Version Management & Release" → create version → submit for review → approve in Admin Console
+7. **Important**: The bot will NOT work until the version is approved and published
+
+### QQ
+
+> QQ currently supports **C2C private chat only**. No group/channel support, no inline permission buttons, no streaming preview. Permissions use text `/perm ...` commands. Image inbound only (no image replies).
+
+1. Go to [QQ Bot OpenClaw](https://q.qq.com/qqbot/openclaw)
+2. Create a QQ Bot or select an existing one → get **App ID** and **App Secret** (only two required fields)
+3. Configure sandbox access and scan QR code with QQ to add the bot
+4. `CTI_QQ_ALLOWED_USERS` takes `user_openid` values (not QQ numbers) — can be left empty initially
+5. Set `CTI_QQ_IMAGE_ENABLED=false` if the underlying provider doesn't support image input
+
+## Architecture
+
+```
+~/.claude-to-im/
+├── config.env             ← Credentials & settings (chmod 600)
+├── data/                  ← Persistent JSON storage
+│   ├── sessions.json
+│   ├── bindings.json
+│   ├── permissions.json
+│   └── messages/          ← Per-session message history
+├── logs/
+│   └── bridge.log         ← Auto-rotated, secrets redacted
+└── runtime/
+    ├── bridge.pid          ← Daemon PID file
+    └── status.json         ← Current status
+```
+
+### Key components
+
+| Component | Role |
+|---|---|
+| `src/main.ts` | Daemon entry — assembles DI, starts bridge |
+| `src/config.ts` | Load/save `config.env`, map to bridge settings |
+| `src/store.ts` | JSON file BridgeStore (30 methods, write-through cache) |
+| `src/llm-provider.ts` | Claude Agent SDK `query()` → SSE stream |
+| `src/codex-provider.ts` | Codex SDK `runStreamed()` → SSE stream |
+| `src/sse-utils.ts` | Shared SSE formatting helper |
+| `src/permission-gateway.ts` | Async bridge: SDK `canUseTool` ↔ IM buttons |
+| `src/logger.ts` | Secret-redacted file logging with rotation |
+| `scripts/daemon.sh` | Process management (start/stop/status/logs) |
+| `scripts/doctor.sh` | Health checks |
+| `SKILL.md` | Claude Code skill definition |
+
+### Permission flow
+
+```
+1. Claude wants to use a tool (e.g., Edit file)
+2. SDK calls canUseTool() → LLMProvider emits permission_request SSE
+3. Bridge sends inline buttons to IM chat: [Allow] [Deny]
+4. canUseTool() blocks, waiting for user response (5 min timeout)
+5. User taps Allow → bridge resolves the pending permission
+6. SDK continues tool execution → result streamed back to IM
+```
+
+## Troubleshooting
+
+Run diagnostics:
+
+```
+/claude-to-im doctor
+```
+
+This checks: Node.js version, config file existence and permissions, token validity (live API calls), log directory, PID file consistency, and recent errors.
+
+| Issue | Solution |
+|---|---|
+| `Bridge won't start` | Run `doctor`. Check if Node >= 20. Check logs. |
+| `Messages not received` | Verify token with `doctor`. Check allowed users config. |
+| `Permission timeout` | User didn't respond within 5 min. Tool call auto-denied. |
+| `Stale PID file` | Run `stop` then `start`. daemon.sh auto-cleans stale PIDs. |
+
+See [references/troubleshooting.md](references/troubleshooting.md) for more details.
+
+## Security
+
+- All credentials stored in `~/.claude-to-im/config.env` with `chmod 600`
+- Tokens are automatically redacted in all log output (pattern-based masking)
+- Allowed user/channel/guild lists restrict who can interact with the bot
+- The daemon is a local process with no inbound network listeners
+- See [SECURITY.md](SECURITY.md) for threat model and incident response
+
+## Development
+
+```bash
+npm install        # Install dependencies
+npm run dev        # Run in dev mode
+npm run typecheck  # Type check
+npm test           # Run tests
+npm run build      # Build bundle
+```
+
+## License
+
+[MIT](LICENSE)