@fangyb/ahchat-bridge 0.1.1 → 0.1.3

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/dist/{chunk-7SODRWIG.js → chunk-MO54RNR2.js}

@@ -1,8 +1,15 @@
+// ../../node_modules/.pnpm/tsup@8.5.1_jiti@1.21.7_postcss@8.5.14_tsx@4.21.0_typescript@5.9.3/node_modules/tsup/assets/esm_shims.js
+import path from "path";
+import { fileURLToPath } from "url";
+var getFilename = () => fileURLToPath(import.meta.url);
+var getDirname = () => path.dirname(getFilename());
+var __dirname = /* @__PURE__ */ getDirname();
+
 // src/config.ts
 import crypto from "crypto";
 import fs from "fs";
 import os from "os";
-import path from "path";
+import path2 from "path";
 var DEFAULT_QUERY_CONFIG = {
   maxActive: 50,
   idleTimeoutMs: 6e4,
@@ -56,9 +63,9 @@ function mergeQueryConfig(file) {
 function loadBridgeConfig() {
   const dataDir = readEnvString(
     "AHCHAT_DATA_DIR",
-    path.join(os.homedir(), ".ahchat")
+    path2.join(os.homedir(), ".ahchat")
   );
-  const fileConfig = tryReadJsonConfig(path.join(dataDir, "bridge.json"));
+  const fileConfig = tryReadJsonConfig(path2.join(dataDir, "bridge.json"));
   return {
     serverUrl: readEnvString(
       "AHCHAT_BRIDGE_SERVER_URL",
@@ -75,7 +82,7 @@ function loadBridgeConfig() {
     dataDir,
     dbPath: readEnvString(
       "AHCHAT_DB_PATH",
-      fileConfig.dbPath ?? path.join(dataDir, "data.db")
+      fileConfig.dbPath ?? path2.join(dataDir, "data.db")
     ),
     serverApiUrl: readEnvString(
       "AHCHAT_SERVER_API_URL",
@@ -90,7 +97,7 @@ function ensureDir(dirPath) {
 
 // src/logger.ts
 import os3 from "os";
-import path3 from "path";
+import path4 from "path";
 
 // ../logger/src/types.ts
 var LOG_LEVEL_VALUE = {
@@ -710,7 +717,7 @@ function consoleTransport(opts) {
 }
 
 // ../logger/src/transports/file.ts
-import path2 from "path";
+import path3 from "path";
 
 // ../../node_modules/.pnpm/rotating-file-stream@3.2.9/node_modules/rotating-file-stream/dist/esm/index.js
 import { exec } from "child_process";
@@ -755,11 +762,11 @@ var RotatingFileStream = class extends Writable {
   timeout;
   timeoutPromise;
   constructor(generator, options) {
-    const { encoding, history, maxFiles, maxSize, path: path10 } = options;
+    const { encoding, history, maxFiles, maxSize, path: path11 } = options;
     super({ decodeStrings: true, defaultEncoding: encoding });
     this.createGzip = createGzip;
     this.exec = exec;
-    this.filename = path10 + generator(null);
+    this.filename = path11 + generator(null);
     this.fsCreateReadStream = createReadStream;
     this.fsCreateWriteStream = createWriteStream;
     this.fsOpen = open;
@@ -771,7 +778,7 @@ var RotatingFileStream = class extends Writable {
     this.options = options;
     this.stdout = process.stdout;
     if (maxFiles || maxSize)
-      options.history = path10 + (history ? history : this.generator(null) + ".txt");
+      options.history = path11 + (history ? history : this.generator(null) + ".txt");
     this.on("close", () => this.finished ? null : this.emit("finish"));
     this.on("finish", () => this.finished = this.clear());
     (async () => {
@@ -899,9 +906,9 @@ var RotatingFileStream = class extends Writable {
     return this.move();
   }
   async findName() {
-    const { interval, path: path10, intervalBoundary } = this.options;
+    const { interval, path: path11, intervalBoundary } = this.options;
     for (let index = 1; index < 1e3; ++index) {
-      const filename = path10 + this.generator(interval && intervalBoundary ? new Date(this.prev) : this.rotation, index);
+      const filename = path11 + this.generator(interval && intervalBoundary ? new Date(this.prev) : this.rotation, index);
       if (!await exists(filename))
         return filename;
     }
@@ -931,11 +938,11 @@ var RotatingFileStream = class extends Writable {
     return this.unlink(filename);
   }
   async classical() {
-    const { compress, path: path10, rotate } = this.options;
+    const { compress, path: path11, rotate } = this.options;
     let rotatedName = "";
     for (let count = rotate; count > 0; --count) {
-      const currName = path10 + this.generator(count);
-      const prevName = count === 1 ? this.filename : path10 + this.generator(count - 1);
+      const currName = path11 + this.generator(count);
+      const prevName = count === 1 ? this.filename : path11 + this.generator(count - 1);
       if (!await exists(prevName))
         continue;
       if (!rotatedName)
@@ -1328,8 +1335,8 @@ function parseSize(maxSize) {
 }
 function fileTransport(opts) {
   const fmt = opts.formatter ?? jsonFormatter;
-  const dir = path2.dirname(opts.path);
-  const filename = path2.basename(opts.path);
+  const dir = path3.dirname(opts.path);
+  const filename = path3.basename(opts.path);
   const stream = createStream(filename, {
     path: dir,
     size: opts.rotate?.maxSize ? parseSize(opts.rotate.maxSize) : "50M",
@@ -1349,8 +1356,8 @@ function createLogger(config) {
 // src/logger.ts
 var bridgeConfig = loadBridgeConfig();
 var isTest = !!process.env["VITEST"];
-var LOG_DIR = path3.join(os3.homedir(), ".ahchat", "logs");
-var LOG_FILE = path3.join(LOG_DIR, "bridge.log");
+var LOG_DIR = path4.join(os3.homedir(), ".ahchat", "logs");
+var LOG_FILE = path4.join(LOG_DIR, "bridge.log");
 if (!isTest) ensureDir(LOG_DIR);
 function createModuleLogger(module) {
   const transports = [consoleTransport({ formatter: prettyFormatter })];
@@ -1748,7 +1755,7 @@ var wsMetrics = new WsMetrics();
 // src/agentManager.ts
 import fs2 from "fs/promises";
 import os4 from "os";
-import path6 from "path";
+import path7 from "path";
 
 // src/inputController.ts
 var InputController = class {
@@ -1806,17 +1813,17 @@ var InputController = class {
 };
 
 // src/permissionGuard.ts
-import path5 from "path";
+import path6 from "path";
 
 // ../shared/src/utils/pathSafety.ts
-import path4 from "path";
+import path5 from "path";
 function isPathInside(parent, child) {
-  const resolvedParent = path4.resolve(parent);
-  const resolvedChild = path4.resolve(child);
+  const resolvedParent = path5.resolve(parent);
+  const resolvedChild = path5.resolve(child);
   if (resolvedParent === resolvedChild) return true;
-  const rel = path4.relative(resolvedParent, resolvedChild);
+  const rel = path5.relative(resolvedParent, resolvedChild);
   if (rel === "") return true;
-  return !rel.startsWith("..") && !path4.isAbsolute(rel);
+  return !rel.startsWith("..") && !path5.isAbsolute(rel);
 }
 
 // src/permissionGuard.ts
@@ -1831,7 +1838,7 @@ function makeCwdPermissionGuard(cwd, agentId, scope, log) {
     if (typeof raw !== "string" || raw.length === 0) {
       return { behavior: "allow" };
     }
-    const abs = path5.isAbsolute(raw) ? raw : path5.resolve(cwd, raw);
+    const abs = path6.isAbsolute(raw) ? raw : path6.resolve(cwd, raw);
     if (isPathInside(cwd, abs)) {
       return { behavior: "allow" };
     }
@@ -2881,14 +2888,14 @@ var AgentManager = class {
     this.emit = emit;
     if (typeof options === "function") {
       this.queryFn = options;
-      this.workspacesDir = path6.join(os4.homedir(), ".ahchat", "workspaces");
+      this.workspacesDir = path7.join(os4.homedir(), ".ahchat", "workspaces");
       this.queryConfig = DEFAULT_QUERY_CONFIG;
       this.askQuestionRegistry = new AskQuestionRegistry();
       this.neuralBusManager = new NeuralBusManager();
       this.groupRegistry = null;
     } else {
       this.queryFn = options?.queryFn ?? null;
-      this.workspacesDir = options?.workspacesDir ?? path6.join(os4.homedir(), ".ahchat", "workspaces");
+      this.workspacesDir = options?.workspacesDir ?? path7.join(os4.homedir(), ".ahchat", "workspaces");
       this.queryConfig = options?.queryConfig ?? DEFAULT_QUERY_CONFIG;
       this.askQuestionRegistry = options?.askQuestionRegistry ?? new AskQuestionRegistry();
       this.neuralBusManager = options?.neuralBusManager ?? new NeuralBusManager();
@@ -3357,7 +3364,7 @@ ${relay.message}`,
         status: existingProc.status
       });
     } else {
-      const cwd = agentConfig.workingDirectory || path6.join(this.workspacesDir, agentConfig.id);
+      const cwd = agentConfig.workingDirectory || path7.join(this.workspacesDir, agentConfig.id);
       void this.acquire(agentConfig, scope, cwd).then((proc) => {
         if (suppressEmit) proc.internalRelayId = suppressEmit;
         return this.sendMessage({ ...task, agentId: agentConfig.id, scope });
@@ -3492,7 +3499,7 @@ ${relay.message}`,
         break;
       }
       try {
-        const cwd = agent.workingDirectory || path6.join(this.workspacesDir, agent.id);
+        const cwd = agent.workingDirectory || path7.join(this.workspacesDir, agent.id);
         await this.acquire(agent, { kind: "single" }, cwd);
         warmed++;
         logger8.info("Agent process pre-created for recovery", { agentId: agent.id });
@@ -3688,8 +3695,8 @@ var HttpAgentRegistry = class {
   agents = /* @__PURE__ */ new Map();
   apiUrl(suffix) {
     const base = this.serverApiUrl.replace(/\/$/, "");
-    const path10 = suffix.startsWith("/") ? suffix : `/${suffix}`;
-    return `${base}${path10}`;
+    const path11 = suffix.startsWith("/") ? suffix : `/${suffix}`;
+    return `${base}${path11}`;
   }
   async refresh() {
     try {
@@ -4074,11 +4081,11 @@ var ServerConnector = class {
 // src/modelQuerier.ts
 import fs3 from "fs/promises";
 import os5 from "os";
-import path7 from "path";
+import path8 from "path";
 var logger12 = createModuleLogger("bridge.modelQuerier");
 async function listModels(queryFn, opts = {}) {
   const t0 = Date.now();
-  const cwd = opts.cwd ?? path7.join(os5.homedir(), ".ahchat", "workspaces", "_list_models");
+  const cwd = opts.cwd ?? path8.join(os5.homedir(), ".ahchat", "workspaces", "_list_models");
   await fs3.mkdir(cwd, { recursive: true });
   const fn = queryFn ?? (await import("@anthropic-ai/claude-agent-sdk")).query;
   const ic = new InputController();
@@ -4137,7 +4144,7 @@ async function listModels(queryFn, opts = {}) {
 
 // src/lockfile.ts
 import fs4 from "fs";
-import path8 from "path";
+import path9 from "path";
 var logger13 = createModuleLogger("bridge.lockfile");
 var lockPath = null;
 function isProcessAlive(pid) {
@@ -4151,7 +4158,7 @@ function isProcessAlive(pid) {
   }
 }
 function acquireLock(dataDir) {
-  const file = path8.join(dataDir, "bridge.lock");
+  const file = path9.join(dataDir, "bridge.lock");
   lockPath = file;
   if (fs4.existsSync(file)) {
     const raw = fs4.readFileSync(file, "utf-8").trim();
@@ -4163,7 +4170,7 @@ function acquireLock(dataDir) {
       logger13.warn("Removing stale bridge.lock (process not found)", { pid, path: file });
     }
   }
-  fs4.mkdirSync(path8.dirname(file), { recursive: true });
+  fs4.mkdirSync(path9.dirname(file), { recursive: true });
   fs4.writeFileSync(file, String(process.pid), "utf-8");
   logger13.info("Acquired bridge lock", { path: file, pid: process.pid });
   const release = () => {
@@ -4431,13 +4438,13 @@ function createGroupTaskDispatchHandler(agentManager, agentRegistry, emit) {
 
 // src/sessionStore.ts
 import fs5 from "fs";
-import path9 from "path";
+import path10 from "path";
 var logger15 = createModuleLogger("session.store");
 var SessionStore = class {
   filePath;
   cache;
   constructor(dataDir) {
-    this.filePath = path9.join(dataDir, "sessions.json");
+    this.filePath = path10.join(dataDir, "sessions.json");
     this.cache = this.loadFromDisk();
   }
   cacheKey(agentId, scope) {
@@ -4497,7 +4504,7 @@ var SessionStore = class {
   }
   saveToDisk() {
     try {
-      const dir = path9.dirname(this.filePath);
+      const dir = path10.dirname(this.filePath);
       fs5.mkdirSync(dir, { recursive: true });
       fs5.writeFileSync(this.filePath, JSON.stringify(this.cache, null, 2), "utf-8");
     } catch (e) {
@@ -4507,6 +4514,7 @@ var SessionStore = class {
 };
 
 export {
+  __dirname,
   loadBridgeConfig,
   ensureDir,
   createModuleLogger,

package/dist/cli.js

@@ -5,6 +5,7 @@ import {
   HttpAgentRegistry,
   ServerConnector,
   SessionStore,
+  __dirname,
   acquireLock,
   createGroupTaskDispatchHandler,
   createModuleLogger,
@@ -14,19 +15,199 @@ import {
   listModels,
   loadBridgeConfig,
   wsMetrics
-} from "./chunk-7SODRWIG.js";
+} from "./chunk-MO54RNR2.js";
 
 // src/cli.ts
 import cac from "cac";
-var logger = createModuleLogger("bridge");
+
+// src/protocol.ts
+import { execSync } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
+var logger = createModuleLogger("bridge.protocol");
+function getBridgeExePath() {
+  const pkgDir = path.resolve(__dirname, "..");
+  return path.join(pkgDir, "dist", "cli.js");
+}
+function registerProtocolHandler() {
+  const platform = os.platform();
+  if (platform === "win32") {
+    registerWindows();
+  } else if (platform === "darwin") {
+    registerMacOS();
+  } else {
+    registerLinux();
+  }
+  logger.info("Protocol handler registered", { platform });
+}
+function registerWindows() {
+  const exe = getBridgeExePath();
+  const handler = `"${process.execPath}" "${exe}" launch --url "%1"`;
+  const iconPath = process.execPath;
+  const regCommands = [
+    `REG ADD "HKCU\\Software\\Classes\\ahchat" /ve /d "URL:ahchat" /f`,
+    `REG ADD "HKCU\\Software\\Classes\\ahchat" /v "URL Protocol" /d "" /f`,
+    `REG ADD "HKCU\\Software\\Classes\\ahchat\\DefaultIcon" /ve /d "${iconPath}" /f`,
+    `REG ADD "HKCU\\Software\\Classes\\ahchat\\shell\\open\\command" /ve /d ${handler} /f`
+  ];
+  for (const cmd of regCommands) {
+    try {
+      execSync(cmd, { stdio: "pipe" });
+    } catch (e) {
+      logger.error("Failed to register Windows protocol handler", { error: e, cmd });
+      throw new Error(`Failed to register protocol handler: ${cmd}`);
+    }
+  }
+  logger.info("Windows protocol handler registered");
+}
+function registerMacOS() {
+  const appDir = path.join(os.homedir(), "Applications", "AHChatBridge.app");
+  const contentsDir = path.join(appDir, "Contents");
+  const macosDir = path.join(contentsDir, "MacOS");
+  const resourcesDir = path.join(contentsDir, "Resources");
+  fs.mkdirSync(macosDir, { recursive: true });
+  fs.mkdirSync(resourcesDir, { recursive: true });
+  const infoPlist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleName</key>
+  <string>AHChatBridge</string>
+  <key>CFBundleDisplayName</key>
+  <string>AHChat Bridge</string>
+  <key>CFBundleIdentifier</key>
+  <string>com.fangyb.ahchat-bridge</string>
+  <key>CFBundleVersion</key>
+  <string>0.1.0</string>
+  <key>CFBundlePackageType</key>
+  <string>APPL</string>
+  <key>CFBundleExecutable</key>
+  <string>launch.sh</string>
+  <key>CFBundleURLTypes</key>
+  <array>
+    <dict>
+      <key>CFBundleURLName</key>
+      <string>AHChat Bridge</string>
+      <key>CFBundleURLSchemes</key>
+      <array>
+        <string>ahchat</string>
+      </array>
+    </dict>
+  </array>
+</dict>
+</plist>`;
+  const launchScript = `#!/bin/bash
+URL="$1"
+exec "${process.execPath}" "${getBridgeExePath()}" launch --url "$URL"`;
+  fs.writeFileSync(path.join(contentsDir, "Info.plist"), infoPlist);
+  fs.writeFileSync(path.join(macosDir, "launch.sh"), launchScript);
+  fs.chmodSync(path.join(macosDir, "launch.sh"), 493);
+  logger.info("macOS protocol handler registered", { appDir });
+}
+function registerLinux() {
+  const desktopFile = `[Desktop Entry]
+Name=AHChat Bridge
+Exec=${process.execPath} ${getBridgeExePath()} launch --url %u
+Type=Application
+NoDisplay=true
+MimeType=x-scheme-handler/ahchat;`;
+  const desktopPath = path.join(
+    os.homedir(),
+    ".local",
+    "share",
+    "applications",
+    "ahchat-bridge.desktop"
+  );
+  fs.mkdirSync(path.dirname(desktopPath), { recursive: true });
+  fs.writeFileSync(desktopPath, desktopFile);
+  try {
+    execSync("update-desktop-database ~/.local/share/applications/", { stdio: "pipe" });
+  } catch {
+  }
+  logger.info("Linux protocol handler registered", { desktopPath });
+}
+function unregisterProtocolHandler() {
+  const platform = os.platform();
+  if (platform === "win32") {
+    try {
+      execSync('REG DELETE "HKCU\\Software\\Classes\\ahchat" /f', { stdio: "pipe" });
+      logger.info("Windows protocol handler unregistered");
+    } catch (e) {
+      logger.warn("Failed to unregister Windows protocol handler", { error: e });
+    }
+  } else if (platform === "darwin") {
+    const appDir = path.join(os.homedir(), "Applications", "AHChatBridge.app");
+    try {
+      fs.rmSync(appDir, { recursive: true, force: true });
+      logger.info("macOS protocol handler unregistered");
+    } catch (e) {
+      logger.warn("Failed to unregister macOS protocol handler", { error: e });
+    }
+  } else {
+    const desktopPath = path.join(
+      os.homedir(),
+      ".local",
+      "share",
+      "applications",
+      "ahchat-bridge.desktop"
+    );
+    try {
+      fs.unlinkSync(desktopPath);
+      logger.info("Linux protocol handler unregistered");
+    } catch (e) {
+      logger.warn("Failed to unregister Linux protocol handler", { error: e });
+    }
+  }
+}
+function isProtocolRegistered() {
+  const platform = os.platform();
+  if (platform === "win32") {
+    try {
+      execSync('REG QUERY "HKCU\\Software\\Classes\\ahchat" /ve', { stdio: "pipe" });
+      return true;
+    } catch {
+      return false;
+    }
+  } else if (platform === "darwin") {
+    const appDir = path.join(os.homedir(), "Applications", "AHChatBridge.app");
+    return fs.existsSync(path.join(appDir, "Contents", "Info.plist"));
+  } else {
+    const desktopPath = path.join(
+      os.homedir(),
+      ".local",
+      "share",
+      "applications",
+      "ahchat-bridge.desktop"
+    );
+    return fs.existsSync(desktopPath);
+  }
+}
+
+// src/cli.ts
+var logger2 = createModuleLogger("bridge");
 var cli = cac("ahchat-bridge");
-cli.command("[command]", "Start the bridge (default: run)").option("--server-url <url>", "WebSocket URL of the AHChat server").option("--token <token>", "Auth token for server registration").option("--data-dir <dir>", "Data directory (default: ~/.ahchat)").option("--log-level <level>", "Log level (default: INFO)").action((args) => {
-  void runBridge({
-    serverUrl: args["server-url"],
-    token: args.token,
-    dataDir: args["data-dir"],
-    logLevel: args["log-level"]
-  });
+cli.command("install", "Register ahchat:// protocol handler (one-time setup)").action(() => {
+  registerProtocolHandler();
+  console.log("ahchat:// protocol handler registered successfully.");
+  console.log("You can now launch the bridge from your browser with one click.");
+});
+cli.command("uninstall", "Remove ahchat:// protocol handler").action(() => {
+  unregisterProtocolHandler();
+  console.log("ahchat:// protocol handler removed.");
+});
+cli.command("status", "Check if protocol handler is registered").action(() => {
+  const registered = isProtocolRegistered();
+  console.log(registered ? "ahchat:// protocol is registered." : "ahchat:// protocol is NOT registered.");
+  console.log('Run "npx @fangyb/ahchat-bridge install" to register it.');
+});
+cli.command("launch", "Launch bridge from ahchat:// URL (called by OS)").option("--url <url>", "ahchat:// URL with server and token params").action((args) => {
+  const url = args.url;
+  if (!url) {
+    console.error("Error: --url is required");
+    process.exit(1);
+  }
+  void runBridgeFromUrl(url);
 });
 cli.command("run", "Start the bridge and connect to server").option("--server-url <url>", "WebSocket URL of the AHChat server").option("--token <token>", "Auth token for server registration").option("--data-dir <dir>", "Data directory (default: ~/.ahchat)").option("--log-level <level>", "Log level (default: INFO)").action((args) => {
   void runBridge({
@@ -42,6 +223,30 @@ cli.command("version", "Show bridge version").action(() => {
 cli.help();
 cli.version("0.1.0");
 cli.parse();
+function parseAhchatUrl(url) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "ahchat:") return null;
+    const serverUrl = parsed.searchParams.get("server");
+    const token = parsed.searchParams.get("token");
+    if (!serverUrl || !token) return null;
+    return { serverUrl, token };
+  } catch {
+    return null;
+  }
+}
+async function runBridgeFromUrl(url) {
+  const parsed = parseAhchatUrl(url);
+  if (!parsed) {
+    console.error("Invalid ahchat:// URL:", url);
+    console.error("Expected format: ahchat://bridge?server=ws://host:port/ws/bridge&token=xxx");
+    process.exit(1);
+  }
+  await runBridge({
+    serverUrl: parsed.serverUrl,
+    token: parsed.token
+  });
+}
 async function runBridge(args) {
   let config = loadBridgeConfig();
   if (args.serverUrl) {
@@ -60,7 +265,7 @@ async function runBridge(args) {
   }
   ensureDir(config.dataDir);
   acquireLock(config.dataDir);
-  logger.info("Bridge starting", {
+  logger2.info("Bridge starting", {
     bridgeId: config.bridgeId,
     serverUrl: config.serverUrl,
     serverApiUrl: config.serverApiUrl
@@ -101,21 +306,21 @@ async function runBridge(args) {
       switch (msg.type) {
         case "bridge:list_models_request": {
           const { requestId } = msg.payload;
-          logger.info("list_models request received", { requestId });
+          logger2.info("list_models request received", { requestId });
           try {
             const models = await listModels();
             connector?.send({
               type: "bridge:list_models_response",
               payload: { requestId, models }
             });
-            logger.info("list_models response sent", { requestId, count: models.length });
+            logger2.info("list_models response sent", { requestId, count: models.length });
           } catch (e) {
             const err = e instanceof Error ? e.message : String(e);
             connector?.send({
               type: "bridge:list_models_response",
               payload: { requestId, error: err }
             });
-            logger.error("list_models failed", { requestId, error: e });
+            logger2.error("list_models failed", { requestId, error: e });
           }
           break;
         }
@@ -123,7 +328,7 @@ async function runBridge(args) {
           await agentManager.terminate(msg.payload.agentId);
           break;
         case "agent:terminate_scope":
-          logger.info("agent:terminate_scope received", {
+          logger2.info("agent:terminate_scope received", {
             agentId: msg.payload.agentId,
             scope: msg.payload.scope
           });
@@ -140,7 +345,7 @@ async function runBridge(args) {
           const p = msg.payload;
           const answerText = formatAnswerForSDK(p);
           const ok = askQuestionRegistry.resolve(p.questionId, answerText);
-          logger.info("user:answer_question handled", {
+          logger2.info("user:answer_question handled", {
             questionId: p.questionId,
             agentId: p.agentId,
             resolved: ok,
@@ -161,7 +366,7 @@ async function runBridge(args) {
     });
   }, config.queryConfig.statusReportIntervalMs);
   const shutdown = async (signal) => {
-    logger.info("Shutdown signal received", { signal });
+    logger2.info("Shutdown signal received", { signal });
     if (statusInterval) {
       clearInterval(statusInterval);
       statusInterval = null;
@@ -169,7 +374,7 @@ async function runBridge(args) {
     wsMetrics.stop();
     connector?.close();
     await agentManager.shutdownAll();
-    logger.info("Bridge stopped");
+    logger2.info("Bridge stopped");
     process.exit(0);
   };
   process.on("SIGINT", () => void shutdown("SIGINT"));

package/dist/index.js

@@ -14,7 +14,7 @@ import {
   listModels,
   loadBridgeConfig,
   wsMetrics
-} from "./chunk-7SODRWIG.js";
+} from "./chunk-MO54RNR2.js";
 
 // src/index.ts
 var logger = createModuleLogger("bridge");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fangyb/ahchat-bridge",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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"