@zoulabo/line-hive 0.1.0

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@zoulabo/line-hive",
+  "version": "0.1.0",
+  "description": "MCP server connecting AI coding agents to LINE Messaging API. Monitor agent progress, provide input, and get notifications from your phone.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "line-hive": "./bin/line-hive.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zoulabo/line-hive"
+  },
+  "homepage": "https://github.com/zoulabo/line-hive#readme",
+  "bugs": {
+    "url": "https://github.com/zoulabo/line-hive/issues"
+  },
+  "keywords": [
+    "mcp",
+    "line",
+    "messaging",
+    "copilot",
+    "cursor",
+    "claude",
+    "ai-agent",
+    "notifications",
+    "model-context-protocol"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist/",
+    "bin/",
+    "templates/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "watch": "tsc --watch -p tsconfig.json",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@line/bot-sdk": "^9.0.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "better-sqlite3": "^11.0.0",
+    "pino": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.0.0",
+    "@types/node": "^20.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  }
+}

package/templates/line-notification.instructions.md

@@ -0,0 +1,105 @@
+# LINE Communication Protocol
+
+**HARD RULE: When a LINE session is active, all replies MUST be sent via `line_ask`. Do not respond in this chat.**
+
+You have LINE messaging tools available. The user monitors your progress via LINE on their phone.
+
+LINE tools are **only used during LINE sessions** — two-way conversations initiated by the user. Outside of a LINE session, do not call any `line_*` tools.
+
+## LINE Session
+
+A LINE session means the user is communicating via LINE. When active, use `line_ask` for all communication and `line_set_status` for progress updates.
+
+### Activation — starts when ANY of these happen:
+- User says "continue on LINE", "talk on LINE", "notify me on LINE", or similar
+- User says "preapprove for LINE", "preapproval for LINE", "prepare for LINE", or "prime LINE" (prepare and continue in LINE; run pre-flight, then activate session)
+- You receive a `pendingReply` from `line_set_status`
+- You call `line_ask`
+
+### Agent Naming
+
+**First `line_set_status` call — always include `agentName`**: Pick a unique, creative, gender-neutral persona name. Be inventive — mythological, celestial, elemental, or abstract names work well. **Avoid common/obvious names.** Check `line_list_agents` first and pick something not already in use. Without `agentName`, messages show the generic workspace name.
+
+**Name uniqueness is enforced by the server.** If another live agent already uses the same `agentName`, `line_set_status`, `line_ask`, and `line_send_message` will return an `agent_name_taken` error. If this happens, pick a different name and retry.
+
+After your first call with `agentName`, the server remembers it — no need to repeat in `line_set_status`. However, **always pass `agentName` to `line_ask`** for correct routing when multiple agents share the same workspace.
+
+### Pre-Flight Tool Approval
+
+When a LINE session is activated by the user (they say "continue on LINE", "preapprove for LINE", etc.), you MUST run a pre-flight approval sequence **before** the user leaves. This ensures the agent won't block on tool permission prompts while the user is away.
+
+**Steps:**
+1. Tell the user: "I need to trigger tool approvals. Accept each permission prompt. Then **send `?` in LINE or tap Continue** to prime a reply token, and confirm here when done."
+2. Fire all non-ask approval triggers in parallel:
+   - **File read**: `read_file("package.json", limit: 3)`
+   - **Terminal**: `ls package.json` (or `dir package.json` on Windows)  
+     *(a real filesystem command triggers tool permission grants)*
+   - **File edit**: `create_file("/dev/null", "")` (triggers file-write permission without modifying any real file)
+   - **LINE status**: `line_set_status({ description: "pre-flight", agentName: "<name>" })`
+   - **LINE list agents**: `line_list_agents()` (for name uniqueness check)
+3. **Do NOT call `line_ask` during pre-flight** — no reply token exists yet, so it would waste a push message. Wait for the user to confirm they've sent `?` in LINE or tapped Continue.
+4. Once the user confirms (types anything in chat like "done", "ready", "ok"), start the LINE session with `line_ask`. The primed reply token ensures the first message is free.
+
+**Skip pre-flight when:**
+- The session was activated by `pendingReply` (user already at phone, tools should already be approved from earlier interaction)
+- The user has already approved tools earlier in the same conversation
+- The agent runs with auto-approved tool permissions (e.g., Claude Code with `--dangerously-skip-permissions`)
+
+### Deactivation — ends ONLY when:
+- **User types directly into the chat** — they're back at the computer
+- User explicitly says "stop LINE" or "go quiet"
+
+### CRITICAL: Never End a Session Based on Message Content
+
+**NEVER interpret the user's reply as a reason to stop the LINE session.** The user may say "done", "ok", "thanks", "got it", "no more", or similar — these are conversational replies, NOT deactivation signals. Always call `line_ask` again after processing any reply.
+
+The ONLY deactivation triggers are listed above. Everything else keeps the session going.
+
+### Active Session Rules
+
+1. **Use `line_ask` for all communication.** It sends your message and waits for the reply in one step. **Always pass `agentName`** for correct routing: `line_ask({ text: "...", agentName: "<name>" })`.
+2. **Never use `line_send_message`** during an active session — it's for internal use only.
+3. **The server automatically appends** `— Waiting for your reply (Xh timeout)` to every `line_ask` message with the actual timeout duration. You do NOT need to add this yourself.
+4. **After receiving a reply, always call `line_ask` again** with your next update or question. Keep the loop going until timeout or explicit deactivation.
+5. **`queuedRemaining`** in the `line_ask` response shows how many user messages are queued. When `queuedRemaining > 0`, the LINE message automatically shows a "📬 N more" button. The user taps it to pop the next message to the agent — no extra action needed from you.
+6. **Use `line_set_status` for progress updates** between `line_ask` calls. Status is auto-managed based on your tool calls — you only set the description:
+   - `line_set_status({ description: "<task>" })` — sets status to "working" with the given description
+   - `line_set_status({})` or `line_set_status({ description: null })` — sets status to "idle"
+   - Other statuses are set automatically: `needs_input` when `line_ask` starts waiting, `error` on failures/cancellations, `idle` on timeouts
+7. **Every `line_set_status` call may return a `pendingReply`**. Always check and act on it.
+8. **Keep messages short** — 1-3 sentences. No multi-paragraph essays.
+9. **Never send filler messages** — no "Resending...", "Processing...", "Still here...", or similar noise. Only send messages with real content.
+
+### Timeout Handling
+
+When `line_ask` returns `{"success": false, "error": "timeout"}`, the agent status is automatically set to `idle`. Stop the loop. The user will reply when ready — their message creates a `pendingReply` that you'll receive on your next `line_set_status` call, which re-activates the LINE session.
+
+> **Note:** The user may send short messages (e.g., ".", "ok", "continue") just to replenish reply tokens. Treat these as keep-alives — do NOT reply to them, just continue waiting.
+
+### Outside a LINE Session
+
+Do NOT call any `line_*` tools. No status updates, no messages.
+
+## Interactive Mode (ON DEMAND)
+
+Off by default. Activate only when user explicitly requests confirmations — e.g., "ask me on LINE before changes", "confirm on LINE".
+
+When active, **before** modifying files or running commands:
+
+```
+line_ask("⏳ About to: <action summary> — confirm?")
+```
+
+If the user says no, respect that. For batched operations, send a single confirmation.
+
+Interactive mode implies an active LINE session. Both deactivate together.
+
+## DO NOT
+
+- Call `line_*` tools outside of a LINE session
+- Send LINE messages when the user is typing directly in the chat
+- Interpret reply content ("done", "ok", "thanks") as session termination
+- Spam reports more often than every 2 minutes
+- Send filler messages ("Processing...", "Resending...", "Still here...")
+- Use interactive mode unless the user asked for it
+- **Pass LINE tools to subagents** — only the top-level agent should call `line_*` tools. When launching subagents (via `runSubagent` or similar), never include LINE tools in their prompt or capabilities