@rune-kit/rune 2.3.3 → 2.6.0

package/extensions/zalo/references/mcp-production.md

@@ -0,0 +1,274 @@
+# MCP Server Production Reference
+
+> Loaded by `@rune/zalo` when MCP server setup, production deployment, or cursor-based pagination patterns detected.
+
+---
+
+## MCP Server Modes
+
+### Local (stdio)
+
+```bash
+# Start MCP server in stdio mode (for local Claude Code / AI IDE)
+zalo-agent mcp start
+
+# Connects via stdin/stdout — AI agent calls tools directly
+```
+
+### Remote (HTTP)
+
+```bash
+# Start MCP server in HTTP mode (for remote agents, multi-client)
+zalo-agent mcp start --http 3847 --auth your-secret-token
+
+# Clients connect via HTTP transport with Bearer auth
+```
+
+---
+
+## Enhanced Tool Definitions
+
+### zalo_get_messages — Cursor-Based Pagination
+
+Replace simple queue polling with cursor-based pagination from a ring buffer:
+
+```typescript
+{
+  name: 'zalo_get_messages',
+  description: 'Get messages from ring buffer with cursor-based pagination.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      cursor: {
+        type: 'string',
+        description: 'Opaque cursor from previous response. Omit for latest messages.'
+      },
+      limit: {
+        type: 'number',
+        default: 20,
+        maximum: 100,
+        description: 'Max messages to return'
+      },
+      thread_id: {
+        type: 'string',
+        description: 'Filter by specific thread. Omit for all threads.'
+      }
+    }
+  }
+}
+```
+
+Returns:
+
+```json
+{
+  "messages": [
+    {
+      "id": "msg_abc123",
+      "thread_id": "user_456",
+      "sender_name": "Nguyen Van A",
+      "text": "Hello",
+      "timestamp": 1711234567890,
+      "type": "text",
+      "attachments": []
+    }
+  ],
+  "next_cursor": "eyJ0IjoxNzExMjM0NTY3ODkwfQ==",
+  "has_more": true
+}
+```
+
+### Implementation
+
+```typescript
+class RingBuffer {
+  private buffer: Message[] = []
+  private maxSize: number
+
+  constructor(maxSize = 5000) {
+    this.maxSize = maxSize
+  }
+
+  push(msg: Message) {
+    this.buffer.push(msg)
+    if (this.buffer.length > this.maxSize) {
+      this.buffer = this.buffer.slice(-this.maxSize) // keep newest
+    }
+  }
+
+  query(cursor?: string, limit = 20, threadId?: string): QueryResult {
+    let startIdx = 0
+
+    if (cursor) {
+      const decoded = JSON.parse(Buffer.from(cursor, 'base64url').toString())
+      startIdx = this.buffer.findIndex(m => m.timestamp > decoded.t)
+      if (startIdx === -1) startIdx = this.buffer.length
+    }
+
+    let filtered = this.buffer.slice(startIdx)
+    if (threadId) {
+      filtered = filtered.filter(m => m.thread_id === threadId)
+    }
+
+    const page = filtered.slice(0, limit)
+    const hasMore = filtered.length > limit
+
+    const nextCursor = page.length > 0
+      ? Buffer.from(JSON.stringify({ t: page[page.length - 1].timestamp })).toString('base64url')
+      : cursor
+
+    return { messages: page, next_cursor: nextCursor, has_more: hasMore }
+  }
+}
+```
+
+### zalo_list_threads — Active Conversations
+
+```typescript
+{
+  name: 'zalo_list_threads',
+  description: 'List active conversations with unread counts.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      limit: { type: 'number', default: 20 },
+      unread_only: { type: 'boolean', default: false }
+    }
+  }
+}
+```
+
+Returns: `{ threads: [{ id, name, type, unread_count, last_message_at }] }`
+
+### zalo_mark_read — Clear Buffer
+
+```typescript
+{
+  name: 'zalo_mark_read',
+  description: 'Mark messages as processed. Clears from unread count.',
+  inputSchema: {
+    type: 'object',
+    required: ['thread_id'],
+    properties: {
+      thread_id: { type: 'string' },
+      up_to_cursor: { type: 'string', description: 'Mark all messages up to this cursor as read' }
+    }
+  }
+}
+```
+
+### zalo_view_image — Media Download
+
+```typescript
+{
+  name: 'zalo_view_image',
+  description: 'Download and view an image from a Zalo message locally.',
+  inputSchema: {
+    type: 'object',
+    required: ['message_id'],
+    properties: {
+      message_id: { type: 'string' },
+      save_to: { type: 'string', description: 'Local path to save. Default: temp directory.' }
+    }
+  }
+}
+```
+
+---
+
+## MCP Configuration
+
+```json
+// mcp-config.json
+{
+  "watchThreads": ["group_abc", "user_xyz"],
+  "keywords": ["help", "support", "bug"],
+  "buffer": {
+    "maxSize": 5000,
+    "persistPath": "./mcp-buffer.json"
+  },
+  "autoReconnect": true,
+  "reconnectDelayMs": 5000
+}
+```
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| `watchThreads` | Only capture messages from these threads | All threads |
+| `keywords` | Keyword triggers — only buffer matching messages | All messages |
+| `buffer.maxSize` | Ring buffer capacity | 5000 |
+| `buffer.persistPath` | Persist buffer to disk on shutdown | In-memory only |
+| `autoReconnect` | Auto-reconnect WebSocket on disconnect | true |
+| `reconnectDelayMs` | Delay before reconnect attempt | 5000 |
+
+---
+
+## Production Deployment
+
+### pm2 (Recommended)
+
+```bash
+# ecosystem.config.js
+module.exports = {
+  apps: [{
+    name: 'zalo-mcp',
+    script: 'zalo-agent',
+    args: 'mcp start --http 3847 --auth $MCP_AUTH_SECRET',
+    autorestart: true,
+    max_restarts: 10,
+    restart_delay: 5000,
+    env: {
+      NODE_ENV: 'production',
+      MCP_AUTH_SECRET: 'your-secret'
+    }
+  }]
+}
+
+# Start
+pm2 start ecosystem.config.js
+pm2 save
+pm2 startup
+```
+
+### WebSocket Session Management
+
+```
+Key constraints:
+1. ONE WebSocket connection per Zalo account — no parallelism
+2. Browser Zalo and bot CANNOT coexist on same account
+3. WebSocket drops on network change → auto-reconnect required
+4. Session cookie expires → re-login with stored credentials
+```
+
+### Health Check Pattern
+
+```typescript
+// Periodic health check for MCP + WebSocket
+setInterval(async () => {
+  const wsAlive = api.isConnected()
+  const lastMsg = ringBuffer.getLatest()?.timestamp ?? 0
+  const silentMinutes = (Date.now() - lastMsg) / 60_000
+
+  if (!wsAlive) {
+    logger.error('WebSocket disconnected — attempting reconnect')
+    await api.reconnect()
+  }
+
+  if (silentMinutes > 30 && wsAlive) {
+    logger.warn(`No messages for ${silentMinutes.toFixed(0)}m — possible silent disconnect`)
+    // Force reconnect if no messages for 60+ minutes
+    if (silentMinutes > 60) await api.reconnect()
+  }
+}, 60_000) // check every minute
+```
+
+---
+
+## Sharp Edges
+
+- **Ring buffer vs queue**: Ring buffer overwrites oldest when full (no data loss notification). Queue drops with warning. Choose based on whether losing old messages is acceptable.
+- **Cursor encoding**: Use `base64url` not `base64` — cursors appear in URLs and JSON, `+` and `/` cause issues
+- **HTTP MCP auth**: `--auth` token is sent as `Bearer` header — use HTTPS in production or attacker can sniff the token
+- **pm2 + credentials**: Never pass credentials as CLI args (visible in `ps aux`) — use env vars or credential file
+- **Buffer persistence**: If `persistPath` is set, buffer writes to disk on SIGTERM — unclean kill loses buffered messages
+- **WebSocket single-session**: Starting MCP server kicks out browser Zalo. Warn user before starting.

package/extensions/zalo/references/multi-account-proxy.md

@@ -0,0 +1,224 @@
+# Multi-Account & Proxy Management Reference
+
+> Loaded by `@rune/zalo` when multi-account setup, proxy configuration, or production account management patterns detected.
+
+---
+
+## Multi-Account Architecture
+
+Run multiple Zalo accounts on a single server — each with its own session, proxy, and WebSocket connection.
+
+### Account Operations
+
+| Command | Description |
+|---------|-------------|
+| `account list` | Show all registered accounts (ID, name, status, proxy) |
+| `account login -n <name> -p <proxy>` | Login new account with proxy |
+| `account switch <ownerId>` | Switch active account |
+| `account remove <ownerId>` | Remove account and credentials |
+| `account info <ownerId>` | Show account details |
+| `account export -o <path>` | Export credentials for headless re-login |
+
+### Login Flow
+
+```bash
+# First account — interactive QR login
+zalo-agent login --qr-url
+# Opens http://localhost:18927/qr — scan with Zalo app
+
+# Additional accounts — with proxy
+zalo-agent account login \
+  -n "support-bot" \
+  -p "socks5://user:pass@proxy1.example.com:1080"
+
+# Headless re-login (VPS, CI/CD)
+zalo-agent account export -o ./creds-support.json
+zalo-agent login --credentials ./creds-support.json
+```
+
+### QR Server Ports
+
+Port auto-tries in order: `18927 → 8080 → 3000 → 9000`. QR code expires after **60 seconds**.
+
+For VPS without browser access:
+
+```bash
+# Start QR server accessible from outside
+zalo-agent login --qr-url
+# Access http://<VPS_IP>:18927/qr from your phone/laptop browser
+```
+
+---
+
+## Proxy Configuration
+
+### Why Proxies Are Required
+
+Zalo detects multiple accounts from the same IP address. Without proxies:
+- Accounts may be flagged for suspicious activity
+- Rate limits are shared across all accounts on the same IP
+- Ban on one account can cascade to others
+
+### Rules
+
+1. **1 unique proxy per account** — never share proxies between accounts
+2. **Residential proxies preferred** — datacenter IPs are flagged more aggressively
+3. **Vietnamese proxies recommended** — foreign IPs trigger additional verification
+4. **Consistent proxy** — don't rotate proxies for the same account (triggers re-verification)
+
+### Supported Formats
+
+```
+http://host:port
+http://user:pass@host:port
+https://user:pass@host:port
+socks5://host:port
+socks5://user:pass@host:port
+```
+
+### Implementation Pattern
+
+```typescript
+import { HttpsProxyAgent } from 'https-proxy-agent'
+import { SocksProxyAgent } from 'socks-proxy-agent'
+
+function createProxyAgent(proxyUrl: string) {
+  const url = new URL(proxyUrl)
+  if (url.protocol.startsWith('socks')) {
+    return new SocksProxyAgent(proxyUrl)
+  }
+  return new HttpsProxyAgent(proxyUrl)
+}
+
+// Per-account proxy assignment
+const accounts: Map<string, { api: ZaloApi; proxy: string }> = new Map()
+
+async function loginWithProxy(name: string, proxyUrl: string) {
+  const agent = createProxyAgent(proxyUrl)
+  const api = new ZaloApi({ proxy: agent, name })
+  await api.login()
+  accounts.set(api.ownerId, { api, proxy: proxyUrl })
+}
+```
+
+---
+
+## Credential Storage
+
+```
+~/.zalo-agent-cli/
+├── credentials.json        # Default account
+├── accounts/
+│   ├── <ownerId1>.json     # Account 1 credentials
+│   └── <ownerId2>.json     # Account 2 credentials
+└── config.json             # Global config (proxies, defaults)
+```
+
+### Security Rules
+
+- File permissions: `0600` (owner read/write only)
+- **Never** log credential file contents
+- **Never** commit to git (add to `.gitignore`)
+- **Never** pass credentials as CLI arguments (visible in `ps aux`)
+- Use environment variables or credential files for headless login
+
+```bash
+# .gitignore
+.zalo-agent-cli/
+*.zalo-creds.json
+```
+
+---
+
+## Account Switching in Code
+
+```typescript
+class AccountManager {
+  private accounts = new Map<string, ZaloApi>()
+  private active: string | null = null
+
+  async switch(ownerId: string): Promise<ZaloApi> {
+    const api = this.accounts.get(ownerId)
+    if (!api) throw new Error(`Account ${ownerId} not found`)
+    this.active = ownerId
+    return api
+  }
+
+  getActive(): ZaloApi {
+    if (!this.active) throw new Error('No active account')
+    return this.accounts.get(this.active)!
+  }
+
+  // Route messages to correct account
+  async routeMessage(msg: InboundMessage) {
+    const targetAccount = this.resolveAccount(msg.recipientId)
+    const api = this.accounts.get(targetAccount)
+    if (!api) return // account not managed
+
+    await api.sendMessage(msg.response, msg.threadId, msg.type)
+  }
+}
+```
+
+---
+
+## Production Multi-Account Setup
+
+### pm2 Ecosystem
+
+```javascript
+// ecosystem.config.js — one process per account
+module.exports = {
+  apps: [
+    {
+      name: 'zalo-bot-main',
+      script: 'zalo-agent',
+      args: 'listen -w http://localhost:3001/webhook',
+      env: { ZALO_ACCOUNT: 'main', ZALO_PROXY: 'socks5://user:pass@proxy1:1080' }
+    },
+    {
+      name: 'zalo-bot-support',
+      script: 'zalo-agent',
+      args: 'listen -w http://localhost:3001/webhook',
+      env: { ZALO_ACCOUNT: 'support', ZALO_PROXY: 'socks5://user:pass@proxy2:1080' }
+    }
+  ]
+}
+```
+
+### Health Monitoring
+
+```typescript
+// Check all accounts periodically
+async function healthCheck() {
+  for (const [id, { api, proxy }] of accounts) {
+    const connected = api.isConnected()
+    const status = await api.getStatus().catch(() => 'error')
+
+    if (!connected) {
+      logger.error(`Account ${id} disconnected via ${proxy}`)
+      await api.reconnect()
+    }
+
+    if (status === 'banned') {
+      logger.critical(`Account ${id} BANNED — removing from rotation`)
+      accounts.delete(id)
+      // Alert operator
+    }
+  }
+}
+
+setInterval(healthCheck, 5 * 60_000) // every 5 minutes
+```
+
+---
+
+## Sharp Edges
+
+- **Proxy per account**: Sharing proxies between accounts = ban risk for ALL accounts on that proxy
+- **QR expiry**: 60 seconds — have Zalo app ready before starting login
+- **Session conflicts**: Only ONE active session per account — starting a new login invalidates existing sessions
+- **Credential export**: Exported JSON contains session cookies — treat as sensitive as passwords
+- **VPS QR access**: Firewall must allow inbound on QR port (18927) — close after login
+- **Proxy rotation**: Do NOT rotate proxies for established sessions — Zalo treats IP change as suspicious
+- **Rate limits per account**: Each account has independent rate limits — but shared IP without proxy means shared rate limit bucket

package/extensions/zalo/references/vietqr-banking.md

@@ -0,0 +1,160 @@
+# VietQR & Banking Reference
+
+> Loaded by `@rune/zalo` when payment, bank transfer, QR code, or VietQR patterns detected.
+
+---
+
+## VietQR Transfer Messages
+
+Send bank transfer QR codes directly in Zalo chat — recipient scans to pay via their banking app.
+
+### Send Bank Card
+
+```bash
+# CLI: send bank card with account details
+zalo-agent msg send-card -t <threadId> \
+  --bank vcb \
+  --account-number 1234567890 \
+  --account-name "NGUYEN VAN A"
+
+# With custom amount and message
+zalo-agent msg send-card -t <threadId> \
+  --bank mbbank \
+  --account-number 0987654321 \
+  --account-name "TRAN THI B" \
+  --amount 500000 \
+  --message "Thanh toan don hang #123"
+```
+
+### Send QR Transfer
+
+```bash
+# Generate VietQR and send as image
+zalo-agent msg send-qr-transfer -t <threadId> \
+  --bank techcombank \
+  --account-number 19033456789 \
+  --account-name "LE VAN C" \
+  --amount 1000000 \
+  --message "Tien thue thang 3"
+```
+
+### Implementation Pattern
+
+```typescript
+import { generateVietQR } from './vietqr-utils'
+
+interface BankTransfer {
+  bankCode: string       // BIN code or alias (e.g., 'vcb', 'mbbank')
+  accountNumber: string
+  accountName: string
+  amount?: number
+  message?: string       // Noi dung chuyen khoan
+}
+
+async function sendBankCard(api: ZaloApi, threadId: string, transfer: BankTransfer) {
+  // 1. Resolve bank alias to BIN code
+  const bin = BANK_ALIASES[transfer.bankCode] ?? transfer.bankCode
+
+  // 2. Generate VietQR URL (NAPAS standard)
+  const qrUrl = `https://img.vietqr.io/image/${bin}-${transfer.accountNumber}-compact.png`
+    + (transfer.amount ? `?amount=${transfer.amount}` : '')
+    + (transfer.message ? `&addInfo=${encodeURIComponent(transfer.message)}` : '')
+
+  // 3. Download QR image to temp file
+  const tempPath = await downloadToTemp(qrUrl)
+
+  // 4. Send as image with caption
+  const caption = [
+    `🏦 ${BANK_NAMES[bin] ?? bin}`,
+    `📋 STK: ${transfer.accountNumber}`,
+    `👤 ${transfer.accountName}`,
+    transfer.amount ? `💰 ${new Intl.NumberFormat('vi-VN').format(transfer.amount)} VND` : null,
+    transfer.message ? `📝 ${transfer.message}` : null,
+  ].filter(Boolean).join('\n')
+
+  await api.sendMessage({ body: caption, attachments: [tempPath] }, threadId, 'User')
+}
+```
+
+---
+
+## Vietnamese Bank Aliases
+
+55+ banks supported via VietQR / NAPAS standard:
+
+| Alias | Bank Name | BIN |
+|-------|-----------|-----|
+| `vcb`, `vietcombank` | Vietcombank | 970436 |
+| `bidv` | BIDV | 970418 |
+| `vietinbank`, `ctg` | VietinBank | 970415 |
+| `agribank` | Agribank | 970405 |
+| `mb`, `mbbank` | MB Bank | 970422 |
+| `techcombank`, `tcb` | Techcombank | 970407 |
+| `acb` | ACB | 970416 |
+| `vpbank` | VPBank | 970432 |
+| `tpbank` | TPBank | 970423 |
+| `sacombank`, `stb` | Sacombank | 970403 |
+| `hdbank` | HDBank | 970437 |
+| `ocb` | OCB | 970448 |
+| `msb` | MSB | 970426 |
+| `seabank` | SeABank | 970440 |
+| `shb` | SHB | 970443 |
+| `eximbank` | Eximbank | 970431 |
+| `vib` | VIB | 970441 |
+| `scb` | SCB | 970429 |
+| `ncb` | NCB | 970419 |
+| `abbank` | ABBank | 970425 |
+| `dongabank` | DongA Bank | 970406 |
+| `kienlongbank` | Kien Long Bank | 970452 |
+| `baovibank` | BaoViet Bank | 970438 |
+| `pvcombank` | PVcomBank | 970412 |
+| `lienvietpostbank`, `lpb` | LienVietPostBank | 970449 |
+| `namabank` | Nam A Bank | 970428 |
+| `pgbank` | PG Bank | 970430 |
+| `vietabank` | VietA Bank | 970427 |
+| `bacabank` | Bac A Bank | 970409 |
+| `saigonbank` | Saigon Bank | 970400 |
+| `gpbank` | GP Bank | 970408 |
+| `cbbank` | CB Bank | 970444 |
+| `oceanbank` | OceanBank | 970414 |
+| `shinhan` | Shinhan Vietnam | 970424 |
+| `hsbc` | HSBC Vietnam | 970443 |
+| `cimb` | CIMB Vietnam | 422589 |
+| `woori` | Woori Vietnam | 970457 |
+| `uob` | UOB Vietnam | 970458 |
+| `standardchartered`, `sc` | Standard Chartered VN | 970410 |
+| `publicbank` | Public Bank VN | 970439 |
+| `cake` | CAKE (VPBank Digital) | 546034 |
+| `ubank` | Ubank (VPBank) | 546035 |
+| `timo` | Timo (Ban Viet) | 963388 |
+| `vnptmoney` | VNPT Money | 971011 |
+| `momo` | MoMo (via NAPAS) | 999996 |
+| `zalopay` | ZaloPay (via NAPAS) | 999997 |
+| `viettelpay` | ViettelPay | 971005 |
+
+### Alias Lookup
+
+```typescript
+const BANK_ALIASES: Record<string, string> = {
+  vcb: '970436', vietcombank: '970436',
+  bidv: '970418',
+  vietinbank: '970415', ctg: '970415',
+  agribank: '970405',
+  mb: '970422', mbbank: '970422',
+  techcombank: '970407', tcb: '970407',
+  acb: '970416',
+  vpbank: '970432',
+  tpbank: '970423',
+  // ... extend as needed
+}
+```
+
+---
+
+## Sharp Edges
+
+- **VietQR image service**: `img.vietqr.io` is free but rate-limited — cache generated QR images locally for repeated sends
+- **Amount encoding**: Must be integer (VND has no decimal). `500000` not `500,000` or `500.000`
+- **Message encoding**: `addInfo` must be URL-encoded, max 25 characters (NAPAS limit), ASCII only — no Vietnamese diacritics
+- **Bank BIN codes**: Change rarely but verify against NAPAS registry for production use
+- **QR expiry**: VietQR codes don't expire — they encode static account info. But amounts can become stale if prices change

package/hooks/hooks.json

@@ -12,6 +12,18 @@
         ]
       }
     ],
+    "UserPromptSubmit": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cjs\" intent-router",
+            "async": true
+          }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "Read|Write|Edit",