@tencent-ai/agent-sdk 0.3.99 → 0.3.100

package/cli/dist/web-ui/docs/en/cli/channels-reference.md

@@ -0,0 +1,293 @@
+# Channels Reference [Beta]
+
+> **Beta Feature**: Channels is currently in Beta. The protocol and interfaces may be adjusted based on feedback.
+
+A Channel is a special MCP server that pushes external events (webhooks, chat messages, monitoring alerts, etc.) into a CodeBuddy Code session, allowing CodeBuddy Code to react to things happening outside the terminal.
+
+## Overview
+
+A Channel runs on the same machine as CodeBuddy Code and communicates via stdio. CodeBuddy Code launches it as a child process.
+
+Typical use cases:
+
+- **Chat platforms** (Telegram, Discord): The plugin runs locally, polls the platform API for new messages, and forwards them to CodeBuddy Code
+- **Webhooks** (CI, monitoring): A server listens on a local HTTP port, receives POST requests from external systems, and pushes them to CodeBuddy Code
+
+Channels operate in two modes:
+
+| Mode | Description |
+|------|-------------|
+| One-way | Only forwards events to CodeBuddy Code (alerts, webhooks), processed in the local session |
+| Two-way | Additionally exposes a reply tool, allowing CodeBuddy Code to send responses |
+
+## Using a Channel
+
+### Startup
+
+Use the `--channels` parameter to specify which channels to load:
+
+```bash
+# Load a plugin-type channel
+codebuddy --channels plugin:fakechat@claude-plugins-official
+
+# Load a channel server configured in .mcp.json
+codebuddy --channels server:webhook
+
+# Load multiple channels (comma-separated)
+codebuddy --channels plugin:telegram@claude-plugins-official,plugin:discord@claude-plugins-official
+```
+
+### Development Mode
+
+Use the `--dangerously-load-development-channels` flag to test custom channels during initial development. This flag allows any channel to run without being on the allowlist:
+
+```bash
+codebuddy --dangerously-load-development-channels server:my-webhook
+```
+
+This flag only bypasses the allowlist check; the `channelsEnabled` organization policy still applies. Once a channel is submitted to the official marketplace and passes security review, it gets added to the allowlist and can be loaded directly with `--channels`.
+
+### Channel Messages in Sessions
+
+Channel messages are injected into CodeBuddy Code's context as `<channel>` tags:
+
+```xml
+<channel source="fakechat" sender="web" chat_id="1">Hello, can you help me look at this issue</channel>
+```
+
+In the TUI, channel messages are displayed in a friendly format:
+
+```
+#fakechat · web: Hello, can you help me look at this issue
+```
+
+### Settings
+
+Channel functionality can be controlled in `settings.json`:
+
+```json
+{
+  "channelsEnabled": true
+}
+```
+
+Set to `false` to completely disable channel functionality.
+
+## Building a Channel
+
+### Basic Requirements
+
+A channel server needs to:
+
+1. Declare the `claude/channel` capability so CodeBuddy Code registers a notification listener
+2. Send `notifications/claude/channel` events
+3. Connect via stdio transport (CodeBuddy Code launches it as a child process)
+
+### Minimal Example: Webhook Receiver
+
+```ts
+#!/usr/bin/env bun
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+
+const mcp = new Server(
+  { name: 'webhook', version: '0.0.1' },
+  {
+    capabilities: { experimental: { 'claude/channel': {} } },
+    instructions: 'Events from webhook arrive as <channel source="webhook" ...> tags. One-way channel, just read and process.',
+  },
+)
+
+await mcp.connect(new StdioServerTransport())
+
+Bun.serve({
+  port: 8788,
+  hostname: '127.0.0.1',
+  async fetch(req) {
+    const body = await req.text()
+    await mcp.notification({
+      method: 'notifications/claude/channel',
+      params: {
+        content: body,
+        meta: { path: new URL(req.url).pathname, method: req.method },
+      },
+    })
+    return new Response('ok')
+  },
+})
+```
+
+Register in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "webhook": { "command": "bun", "args": ["./webhook.ts"] }
+  }
+}
+```
+
+## Server Configuration Options
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `capabilities.experimental['claude/channel']` | `object` | **Required**. Always `{}`. Once declared, CodeBuddy Code registers a notification listener |
+| `capabilities.experimental['claude/channel/permission']` | `object` | Optional. Always `{}`. Declares that this channel can receive permission relay requests |
+| `capabilities.tools` | `object` | Required for two-way channels. Always `{}`. Standard MCP tool capability |
+| `instructions` | `string` | Recommended. Injected into the system prompt, telling CodeBuddy Code how to handle events from this channel |
+
+## Notification Format
+
+When sending `notifications/claude/channel` notifications, params contains two fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `content` | `string` | Event content, becomes the body of the `<channel>` tag |
+| `meta` | `Record<string, string>` | Optional. Each key-value pair becomes an attribute of the `<channel>` tag. Key names only allow letters, numbers, and underscores; keys containing hyphens or other characters are silently discarded |
+
+Example:
+
+```ts
+await mcp.notification({
+  method: 'notifications/claude/channel',
+  params: {
+    content: 'build failed on main',
+    meta: { severity: 'high', run_id: '1234' },
+  },
+})
+```
+
+Format when arriving at CodeBuddy Code:
+
+```xml
+<channel source="webhook" severity="high" run_id="1234">
+build failed on main
+</channel>
+```
+
+## Exposing a Reply Tool
+
+Two-way channels need to expose standard MCP tools for CodeBuddy Code to reply to messages:
+
+```ts
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+
+mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [{
+    name: 'reply',
+    description: 'Send a reply message through this channel',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        chat_id: { type: 'string', description: 'The conversation ID to reply to' },
+        text: { type: 'string', description: 'The message to send' },
+      },
+      required: ['chat_id', 'text'],
+    },
+  }],
+}))
+
+mcp.setRequestHandler(CallToolRequestSchema, async req => {
+  if (req.params.name === 'reply') {
+    const { chat_id, text } = req.params.arguments as { chat_id: string; text: string }
+    // Call your chat platform API to send the message
+    await sendToPlatform(chat_id, text)
+    return { content: [{ type: 'text', text: 'sent' }] }
+  }
+  throw new Error(`unknown tool: ${req.params.name}`)
+})
+```
+
+## Sender Security Controls
+
+An unprotected channel is a prompt injection attack vector. Anyone who can reach your endpoint can inject text into CodeBuddy Code.
+
+Before calling `mcp.notification()`, you must verify the sender's identity:
+
+```ts
+const allowed = new Set(loadAllowlist())
+
+// In the message handler, before sending the notification:
+if (!allowed.has(message.from.id)) {  // Check sender ID, not group ID
+  return  // Silently discard
+}
+await mcp.notification({ ... })
+```
+
+**Important**: Always validate based on sender identity (`message.from.id`) rather than chat room identity (`message.chat.id`). In group chats, these two values differ, and validating by group would allow anyone in the group to inject messages into the session.
+
+## Permission Relay
+
+When CodeBuddy Code calls a tool that requires approval (such as `Bash`, `Write`, `Edit`), the local terminal opens a permission dialog. Two-way channels can optionally receive this prompt as well, allowing you to approve or deny from a remote device.
+
+Both the local terminal and remote channel dialogs open simultaneously. **The first response wins**, and the other is automatically dismissed.
+
+### Enabling Permission Relay
+
+Add `claude/channel/permission` in the Server constructor:
+
+```ts
+capabilities: {
+  experimental: {
+    'claude/channel': {},
+    'claude/channel/permission': {},  // Enable permission relay
+  },
+  tools: {},
+},
+```
+
+### Permission Request Fields
+
+CodeBuddy Code sends `notifications/claude/channel/permission_request` with the following fields:
+
+| Field | Description |
+|-------|-------------|
+| `request_id` | 5 lowercase letters (excluding `l`), used to match replies |
+| `tool_name` | The tool CodeBuddy Code wants to use, e.g., `Bash`, `Write` |
+| `description` | Human-readable description of the tool call |
+| `input_preview` | JSON string of tool parameters, truncated to 200 characters |
+
+### Sending a Verdict
+
+Your channel needs to send a `notifications/claude/channel/permission` notification:
+
+```ts
+await mcp.notification({
+  method: 'notifications/claude/channel/permission',
+  params: {
+    request_id: '<received request_id>',
+    behavior: 'allow',  // or 'deny'
+  },
+})
+```
+
+### Handling Inbound Verdicts
+
+In your inbound message handler, recognize replies in the format `yes <id>` or `no <id>`:
+
+```ts
+// Match "y abcde", "yes abcde", "n abcde", "no abcde"
+// [a-km-z] is the ID alphabet used by CodeBuddy Code (lowercase, skipping 'l')
+const PERMISSION_REPLY_RE = /^\s*(y|yes|n|no)\s+([a-km-z]{5})\s*$/i
+
+const m = PERMISSION_REPLY_RE.exec(message.text)
+if (m) {
+  await mcp.notification({
+    method: 'notifications/claude/channel/permission',
+    params: {
+      request_id: m[2].toLowerCase(),
+      behavior: m[1].toLowerCase().startsWith('y') ? 'allow' : 'deny',
+    },
+  })
+  return  // Handled as a verdict, not forwarded as chat
+}
+```
+
+## Packaging as a Plugin
+
+Wrapping a channel as a plugin makes it easy to share and install. Users install via `/plugin install`, then enable with `--channels plugin:<name>@<marketplace>`.
+
+## References
+
+- [fakechat example](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/fakechat): A complete two-way channel implementation with Web UI, file attachments, and reply tool
+- [MCP Protocol](https://modelcontextprotocol.io): Channels are built on the MCP protocol

package/cli/dist/web-ui/docs/en/cli/channels.md

@@ -0,0 +1,215 @@
+# Channels: Push External Events into Sessions [Beta]
+
+> **Beta Feature**: Channels is currently in Beta. Features and interfaces may be adjusted based on feedback.
+
+A Channel is an MCP server that pushes messages, alerts, and webhooks into your running CodeBuddy Code session, allowing CodeBuddy Code to react to external events even when you're not at the terminal.
+
+Channels can be two-way: CodeBuddy Code reads events and replies through the same channel, acting like a chat bridge. Events only arrive while a session is open; for continuous operation, run CodeBuddy Code in a background process or persistent terminal.
+
+You can enable channels by installing plugins or using built-in channels. WeChat, Telegram, Discord, and the fakechat demo are all supported.
+
+When CodeBuddy Code replies through a channel, the terminal shows the tool call and confirmation (e.g., "sent"), while the actual reply content appears on the corresponding chat platform.
+
+This page covers:
+
+* [Supported Channels](#supported-channels): WeChat, Telegram, Discord, and fakechat setup
+* [Quick Start](#quick-start): Quick hands-on experience with the WeChat channel
+* [Security](#security): Sender allowlists and pairing flows
+* [Organization Controls](#organization-controls): Enabling channels for teams and enterprises
+* [Feature Comparison](#feature-comparison)
+
+To build your own channel, see the [Channels Reference](./channels-reference.md).
+
+## Supported Channels
+
+### WeChat (Built-in)
+
+The WeChat channel is built into CodeBuddy Code and requires no plugin installation. It enables two-way messaging through WeChat ClawBot, supporting text, images, and file exchange.
+
+**Prerequisites**:
+- WeChat version iOS 8.0.70 or above
+- Enable the ClawBot plugin in WeChat (WeChat > Me > Settings > Plugins > ClawBot)
+
+**QR Code Binding**:
+
+1. In CodeBuddy Code, run `/remote-control wechat` or `/remote-control` and select wechat
+2. The terminal displays a QR code (if the QR code doesn't render correctly, a browser link will be provided)
+3. Scan the QR code with WeChat and confirm
+4. After successful binding, message reception starts automatically
+
+**Usage**:
+
+After binding, send messages in the WeChat ClawBot conversation, and they will automatically appear in the CodeBuddy Code session:
+
+```
+#wechat · user_id: Hello, help me look at this bug
+```
+
+CodeBuddy Code processes the message and replies via the `WechatReply` tool, with the reply appearing in WeChat.
+
+Supported message types:
+
+| Type | Receive | Send |
+|------|---------|------|
+| Text | Supported | Supported |
+| Image | Supported (auto-downloaded and decrypted locally) | Supported (auto-encrypted and uploaded to CDN) |
+| File | Supported | Supported |
+
+**Credential Management**:
+
+After successful QR code scanning, credentials are saved to `~/.codebuddy/channels/wechat/credentials.json`. On next startup, saved credentials are used automatically without re-scanning.
+
+```bash
+# Check connection status
+/remote-control wechat status
+
+# Disconnect
+/remote-control wechat stop
+
+# Reconnect (using saved credentials)
+/remote-control wechat start
+```
+
+### Telegram
+
+Requires plugin installation. See the full [Telegram plugin source](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram).
+
+1. Create a bot via [BotFather](https://t.me/BotFather) in Telegram and obtain a token
+2. Install the plugin: `/plugin install telegram@claude-plugins-official`
+3. Configure the token: `/telegram:configure <token>`
+4. Start: `codebuddy --channels plugin:telegram@claude-plugins-official`
+5. Send a message to the bot to get a pairing code, then run `/telegram:access pair <code>` to complete pairing
+
+### Discord
+
+Requires plugin installation. See the full [Discord plugin source](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/discord).
+
+1. Create an application and bot in the [Discord Developer Portal](https://discord.com/developers/applications)
+2. Enable Message Content Intent and invite the bot to your server
+3. Install the plugin: `/plugin install discord@claude-plugins-official`
+4. Configure the token: `/discord:configure <token>`
+5. Start: `codebuddy --channels plugin:discord@claude-plugins-official`
+6. DM the bot to get a pairing code, then run `/discord:access pair <code>` to complete pairing
+
+### fakechat (Demo)
+
+fakechat is an officially supported demo channel that runs a chat UI on localhost, requiring no authentication or external services.
+
+```bash
+# Install
+/plugin install fakechat@claude-plugins-official
+
+# Start
+codebuddy --channels plugin:fakechat@claude-plugins-official
+```
+
+Open `http://localhost:8787` to start chatting.
+
+## Quick Start
+
+Using the WeChat channel as an example, here's a quick walkthrough of the full two-way communication flow:
+
+**Step 1: Ensure ClawBot is Enabled**
+
+In WeChat, go to **Me > Settings > Plugins**, find ClawBot and enable it.
+
+**Step 2: QR Code Binding**
+
+Start CodeBuddy Code and run:
+
+```
+/remote-control wechat
+```
+
+The terminal displays a QR code. Scan it with WeChat and confirm the binding.
+
+**Step 3: Send a Message**
+
+In the WeChat ClawBot conversation, send:
+
+```
+Help me check what files are in the current directory
+```
+
+The message arrives in the CodeBuddy Code session, displayed as:
+
+```
+#wechat · user_id: Help me check what files are in the current directory
+```
+
+CodeBuddy Code executes the task and replies via the `WechatReply` tool, with the reply appearing in WeChat.
+
+**Step 4: Send an Image**
+
+Send a screenshot to ClawBot in WeChat. CodeBuddy Code will automatically download and recognize the image content. You can ask it to edit the image and send it back:
+
+```
+Add a hat to the person in the image
+```
+
+CodeBuddy Code uses the ImageEdit tool to process the image, then sends the edited image back to WeChat via `WechatReply`.
+
+## Security
+
+### WeChat
+
+The WeChat channel ensures security through ClawBot's QR code authentication mechanism. Only the WeChat account that completed the QR code binding can send messages; messages from others are silently discarded.
+
+Credentials (containing bot_token and account_id) are saved locally with permissions set to 600 (owner read/write only).
+
+### Plugin Channels
+
+Plugin channels like Telegram and Discord maintain a sender allowlist. Trusted senders are added through a pairing flow:
+
+1. Send any message to the bot
+2. The bot replies with a pairing code
+3. Confirm the pairing code in CodeBuddy Code
+4. The sender's ID is added to the allowlist
+
+The allowlist also controls [permission relay](./channels-reference.md#permission-relay). People who reply through a channel can approve or deny tool calls, so only add trusted senders to the allowlist.
+
+### Other Security Considerations
+
+- Configuring in `.mcp.json` alone is not sufficient to push messages; the channel must also be specified in `--channels`
+- Organizations can enforce unified controls via the `channelsEnabled` setting
+
+## Organization Controls
+
+Channel functionality is controlled by the `channelsEnabled` setting:
+
+| Plan Type | Default Behavior |
+|-----------|-----------------|
+| Individual users | Available; users enable per-session via `--channels` |
+| Team/Enterprise | Disabled by default; admins must explicitly enable |
+
+### Enabling Channels for Organizations
+
+Admins can set this in `settings.json`:
+
+```json
+{
+  "channelsEnabled": true
+}
+```
+
+Once enabled, users in the organization can use `--channels` to connect channel servers to their sessions. If the setting is disabled, MCP servers still connect and tools remain available, but channel messages will not arrive.
+
+## Feature Comparison
+
+CodeBuddy Code has multiple features for connecting to external systems, each suited to different scenarios:
+
+| Feature | Purpose | Use Case |
+|---------|---------|----------|
+| Standard MCP Server | CodeBuddy Code queries it during tasks; does not push to session | On-demand reading or querying systems |
+| Remote Control | Control a local session from remote | Operating an active session when away from your desk |
+| **Channel** | **Pushes external events into a running local session** | **Chat bridges, webhook reception, alert response** |
+
+Channels fill the gap by pushing events from non-CodeBuddy Code sources into a running local session:
+
+* **Chat bridge**: Ask CodeBuddy Code questions via WeChat, with answers appearing in WeChat, while the actual work runs on your machine using your real files
+* **Webhook receiver**: When webhooks from CI, error trackers, or deployment pipelines arrive, CodeBuddy Code already has your files open and remembers what you were debugging
+
+## Next Steps
+
+* [Build your own Channel](./channels-reference.md): Create a channel for systems that don't have a plugin yet
+* Use `/remote-control` to manage all remote control connections

package/cli/dist/web-ui/docs/en/cli/checkpointing.md

@@ -0,0 +1,53 @@
+# Checkpointing (Beta)
+
+> ⚠️ **Beta Feature**: Checkpointing is currently in Beta and features may change.
+
+## Overview
+
+Automatically track and rewind CodeBuddy edits to quickly restore unwanted changes.
+
+CodeBuddy Code automatically tracks CodeBuddy's edits to files as you work, allowing you to quickly undo changes and revert to a previous state if something goes wrong.
+
+
+## Common Use Cases
+
+Checkpointing is particularly useful in these scenarios:
+
+- **Exploring Alternatives**: Try different implementation approaches without losing your starting point
+- **Recovering from Errors**: Quickly undo changes that introduced bugs or broke functionality
+- **Feature Iteration**: Confidently experiment knowing you can always restore to a working state
+
+---
+
+## Limitations
+
+### Changes via Bash Commands Are Not Tracked
+
+Checkpointing does not track files modified through bash commands. For example, if CodeBuddy Code runs:
+
+```
+rm file.txt
+mv old.txt new.txt
+cp source.txt dest.txt
+```
+
+These file modifications cannot be undone via the rewind feature. Only edits made directly through CodeBuddy's file editing tools are tracked.
+
+### External Changes Are Not Tracked
+
+Checkpointing only tracks files edited in the current session. Manual changes you make to files outside of CodeBuddy Code, and edits from other concurrent sessions, are typically not captured unless they happen to modify the same files as your current session.
+
+### Not a Replacement for Version Control
+
+Checkpointing is designed for quick session-level recovery. For permanent version history and collaboration:
+
+- Continue using version control (like Git) to manage commits, branches, and long-term history
+- Checkpointing complements version control rather than replacing it
+- Think of checkpointing as "local undo" and Git as "permanent history"
+
+---
+
+## See Also
+
+- **[Interactive Mode](interactive-mode.md)** - Keyboard shortcuts and session control
+- **[Slash Commands](slash-commands.md)** - Use `/rewind` to access checkpoints