@zoulabo/line-hive 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kizuna Contributors
+
+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,457 @@
+<p align="center">
+  <img src="assets/logo-line-hive.svg" alt="LINE Hive logo" width="120">
+</p>
+
+<h1 align="center">LINE Hive — Connect Your AI Agents</h1>
+
+<p align="center">
+  <strong>Stay connected to your AI coding agents from your phone.</strong><br>
+  An MCP server that bridges AI agents (Copilot, Cursor, Claude) to LINE Messaging — check progress, answer questions, and get alerts without touching your computer.
+</p>
+
+<p align="center">
+  <em>Works with VS Code Copilot · Cursor · Claude Code · Claude Desktop · any MCP client</em>
+</p>
+
+---
+
+**Why?** AI agents run long tasks, hit decisions, and need your input. Instead of watching your editor, LINE Hive lets you check status or reply from LINE on your phone — when it's convenient for you.
+
+<!-- screenshot placeholder: LINE conversation showing status query + agent reply -->
+
+## Contents
+
+- [Quick Start](#quick-start)
+- [How It Works](#how-it-works)
+- [Setup](#setup) — [LINE Account](#1-create-a-line-official-account) · [Webhook Tunnel](#2-set-up-a-webhook-tunnel) · [Install](#3-install-line-hive-in-your-project)
+- [MCP Tools](#mcp-tools)
+- [LINE Commands](#line-commands)
+- [Limitations](#limitations)
+- [Development](#development)
+- [Troubleshooting](#troubleshooting)
+- [Architecture](#architecture)
+
+## Quick Start
+
+```bash
+# 1. Run interactive setup in your project
+npx @zoulabo/line-hive init
+
+# 2. Restart your editor — the MCP server starts automatically
+```
+
+The wizard prompts for your LINE credentials, configures your editor, and installs agent instructions. You'll need a [LINE Official Account](#1-create-a-line-official-account) and a [webhook tunnel](#2-set-up-a-webhook-tunnel) (ngrok recommended, but any tunnel works) first.
+
+Optional: verify your LINE API connection:
+```bash
+npx @zoulabo/line-hive test
+```
+
+## How It Works
+
+Your AI agent sets its status; you query it from LINE whenever you want. Replies are free (uses LINE's replyToken — no push quota consumed).
+
+```mermaid
+sequenceDiagram
+    participant You as You (LINE)
+    participant Server as LINE Hive
+    participant Agent as AI Agent
+
+    Agent->>Server: set_status("working on tests")
+    You->>Server: "?"
+    Server-->>You: Working: tests
+
+    Agent->>Server: set_status("needs_input")
+    You->>Server: "yes"
+    Server-->>You: Got it
+    Server->>Agent: pending_reply: "yes"
+```
+
+**Key benefits:**
+- **Free status queries** — uses LINE replyToken (no push quota consumed)
+- **Multi-agent** — multiple editor windows share one LINE bot, numbered list shows all
+- **No spam** — you check when convenient, not interrupted by push notifications
+- **Works offline** — status is stored in SQLite; LINE responds even when the agent is busy
+
+## Prerequisites
+
+1. A LINE Official Account with Messaging API enabled ([setup guide below](#1-create-a-line-official-account))
+2. A webhook tunnel — ngrok (recommended, auto-managed), or any tunnel to localhost:19780 ([options below](#2-set-up-a-webhook-tunnel))
+3. Node.js 18+
+
+## Setup
+
+### 1. Create a LINE Official Account
+
+> Takes ~5 minutes. You need a browser + LINE app on your phone.
+
+1. Go to [LINE Developers Console](https://developers.line.biz/console/) → log in with your LINE account
+2. Create a **Provider** (just an org label) → Create a **Messaging API** channel
+3. Copy your credentials from the channel settings:
+   - **Channel Secret** — *Basic settings* tab
+   - **Channel Access Token** — *Messaging API* tab → click *Issue*
+4. Add the bot as a friend: scan the QR code in *Messaging API* → *Bot information*
+5. Disable auto-reply: *Messaging API* → *Auto-reply messages* → *Edit* → turn off both responses
+
+> **Webhook URL** — you'll set this after configuring your tunnel (next step). Format: `https://YOUR-TUNNEL-URL/webhook`
+
+### 2. Set Up a Webhook Tunnel
+
+LINE needs a public HTTPS URL to send webhook events. Any tunnel that forwards to `localhost:19780` works:
+
+| Tool | Stable URL? | Setup |
+|------|-------------|-------|
+| **ngrok** (recommended) | Yes (free tier) | Built-in auto-management via `NGROK_DOMAIN` env var |
+| **VS Code Ports** | Yes (devtunnels) | Built-in — Ports panel → Forward Port 19780 |
+| **cloudflared** (quick) | No (random URL) | `cloudflared tunnel --url http://localhost:19780` |
+| **cloudflared** (named) | Yes (own domain) | Requires Cloudflare domain |
+| **localtunnel** | No | `npx localtunnel --port 19780` |
+| **localhost.run** | No | `ssh -R 80:localhost:19780 localhost.run` |
+
+**Using ngrok (recommended):**
+
+ngrok is recommended because the MCP server can auto-manage it — when `NGROK_DOMAIN` is set, the tunnel starts and auto-restarts alongside the webhook server. Other tunnels work fine but must be started manually.
+
+1. Sign up at [ngrok.com](https://ngrok.com/) (free tier works)
+2. Install the CLI:
+   ```bash
+   # macOS
+   brew install ngrok
+
+   # or download from https://ngrok.com/download
+   ```
+3. Authenticate:
+   ```bash
+   ngrok config add-authtoken YOUR_AUTH_TOKEN
+   ```
+   (Find your token at [dashboard.ngrok.com/get-started/your-authtoken](https://dashboard.ngrok.com/get-started/your-authtoken))
+4. **Claim a free stable domain**:
+   - Go to [dashboard.ngrok.com/domains](https://dashboard.ngrok.com/domains)
+   - Click *Create Domain* — you'll get something like `your-app-name.ngrok-free.dev`
+   - A stable domain means the URL doesn't change between restarts (no need to update LINE Console every time)
+
+**Using a different tunnel:**
+
+Start your tunnel manually before or after the MCP server. The webhook server listens on port 19780 regardless. Just skip setting `NGROK_DOMAIN` and the MCP server won't try to spawn ngrok.
+
+**Set the webhook URL in LINE Console:**
+
+5. Go back to your channel in [LINE Developers Console](https://developers.line.biz/console/)
+6. *Messaging API* → *Webhook URL* → set to `https://YOUR-TUNNEL-URL/webhook`
+7. Toggle *Use webhook* → **On**
+8. Click *Verify* — it will fail until the MCP server is running (that's OK)
+
+### 3. Install LINE Hive in Your Project
+
+```bash
+# Interactive setup (prompts for editor choice)
+npx @zoulabo/line-hive init
+
+# Or specify your editor directly:
+npx @zoulabo/line-hive init --editor cursor
+npx @zoulabo/line-hive init --editor claude-code
+npx @zoulabo/line-hive init --editor claude-desktop
+```
+
+The init wizard will:
+1. Ask which AI agent you're using (VS Code Copilot, Cursor, Claude Code, or Claude Desktop)
+2. Generate the appropriate config file
+3. Install the LINE instruction file (teaches AI agents how to use the LINE tools)
+4. Run a diagnostic check to verify your setup
+
+This generates editor-specific config files:
+
+| Editor | Config File | Credential Handling |
+|--------|------------|-------------------|
+| VS Code | `.vscode/mcp.json` | Prompted at startup (no secrets on disk) |
+| Cursor | `.vscode/mcp.json` | Prompted at startup (no secrets on disk) |
+| Claude Code | `.mcp.json` | Uses `${VAR}` env var expansion |
+| Claude Desktop | `~/...Claude/claude_desktop_config.json` | Edit config file manually |
+
+All editors also get a project-level instruction file that teaches AI agents how to use the LINE tools:
+- **VS Code / Cursor / Claude Desktop**: `.github/instructions/line-notification.instructions.md`
+- **Claude Code**: `.claude/rules/line-notification.md` (auto-loaded by Claude Code's rules system)
+
+> **Note**: If you use Claude Code as a VS Code or Cursor extension, pass `--editor claude-code` (not `--editor vscode`). The `--editor` flag selects the AI agent's config format, not the editor application.
+
+**VS Code / Cursor** — no secrets on disk. Credentials use `${input:}` placeholders. The editor prompts for them each session.
+
+Restart your editor after init. You'll be prompted for:
+- **LINE Channel Access Token** — from step 1
+- **LINE Channel Secret** — from step 1
+- **ngrok domain** — from step 2 (leave empty to skip tunnel)
+
+The MCP server starts automatically, including the webhook server and ngrok tunnel.
+
+### Manual Configuration (without init wizard)
+
+If you prefer manual setup or use a different MCP client:
+
+<details>
+<summary>Claude Code (.mcp.json)</summary>
+
+Create `.mcp.json` in your project root:
+```json
+{
+  "mcpServers": {
+    "line-hive": {
+      "command": "npx",
+      "args": ["line-hive"],
+      "env": {
+        "LINE_CHANNEL_ACCESS_TOKEN": "${LINE_CHANNEL_ACCESS_TOKEN}",
+        "LINE_CHANNEL_SECRET": "${LINE_CHANNEL_SECRET}",
+        "NGROK_DOMAIN": "${NGROK_DOMAIN:-}",
+        "WORKSPACE_PATH": "/path/to/your/project"
+      }
+    }
+  }
+}
+```
+
+Set credentials in your shell profile, or use `claude mcp add` for secure storage:
+```bash
+claude mcp add --transport stdio \
+  --env LINE_CHANNEL_ACCESS_TOKEN=your-token \
+  --env LINE_CHANNEL_SECRET=your-secret \
+  --env NGROK_DOMAIN=your-domain.ngrok-free.dev \
+  --env WORKSPACE_PATH=/path/to/your/project \
+  line-hive -- npx @zoulabo/line-hive
+```
+
+Also install instructions: copy `templates/line-notification.instructions.md` to `.claude/rules/line-notification.md`.
+</details>
+
+<details>
+<summary>Claude Desktop (claude_desktop_config.json)</summary>
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):
+```json
+{
+  "mcpServers": {
+    "line-hive": {
+      "command": "npx",
+      "args": ["line-hive"],
+      "env": {
+        "LINE_CHANNEL_ACCESS_TOKEN": "your-token",
+        "LINE_CHANNEL_SECRET": "your-secret",
+        "NGROK_DOMAIN": "your-domain.ngrok-free.dev",
+        "WORKSPACE_PATH": "/path/to/your/project"
+      }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Any MCP Client (stdio)</summary>
+
+The server uses stdio transport (stdin/stdout for MCP JSON-RPC). Configure your client to run:
+```bash
+npx @zoulabo/line-hive
+```
+With these environment variables:
+- `LINE_CHANNEL_ACCESS_TOKEN` — required
+- `LINE_CHANNEL_SECRET` — required
+- `WORKSPACE_PATH` — recommended (for agent naming)
+- `NGROK_DOMAIN` — optional (enables webhook tunnel)
+</details>
+
+## MCP Tools
+
+| Tool | Purpose | Blocking |
+|------|---------|----------|
+| `line_set_status` | Set agent description + name (status auto-derived) | No |
+| `line_ask` | Send message + wait for reply (single tool call) | Yes |
+| `line_send_message` | Push message to LINE (use sparingly — costs quota) | Yes (default) |
+| `line_check_messages` | Fetch unclaimed inbound messages | No |
+| `line_list_agents` | List all active agents across editor windows | No |
+
+### Recommended Pattern
+
+```
+1. line_set_status({ description: "Running tests...", agentName: "Nova" })  → auto-status: working
+2. line_ask({ text: "3 tests failed. Fix?", agentName: "Nova" })            → auto-status: needs_input
+   → user replies                                                           → auto-status: working
+3. line_set_status({ description: "Applying fixes..." })                     → auto-status: working
+4. line_set_status({})                                                       → auto-status: idle
+```
+
+**Auto-status values**: `idle` | `working` | `needs_input` | `error` — the `status` parameter is not user-settable.
+
+## LINE Commands
+
+Send these to your LINE bot:
+
+| Command | Action |
+|---------|--------|
+| `status` / `s` / `?` | Show all agents with status |
+| A number (e.g. `2`) | Select that agent (always — never forwarded to agents) |
+| Any other text | Route to targeted/waiting agent |
+| ▶️ Continue (button) | Send a reply token to keep the conversation going |
+| 📊 Status (button) | Same as `?` |
+| 📬 N more (button) | Pop all queued messages to the agent at once |
+
+## Limitations
+
+### LINE Messaging API
+
+- **Push message quota** — free tier allows 200 push messages/month. Status queries via replyToken are free and unlimited. The server uses reply token pooling to minimize push usage. `line_ask` prefers reply tokens but falls back to push when none are available.
+- **Reply token expiry** — tokens expire after ~15 minutes (empirically tested). The server pools and reuses them aggressively, but if no user interaction happens for a while, it falls back to push messages.
+- **Single webhook URL** — LINE allows only one webhook URL per channel. All agent instances must share the same tunnel endpoint.
+- **Text-only messages** — the server currently handles text messages only. Images, stickers, and rich media are ignored.
+- **One user** — designed for single-developer use. The bot interacts with one LINE user (auto-registered on first message).
+
+### Multi-Workspace
+
+- **Shared tunnel** — only the first editor window to start claims the webhook port and ngrok tunnel. Other windows connect to the same shared SQLite DB and piggyback on the existing webhook/tunnel.
+- **Shared credentials** — all workspaces use the same LINE channel. There's no per-workspace channel isolation.
+- **First-wins lifecycle** — if the first window is closed, the webhook server and tunnel stop. Other windows keep running (MCP tools still work via push messages) but webhook-based features (free replies, real-time routing) are unavailable until a window restarts and claims the port.
+
+### Webhook Tunnel
+
+- **Any tunnel works** — the webhook server is a standard HTTP server on port 19780. Use ngrok, cloudflared, VS Code Ports, localtunnel, or any reverse tunnel.
+- **ngrok auto-managed** — when `NGROK_DOMAIN` is set, the server spawns and auto-restarts ngrok as a child process. Other tunnels must be started manually.
+- **ngrok free tier limits** — one stable domain, rate limits. Paid plan removes these.
+- **Stable URL recommended** — without a stable domain/URL, you need to update the LINE Console webhook URL on every restart.
+
+### Claude Code
+
+- **`MCP_TOOL_TIMEOUT`** — Claude Code enforces a timeout on individual MCP tool calls. `line_ask` can block for up to 2 hours waiting for user replies. If `MCP_TOOL_TIMEOUT` is set to a shorter value, `line_ask` calls may be terminated prematurely. Consider using the poll-centric flow (`line_set_status` + `line_check_messages`) if you hit timeout issues.
+- **`--editor claude-code` required** — auto-detection of Claude Code is best-effort. Always pass `--editor claude-code` explicitly when running the init wizard. This applies whether you use Claude Code as a CLI tool, a VS Code extension, or a Cursor extension.
+- **Instructions location** — Claude Code reads `.claude/rules/`, not `.github/instructions/`. The init wizard writes to the correct location based on the `--editor` flag.
+
+## Development
+
+For contributing or running from source:
+
+```bash
+git clone https://github.com/zoulabo/line-hive && cd line-hive
+npm install && npm run build
+
+npm run build          # Compile TypeScript
+npm run watch          # Watch mode
+npm test               # Run tests (vitest)
+npm start              # Start standalone server
+```
+
+### CLI Commands
+
+```bash
+npx @zoulabo/line-hive init [--editor ...]   # Setup or update project config
+npx @zoulabo/line-hive test                 # Test LINE API connection
+```
+
+### Updating
+
+```bash
+npm update @zoulabo/line-hive  # Update the package
+npx @zoulabo/line-hive init    # Refresh config files and instruction templates
+```
+
+Re-running `init` is safe — it overwrites templates with the latest version while preserving your mcp.json credentials (prompted inputs).
+
+### Environment Variables
+
+For standalone `npm start` (not needed when running via VS Code MCP):
+
+```bash
+LINE_CHANNEL_ACCESS_TOKEN=   # From LINE Developers Console
+LINE_CHANNEL_SECRET=         # For webhook signature verification
+NGROK_DOMAIN=                # Optional — enables auto-managed ngrok tunnel
+                             # Omit if using a different tunnel (cloudflared, VS Code Ports, etc.)
+WEBHOOK_PORT=19780
+WEBHOOK_PATH=/webhook
+SQLITE_PATH=~/.line-hive/line-hive.db
+```
+
+### Project Structure
+
+```
+src/
+├── index.ts              # Entry point
+├── server.ts             # MCP server + tool handlers
+├── config.ts             # Environment config
+├── logger.ts             # Pino (stderr only — stdout is MCP)
+├── tunnel.ts             # ngrok tunnel management
+├── cli/
+│   ├── init.ts           # Setup wizard
+│   ├── test-connection.ts # LINE API connection test
+│   ├── config-writer.ts  # Generates mcp.json + instructions
+│   └── webhook-capture.ts # Temp server to capture userId
+├── tools/                # MCP tool implementations
+├── line/
+│   ├── client.ts         # LINE API client
+│   ├── messages.ts       # Message builders, quick reply, postback
+│   └── webhook.ts        # Webhook handler + status responder
+├── store/
+│   ├── messageStore.ts   # Message persistence (SQLite)
+│   └── statusStore.ts    # Agent status management
+├── util/
+│   └── sendWithTokenPool.ts # Reply token pool → push fallback
+└── types/
+    └── index.ts
+```
+
+## Troubleshooting
+
+<details>
+<summary><b>MCP server fails to start</b></summary>
+
+Run `npx @zoulabo/line-hive test` to diagnose. Common causes:
+- **Missing credentials** — `LINE_CHANNEL_ACCESS_TOKEN` or `LINE_CHANNEL_SECRET` not set. VS Code/Cursor prompt at startup; Claude Code needs env vars.
+- **Port 19780 in use** — Another process is using the webhook port. Kill it: `lsof -ti :19780 | xargs kill`
+- **Node.js < 18** — Requires Node.js 18+.
+</details>
+
+<details>
+<summary><b>LINE bot doesn't respond to messages</b></summary>
+
+1. Run `npx @zoulabo/line-hive test` to verify API connection
+2. Check that the webhook URL is set in [LINE Developers Console](https://developers.line.biz/console/) → *Messaging API* → *Webhook URL*
+3. Verify *Use webhook* is toggled **On**
+4. Make sure auto-reply is **disabled**: *Messaging API* → *Auto-reply messages* → *Edit* → turn off both responses
+5. Ensure the MCP server is running (check your editor's MCP status)
+</details>
+
+<details>
+<summary><b>Claude Code: "which --editor should I use?"</b></summary>
+
+Use `--editor claude-code` whether you're running Claude Code as:
+- A standalone CLI tool
+- A VS Code extension
+- A Cursor extension
+
+Don't use `--editor vscode` — that's for GitHub Copilot.
+</details>
+
+<details>
+<summary><b>Reply tokens expire / push message quota exceeded</b></summary>
+
+- Reply tokens expire after ~15 minutes. The server pools them aggressively but falls back to push messages when none are available.
+- Free tier: 200 push messages/month. Status queries via `?` are free (use reply tokens).
+- Tip: Send `?` in LINE periodically to replenish the token pool.
+</details>
+
+<details>
+<summary><b>ngrok tunnel not starting</b></summary>
+
+1. Confirm ngrok is installed: `ngrok version`
+2. Check auth: `ngrok config check`
+3. Set `NGROK_DOMAIN` env var to your stable domain
+4. The tunnel auto-starts with the MCP server — only one instance can run the tunnel.
+</details>
+
+## Architecture
+
+- **SQLite** (WAL mode) shared across all agent instances at `~/.line-hive/line-hive.db`
+- **Heartbeat** every 10s — dead agents auto-cleaned after 2 min
+- **Reply token pooling** — webhook saves tokens for free replies (saves push quota)
+- **Session correlation** — `line_ask` creates a session, webhook fulfills it on reply
+- **Multi-agent routing** — user selects agent by number, or auto-routes to `needs_input` agent
+- **Embedded tunnel** — ngrok auto-managed as child process (optional; any tunnel to localhost:19780 works)
+- **Cross-platform** — works on macOS, Linux, and Windows
+
+## License
+
+MIT

package/bin/line-hive.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+async function run() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (command === "init") {
+    // Usage: line-hive init [projectDir] [--editor vscode|cursor|claude-code|claude-desktop]
+    const editorIdx = args.indexOf("--editor");
+    const editor = editorIdx !== -1 && args[editorIdx + 1] ? args[editorIdx + 1] : undefined;
+    // Project dir is first positional arg after "init" that isn't a flag or flag value
+    const positional = args.slice(1).filter((a, i) => {
+      if (a.startsWith("--")) return false;
+      const origIdx = i + 1; // offset for args (since we sliced from 1)
+      return origIdx !== editorIdx + 1; // skip the value after --editor
+    });
+    const projectDir = positional[0] || process.cwd();
+    const modulePath = path.join(__dirname, "..", "dist", "cli", "init.js");
+    const moduleUrl = pathToFileURL(modulePath).href;
+    const mod = await import(moduleUrl);
+    await mod.runCli(path.resolve(projectDir), editor);
+    return;
+  }
+
+  if (command === "test") {
+    const modulePath = path.join(__dirname, "..", "dist", "cli", "test-connection.js");
+    const moduleUrl = pathToFileURL(modulePath).href;
+    const mod = await import(moduleUrl);
+    await mod.runTestConnection();
+    return;
+  }
+
+  const modulePath = path.join(__dirname, "..", "dist", "index.js");
+  const moduleUrl = pathToFileURL(modulePath).href;
+  await import(moduleUrl);
+}
+
+run();