xabot-cli 1.4.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 drodreo
+
+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.

package/README.md

@@ -0,0 +1,126 @@
+**[中文文档](README.zh-CN.md)**
+
+# xabot
+
+Bidirectional message bridge connecting XACPP-enabled Agents to Feishu and WeChat.
+
+```
+Cloud IM (Feishu / WeChat) ←→ xabot ←→ Agent (XACPP)
+```
+
+xabot is the **XACPP Responder** — it passively accepts establish requests from downstream XACPP Initiators and routes messages to/from cloud IM platforms. xabot only works with [XACPP-compatible](#xacpp-protocol) peers.
+
+## Install
+
+```bash
+npm install -g xabot
+```
+
+Or build from source:
+
+```bash
+git clone https://github.com/drodreo/xabot.git
+cd xabot
+npm install
+npm run build
+npm install -g .
+```
+
+## Usage
+
+CLI is organized by platform subcommands:
+
+```
+xabot feishu --app-id <ID> --app-secret <SECRET> <action>
+xabot wechat <action>
+```
+
+### Actions
+
+| Action | Lifecycle | Description |
+|--------|-----------|-------------|
+| `health` | One-shot | Verify credentials and connectivity |
+| `run` | Long-running | Production: stdio ↔ platform bidirectional bridge |
+| `chat` | Long-running | Interactive debug: terminal ↔ Agent ↔ platform |
+
+### Feishu
+
+```bash
+# Health check
+xabot feishu --app-id <ID> --app-secret <SECRET> health
+
+# Production bridge
+xabot feishu --app-id <ID> --app-secret <SECRET> run
+
+# Interactive chat
+xabot feishu --app-id <ID> --app-secret <SECRET> chat
+```
+
+### WeChat
+
+```bash
+# Health check (requires a previously obtained token)
+xabot wechat health --token <TOKEN>
+
+# Production bridge (auto QR-code login on first start)
+xabot wechat run
+
+# Interactive chat
+xabot wechat chat
+
+# Reconnect with existing credentials
+xabot wechat chat --credentials <CREDENTIALS>
+```
+
+### chat Terminal Commands
+
+In `chat` mode, text input is parsed into commands or plain messages:
+
+| Input | Action |
+|-------|--------|
+| Plain text | Send to Agent as `invoke_activity` |
+| `/new [prompt]` | Create a new Activity |
+| `/compact` | Compress current Activity context |
+| `/cancel` | Cancel current Activity |
+
+## Development
+
+```bash
+npm install
+npm run build    # Compile TypeScript → dist/
+npm test         # Run all tests (vitest)
+```
+
+## Architecture
+
+```
+xabot/
+├── src/
+│   ├── core/            # Platform client interface, types, pairing
+│   ├── xacpp/           # XACPP EstablishHandler & SessionHandler
+│   ├── platforms/
+│   │   ├── feishu/      # Feishu client (WebSocket)
+│   │   └── wechat/      # WeChat client (HTTP long-polling)
+│   ├── bridge/          # Bidirectional message routing: cloud ↔ XACPP
+│   └── cli/             # CLI entry point & subcommands (commander)
+```
+
+Key design points:
+- **No persistence** — credentials are passed via CLI arguments
+- **chatId via Establish handshake** — obtained dynamically, no hardcoded IDs
+- **Activity ↔ chatId** — each chatId maps to exactly one XACPP activity
+
+## XACPP Protocol
+
+xabot implements the Responder side of the XACPP (eXtensible Agent Control Plane Protocol). The downstream Agent connects as the Initiator.
+
+Protocol SDKs:
+
+| SDK | Language | Repository |
+|-----|----------|------------|
+| xacpp-ts | TypeScript | https://github.com/drodreo/xacpp-ts |
+| xacpp-rs | Rust | https://github.com/drodreo/xacpp-rs |
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,126 @@
+**[English](README.md)**
+
+# xabot
+
+连接 XACPP Agent 与飞书、微信的双向消息桥接工具。
+
+```
+云端 IM（飞书 / 微信）←→ xabot ←→ Agent (XACPP)
+```
+
+xabot 是 **XACPP Responder** — 被动接受下游 XACPP Initiator 的 establish 请求，在云端 IM 平台与 Agent 之间路由消息。xabot 仅兼容 [XACPP 协议](#xacpp-协议)对等端。
+
+## 安装
+
+```bash
+npm install -g xabot
+```
+
+或从源码构建：
+
+```bash
+git clone https://github.com/drodreo/xabot.git
+cd xabot
+npm install
+npm run build
+npm install -g .
+```
+
+## 使用
+
+CLI 按平台组织为子命令：
+
+```
+xabot feishu --app-id <ID> --app-secret <SECRET> <action>
+xabot wechat <action>
+```
+
+### 命令
+
+| 命令 | 生命周期 | 说明 |
+|------|---------|------|
+| `health` | 单次 | 验证凭证与连通性 |
+| `run` | 长连接 | 正式模式：stdio ↔ 平台双向桥接 |
+| `chat` | 长连接 | 交互调试：终端 ↔ Agent ↔ 平台 |
+
+### 飞书
+
+```bash
+# 健康检查
+xabot feishu --app-id <ID> --app-secret <SECRET> health
+
+# 正式桥接
+xabot feishu --app-id <ID> --app-secret <SECRET> run
+
+# 交互式聊天
+xabot feishu --app-id <ID> --app-secret <SECRET> chat
+```
+
+### 微信
+
+```bash
+# 健康检查（需要已获取的 token）
+xabot wechat health --token <TOKEN>
+
+# 正式桥接（首次启动自动触发扫码登录）
+xabot wechat run
+
+# 交互式聊天
+xabot wechat chat
+
+# 使用已有凭证重新连接
+xabot wechat chat --credentials <CREDENTIALS>
+```
+
+### chat 终端命令
+
+在 `chat` 模式下，文本输入会被解析为命令或普通消息：
+
+| 输入 | 动作 |
+|------|------|
+| 纯文本 | 作为 `invoke_activity` 发送给 Agent |
+| `/new [prompt]` | 创建新 Activity |
+| `/compact` | 压缩当前 Activity 上下文 |
+| `/cancel` | 取消当前 Activity |
+
+## 开发
+
+```bash
+npm install
+npm run build    # 编译 TypeScript → dist/
+npm test         # 运行全量测试 (vitest)
+```
+
+## 架构
+
+```
+xabot/
+├── src/
+│   ├── core/            # 平台 Client 接口、类型、配对码
+│   ├── xacpp/           # XACPP EstablishHandler & SessionHandler
+│   ├── platforms/
+│   │   ├── feishu/      # 飞书 Client（WebSocket 长连接）
+│   │   └── wechat/      # 微信 Client（HTTP 长轮询）
+│   ├── bridge/          # 双向消息路由：云端 ↔ XACPP
+│   └── cli/             # CLI 入口 & 子命令（commander）
+```
+
+核心设计：
+- **无持久化** — 凭证通过 CLI 参数传入
+- **chatId 通过 Establish 握手获取** — 动态获取，无需硬编码
+- **Activity ↔ chatId** — 每个 chatId 对应唯一一个 XACPP activity
+
+## XACPP 协议
+
+xabot 实现 XACPP（eXtensible Agent Control Plane Protocol）的 Responder 侧。下游 Agent 作为 Initiator 连接。
+
+协议 SDK：
+
+| SDK | 语言 | 仓库 |
+|-----|------|------|
+| xacpp-ts | TypeScript | https://github.com/drodreo/xacpp-ts |
+| xacpp-rs | Rust | https://github.com/drodreo/xacpp-rs |
+
+## 许可
+
+MIT

package/dist/bridge/index.d.ts

@@ -0,0 +1,93 @@
+import type { ChannelId } from '../core/types.js';
+import type { PlatformClient } from '../core/client.js';
+import type { XacppSession, XacppTransport, XacppActivityEvent, XacppCommand, XacppResponse } from 'xacpp';
+/**
+ * Bridge — bidirectional message loop between cloud platform and XACPP agents.
+ *
+ * Cloud → Agent: reads cloud messages, resolves/creates activity,
+ *   sends invoke_activity command via session.
+ * Agent → Cloud: reads agent events, routes content_delta/complete/notify
+ *   back to the corresponding chatId.
+ */
+export declare class Bridge {
+    private cloud;
+    private readonly transport;
+    private readonly cloudReady;
+    private cloudReadyResolve;
+    /** chatId → (senderId → activityId) */
+    private readonly chatUserToActivity;
+    /** activityId → { chatId, senderId } */
+    private readonly activityToTarget;
+    /** Obtained after establish, used to proactively send command/event */
+    private session;
+    /** chatId bound to the established session (from session.credentials) */
+    private sessionChatId;
+    /** targetKey (chatId:senderId) → pending queue state */
+    private readonly pendingQueues;
+    /** targetKey → buffered media ContentParts awaiting next text invoke */
+    private readonly pendingMediaByTarget;
+    private abortCtrl;
+    private closed;
+    private runPromise;
+    /** Whether the establish handshake has completed. */
+    private established;
+    /** Reference to the establish handler — Phase 1 feeds discovered challenges to it. */
+    private establishHandler;
+    private verbose;
+    constructor(transport: XacppTransport, options?: {
+        cloud?: PlatformClient;
+        verbose?: boolean;
+    });
+    /** Replace the cloud PlatformClient (used after Establish login creates a new client). */
+    replaceCloud(cloud: PlatformClient): void;
+    /** Call after establish succeeds to inject session reference. */
+    setSession(session: XacppSession): void;
+    /** Set the establish handler — Phase 1 feeds discovered challenges to it. */
+    setEstablishHandler(handler: {
+        submitChallenge(challenge: string, chatId: ChannelId): void;
+    }): void;
+    /** Generate targetKey for pending queue lookup. */
+    private targetKey;
+    /** Get or create pending queue for a target. */
+    private ensureQueue;
+    /** Create a PendingItem from an event. */
+    private createPendingItem;
+    /** Format action_request for cloud display. */
+    private formatActionMessage;
+    /** Format question for cloud display. */
+    private formatQuestionMessage;
+    /** Format sensitive_info_operation for cloud display. */
+    private formatSensitiveInfoMessage;
+    /** Parse user text into a pending response, or null if unrecognized. */
+    private tryParsePendingResponse;
+    /** Get or create senderId→activityId sub-map for a chatId. */
+    private ensureUserMap;
+    /** Look up activityId for (chatId, senderId). */
+    private getActivityForUser;
+    /** Bind activityId ↔ (chatId, senderId) bidirectionally. */
+    private bindActivity;
+    /** Unbind activityId for (chatId, senderId). */
+    private unbindActivity;
+    /** activityId → state (processingMessageId, thinkingStart, toolActiveStart, expressingStart) */
+    private readonly activityStates;
+    private setTypingIndicatorIfNeeded;
+    private releaseTypingIndicatorForActivity;
+    private endThinking;
+    /** Send a single ContentPart to the cloud platform. */
+    private _sendContentPart;
+    /** Handle Command from downstream Agent (forwarded via XabotSessionHandler.onCommand). */
+    handleCommand(command: XacppCommand): Promise<XacppResponse>;
+    /** Handle Event from downstream Agent (forwarded via XabotSessionHandler.onEvent). */
+    handleEvent(activityId: string, event: XacppActivityEvent): Promise<XacppResponse>;
+    /** Send the next queued pending item to cloud. */
+    private sendNextPending;
+    /** Resolve a pending request and drive the queue forward. */
+    resolvePending(requestId: string, response: XacppResponse): void;
+    /** Cloud message loop: two-phase consumption (idempotent). */
+    run(): Promise<void>;
+    private _run;
+    /** Mark the establish handshake as completed — switches to Phase 2 routing. */
+    markEstablished(): void;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/bridge/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bridge/index.ts"],"names":[],"mappings":"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"}