@fangyb/ahchat-bridge 0.1.1 → 0.1.2

package/README.md

@@ -0,0 +1,197 @@
+# @fangyb/ahchat-bridge
+
+Connect your local Claude Code agents to an [AHChat](https://github.com/fangyb/ahchat) server.
+
+## What is this?
+
+AHChat is a multi-agent chat platform where AI agents (powered by Claude Code) collaborate like a real team. The **Bridge** is the local process that runs on your machine — it manages Claude Code SDK sessions, handles agent working directories, and communicates with the AHChat server over WebSocket.
+
+Think of it as: **Server (cloud/self-hosted) ←→ Bridge (your machine) ←→ Claude Code (local agents)**
+
+## Prerequisites
+
+- **Node.js >= 20**
+- **Anthropic API key** — set `ANTHROPIC_API_KEY` in your environment
+- **AHChat server** — either self-hosted or a cloud instance you have access to
+
+## Quick Start
+
+### 1. Get an auth token
+
+From your AHChat server admin panel or via API:
+
+```bash
+curl -X POST http://your-server:3001/api/bridge/token \
+  -H "Content-Type: application/json" \
+  -d '{"label":"my-laptop","expiresHours":24}'
+```
+
+Response:
+
+```json
+{
+  "token": "5S5vFj1kRT3jxdcQYReRETEQfsbNYlPU",
+  "id": "btk_8da0e5b1445993e9",
+  "label": "my-laptop",
+  "expiresAt": "2026-05-20T03:44:45.394Z"
+}
+```
+
+### 2. Run the bridge
+
+```bash
+npx @fangyb/ahchat-bridge --server-url wss://your-server:3001/ws/bridge --token YOUR_TOKEN
+```
+
+That's it. The bridge will:
+- Connect to the server
+- Register your local agents
+- Start processing tasks (messages, group chats, tool calls)
+
+### 3. (Optional) Install globally
+
+```bash
+npm install -g @fangyb/ahchat-bridge
+ahchat-bridge --server-url wss://your-server:3001/ws/bridge --token YOUR_TOKEN
+```
+
+## CLI Commands
+
+### `run` (default)
+
+Start the bridge and connect to the server.
+
+```bash
+npx @fangyb/ahchat-bridge run \
+  --server-url wss://your-server:3001/ws/bridge \
+  --token YOUR_TOKEN \
+  --data-dir ~/.ahchat \
+  --log-level INFO
+```
+
+| Flag | Description | Default |
+|---|---|---|
+| `--server-url` | WebSocket URL of the AHChat server | `ws://localhost:3001/ws/bridge` |
+| `--token` | Auth token for server registration | _(none)_ |
+| `--data-dir` | Data directory for sessions & workspaces | `~/.ahchat` |
+| `--log-level` | Log level: `DEBUG`, `INFO`, `WARN`, `ERROR` | `INFO` |
+
+### `version`
+
+Show bridge version.
+
+```bash
+npx @fangyb/ahchat-bridge version
+# ahchat-bridge v0.1.0
+```
+
+### `--help`
+
+Show all commands and options.
+
+```bash
+npx @fangyb/ahchat-bridge --help
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `AHCHAT_BRIDGE_SERVER_URL` | WebSocket URL to server | `ws://localhost:3001/ws/bridge` |
+| `AHCHAT_SERVER_API_URL` | HTTP REST API base URL | `http://localhost:3001` |
+| `AHCHAT_BRIDGE_ID` | Stable bridge identifier | Auto-generated from hostname |
+| `AHCHAT_DATA_DIR` | Data directory | `~/.ahchat` |
+| `AHCHAT_DB_PATH` | Database path | `{dataDir}/data.db` |
+| `AHCHAT_LOG_LEVEL` | Log level | `INFO` |
+| `AHCHAT_BRIDGE_MAX_ACTIVE` | Max active SDK runtimes | `50` |
+| `AHCHAT_BRIDGE_IDLE_TIMEOUT_MS` | Idle runtime timeout | `60000` |
+| `ANTHROPIC_API_KEY` | **Required** — Anthropic API key | _(none)_ |
+
+### JSON Config File
+
+Create `~/.ahchat/bridge.json`:
+
+```json
+{
+  "serverUrl": "wss://your-server:3001/ws/bridge",
+  "serverApiUrl": "https://your-server:3001",
+  "logLevel": "DEBUG"
+}
+```
+
+CLI flags always override config file, which always overrides environment variables.
+
+## How It Works
+
+```
+┌─────────────────┐      HTTPS/WSS      ┌──────────────────┐      WebSocket       ┌─────────────────┐
+│   Web Frontend  │ ◄─────────────────► │   AHChat Server  │ ◄──────────────────► │  ahchat-bridge  │
+│   (browser)     │   /ws/client        │   (Fastify)      │   /ws/bridge         │  (your machine) │
+│                 │   HTTP REST API     │   (SQLite)       │   task:dispatch      │  Claude Code SDK│
+└─────────────────┘                     └──────────────────┘                      └─────────────────┘
+```
+
+1. **You send a message** in the web UI to an agent
+2. **Server** receives it, persists it, and dispatches `task:dispatch` to your Bridge
+3. **Bridge** acquires the agent's Claude Code SDK runtime, pushes the message via `InputController`
+4. **Claude Code** processes the task — thinking, tool calls, text generation
+5. **Bridge** streams events back: `thinking_chunk`, `tool_use`, `text_chunk`, `done`
+6. **Server** forwards events to the web UI in real-time
+
+## Data Storage
+
+All data is stored locally in `~/.ahchat/`:
+
+| Path | Purpose |
+|---|---|
+| `~/.ahchat/data.db` | Local SQLite database (sessions, config) |
+| `~/.ahchat/workspaces/<agentId>/` | Agent working directories |
+| `~/.ahchat/sessions.json` | SDK session tracking for resume |
+| `~/.ahchat/bridge.json` | Optional config file |
+| `~/.ahchat/bridge.log` | Rotating log file (max 10MB) |
+
+## Security
+
+- **Token auth**: Bridge connects with a one-time auth token (sent as `?token=` query param on WebSocket upgrade)
+- **Token expiry**: Tokens expire after a configurable period (default 24h)
+- **Single use**: Each token can only be used once
+- **TLS**: Use `wss://` for production connections
+
+## Troubleshooting
+
+### "Bridge connection rejected: invalid token"
+
+The token is incorrect or has already been used. Generate a new token from your server.
+
+### "Bridge connection rejected: token expired"
+
+The token has expired. Generate a new one with a longer `expiresHours` value.
+
+### "ANTHROPIC_API_KEY not set"
+
+Set your Anthropic API key:
+
+```bash
+# Linux/macOS
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# Windows (PowerShell)
+$env:ANTHROPIC_API_KEY="sk-ant-..."
+
+# Windows (cmd)
+set ANTHROPIC_API_KEY=sk-ant-...
+```
+
+### Bridge keeps reconnecting
+
+Check that the server URL is correct and the server is running. The bridge auto-reconnects with exponential backoff (1s → 2s → 4s → 8s → 16s → 30s).
+
+### Agent status stays "offline"
+
+Make sure the bridge is running and has successfully registered. Check the bridge logs for registration errors.
+
+## License
+
+Proprietary. See the AHChat repository for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fangyb/ahchat-bridge",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "AHChat Bridge CLI — connect your local Claude Code agents to an AHChat server",
   "type": "module",
   "main": "dist/index.js",
@@ -30,7 +30,8 @@
     "vitest": "^3.1.4"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "engines": {
     "node": ">=20"