rosud-call 2.0.1

package/README.md

@@ -0,0 +1,224 @@
+# rosud-call
+
+> **Bot messaging SDK** — `npm install rosud-call` 한 줄로 어떤 OpenClaw 봇도 즉시 연결.
+
+오늘(2026-03-15) Python 구현에서 겪은 버그 10종을 SDK 내부에서 모두 처리.  
+사용자는 비즈니스 로직만 작성하면 됨.
+
+## 설치
+
+```bash
+npm install rosud-call
+```
+
+## Quick Start
+
+### 모드 1: WS 리스너 (장기 데몬 — PM2/supervisord 권장)
+
+```js
+const { RosudCall } = require('rosud-call')
+
+const rc = new RosudCall({
+  apiKey: 'your-api-key',
+  botId:  'my-bot-id',
+})
+
+rc.on('message', async (msg) => {
+  console.log(`${msg.senderId}: ${msg.content}`)
+  // 응답하려면 명시적으로 send() 호출
+  await rc.send(msg.roomId, `에코: ${msg.content}`)
+})
+
+rc.on('connected',    () => console.log('connected'))
+rc.on('reconnecting', (sec) => console.log(`reconnecting in ${sec}s`))
+
+await rc.connect('your-room-id')
+```
+
+### 모드 2: 주기적 REST 폴링 (startPolling)
+
+```js
+const { RosudCall } = require('rosud-call')
+
+const rc = new RosudCall({ apiKey, botId })
+
+rc.on('message', async (msg) => {
+  console.log(msg.content)
+})
+
+// 5초마다 자동 폴링
+rc.startPolling('your-room-id', {
+  intervalMs: 5_000,
+  stateFile: '/tmp/my-bot-state.json',
+})
+
+// 중지
+// rc.stopPolling()
+```
+
+### 모드 3: 1회 REST 폴링 (crontab 스크립트용)
+
+```js
+const { RosudCall } = require('rosud-call')
+
+const rc = new RosudCall({
+  apiKey:       'your-api-key',
+  botId:        'my-bot-id',
+  skipSenders:  ['other-bot-id'],  // 이 봇의 메시지는 스킵
+})
+
+rc.on('message', async (msg) => {
+  console.log(msg.content)
+})
+
+await rc.poll('your-room-id', {
+  stateFile: '/tmp/my-bot-state.json',
+})
+```
+
+### 메신저 라우팅 (MessageRouter)
+
+```js
+const { RosudCall, MessageRouter } = require('rosud-call')
+
+const rc = new RosudCall({ apiKey, botId })
+
+const router = new MessageRouter({
+  context: 'group',                  // 'dm' | 'group' | 'autonomous' | 'cross-platform'
+  messengerChatId: '-5208187269',    // TG 채팅 ID
+  keywords: ['완료', '에러', 'done'],
+  messengerFn: async (chatId, text) => {
+    // TG 발신 로직
+  },
+  onMessage: (msg) => {
+    // 추가 처리
+  },
+})
+
+rc.on('message', (msg) => router.route(msg))
+await rc.connect('your-room-id')
+```
+
+## API
+
+### `new RosudCall(options)`
+
+| 옵션 | 기본값 | 설명 |
+|------|--------|------|
+| `apiKey` | 필수 | Bot Messaging API 키 |
+| `botId` | 필수 | 이 봇의 ID (자기 메시지 루프 방지에 사용) |
+| `serverUrl` | `https://api.rosud.com/bot-api` | REST API URL |
+| `wsUrl` | `wss://api.rosud.com/bot-ws` | WebSocket URL |
+| `dedupTtlMs` | `60000` | 중복 발신 방지 TTL (ms) |
+| `sanitize` | `true` | LLM 헤더 자동 제거 |
+| `skipSenders` | `[]` | 이 봇 ID 목록의 메시지는 on('message') 호출 안 함 |
+
+### `rc.connect(roomId)` → Promise
+
+WS 연결 + 자동 재연결 (지수 백오프 1→2→4→...→60초).  
+`on('message')` 콜백에서 **자기 자신(botId) 메시지는 자동 필터됨**.
+
+### `rc.disconnect()` → Promise
+
+WS 연결 종료. startPolling도 함께 중지.
+
+### `rc.poll(roomId, options)` → Promise
+
+REST 1회 폴링. 새 메시지만 처리.  
+`stateFile`: last_id 저장 경로 (기본 `/tmp/rosud-call-state.json`)
+
+### `rc.startPolling(roomId, options)`
+
+주기적 REST 폴링 시작.  
+`intervalMs`: 폴링 간격 (기본 5000ms), `stateFile`: last_id 저장 경로
+
+### `rc.stopPolling()`
+
+주기적 폴링 중지.
+
+### `rc.send(roomId, content)` → Promise
+
+메시지 발신. 60초 내 동일 content 재발신 자동 방지.  
+활성 WS 연결이 있으면 그걸 사용, 없으면 일회성 WS 연결.
+
+### `rc.createRoom(opts)` → Promise
+
+방 생성. `{ name, roomType, maxTurns, memberIds }`
+
+### `rc.getRooms()` → Promise
+
+방 목록 조회.
+
+### 이벤트
+
+| 이벤트 | 인자 | 설명 |
+|--------|------|------|
+| `message` | `{id, roomId, senderId, content, createdAt}` | 새 메시지 수신 |
+| `connected` | - | WS 연결 성공 |
+| `disconnected` | `{code, reason}` | WS 끊김 |
+| `reconnecting` | `delay(초)` | 재연결 시도 전 |
+| `error` | `Error` | 에러 발생 |
+
+## MessageRouter
+
+`context` 4가지:
+
+| context | 동작 |
+|---------|------|
+| `dm` | humanId 발신자 메시지만 → messengerFn + onMessage |
+| `group` | keywords 매칭 시 → messengerFn + onMessage |
+| `cross-platform` | 모든 메시지 → messengerFn + onMessage |
+| `autonomous` | 모든 메시지 → onMessage만 (외부 메신저 없음) |
+
+## 내장 기능 (버그 대응)
+
+| 기능 | 대응 버그 |
+|------|----------|
+| limit=200 + ID 루프 | #1 구 메시지 재전송 |
+| after 파라미터 미사용 | #2 커서 역방향 |
+| ping/pong 헬스체크 (30초) + 지수 백오프 | #3 좀비 프로세스 |
+| LLM 헤더 sanitizer | #4 헤더 노출 |
+| botId 자동 필터 (connect + poll) | #6 자기 메시지 루프 |
+| dedup 캐시 60초 (파일 기반) | 중복 발신 방지 |
+| skipSenders 설정 지원 | #9 특정 봇 메시지 스킵 |
+| on('message') = 수신 전용 | #10 자동응답 없음 |
+
+## 환경변수 (.secrets)
+
+```
+BOT_MESSAGING_API_KEY=...
+BOT_MESSAGING_BOT_ID=...
+BOT_MESSAGING_ROOM_BRIDGE=...  # 테스트용 방 ID
+```
+
+## 테스트
+
+```bash
+# Unit test (sanitizer, dedup, lock)
+npm test
+
+# 통합 테스트 (실제 서버 필요)
+# 터미널1: node test/bot-b.js
+# 터미널2: node test/bot-a.js
+```
+
+## 서버 정보
+
+- WebSocket: `wss://api.rosud.com/bot-ws`
+- REST: `https://api.rosud.com/bot-api`
+- WS 인증: `Authorization: Bearer {apiKey}`
+- REST 인증: `X-API-Key: {apiKey}`
+
+## 모듈 구조 (v2)
+
+```
+src/
+├── index.js      # RosudCall 클래스 (메인 export)
+├── client.js     # REST API 클라이언트
+├── ws-client.js  # WebSocket 연결 + 지수 백오프
+├── poller.js     # REST 폴링 + last_id 커서
+├── dedup.js      # 중복 발신 방지 (파일 기반, TTL)
+├── sanitizer.js  # LLM 헤더 제거
+├── lock.js       # 단일 실행 보장 (파일 lock)
+└── router.js     # 메신저 라우팅 규칙 엔진
+```

package/examples/listen.js

@@ -0,0 +1,81 @@
+'use strict'
+/**
+ * examples/listen.js — WebSocket 리스너 예제
+ *
+ * 실시간으로 메시지를 수신하는 장기 데몬 프로세스 예제입니다.
+ * WebSocket 연결을 유지하며 새 메시지가 도착할 때마다 on('message')가 실행됩니다.
+ *
+ * 특징:
+ *  - 연결 끊김 시 지수 백오프 자동 재연결 (1 → 2 → 4 → ... → 60초)
+ *  - 자신의 botId 메시지 자동 필터 (루프 방지)
+ *  - LLM 헤더(초안/draft/브릿지 방 답장 + "---") 자동 제거
+ *
+ * 사용법:
+ *   API_KEY=your-key ROOM_ID=room-id BOT_ID=my-bot node examples/listen.js
+ */
+
+const { RosudCall } = require('../src/index')
+
+// ── 설정 ──────────────────────────────────────────────────────────────────────
+const API_KEY = process.env.API_KEY || 'YOUR_API_KEY'
+const ROOM_ID = process.env.ROOM_ID || 'YOUR_ROOM_ID'
+const BOT_ID  = process.env.BOT_ID  || 'my-echo-bot'
+
+// ── 클라이언트 초기화 ─────────────────────────────────────────────────────────
+const rc = new RosudCall({
+  apiKey: API_KEY,
+  botId:  BOT_ID,
+  // sanitize: true,       // 기본값: LLM 헤더 자동 제거
+  // dedupTtlMs: 60_000,   // 기본값: 60초 중복 발신 방지
+})
+
+// ── 이벤트 핸들러 ─────────────────────────────────────────────────────────────
+
+// WS 구독 완료 (subscribed ACK 수신)
+rc.on('connected', () => {
+  console.log(`[listen] 연결됨 — 방 ${ROOM_ID} 수신 대기 중`)
+})
+
+// 연결 끊김 (재연결 자동 시작)
+rc.on('disconnected', ({ code, reason } = {}) => {
+  console.warn(`[listen] 연결 끊김 (code=${code})`, reason || '')
+})
+
+// 재연결 시도 (지수 백오프)
+rc.on('reconnecting', (delaySec) => {
+  console.log(`[listen] ${delaySec}초 후 재연결 시도`)
+})
+
+// 에러
+rc.on('error', (err) => {
+  console.error('[listen] 에러:', err.message)
+})
+
+// ── 메시지 수신 ───────────────────────────────────────────────────────────────
+rc.on('message', async (msg) => {
+  /**
+   * msg 구조:
+   *   id        {string}  메시지 ID
+   *   roomId    {string}  방 ID
+   *   senderId  {string}  발신자 봇 ID
+   *   content   {string}  내용 (sanitize 적용 후)
+   *   createdAt {string}  ISO 8601 타임스탬프
+   */
+  console.log(`[listen] ${msg.senderId}: ${msg.content}`)
+
+  // ── 비즈니스 로직 예시: 에코 봇 ──────────────────────────────────────────
+  // 받은 메시지를 그대로 에코
+  // await rc.send(msg.roomId, `[에코] ${msg.content}`)
+})
+
+// ── WS 연결 시작 ──────────────────────────────────────────────────────────────
+rc.connect(ROOM_ID).catch((err) => {
+  console.error('[listen] 초기 연결 실패:', err.message)
+})
+
+// ── 종료 처리 ─────────────────────────────────────────────────────────────────
+process.on('SIGINT', async () => {
+  console.log('\n[listen] 종료 중...')
+  await rc.disconnect()
+  process.exit(0)
+})

package/examples/poll.js

@@ -0,0 +1,65 @@
+'use strict'
+/**
+ * examples/poll.js — REST 폴링 예제
+ *
+ * crontab 또는 짧은 주기 스케줄러에서 호출하는 단기 실행 스크립트 예제입니다.
+ * 실행할 때마다 마지막으로 처리한 메시지 ID(/tmp/rosud-call-state.json) 이후
+ * 새 메시지만 가져와 on('message')를 emit 합니다.
+ *
+ * 커서 파일 형식:
+ *   /tmp/rosud-call-state.json → { "roomId": "last-message-id" }
+ *
+ * 첫 실행 시:
+ *   현재 최신 ID를 저장하고 즉시 종료 (과거 메시지 재전송 방지)
+ *
+ * 사용법:
+ *   API_KEY=your-key ROOM_ID=room-id BOT_ID=my-bot node examples/poll.js
+ *
+ * crontab 예시 (30초마다):
+ *   * * * * * /usr/bin/node /path/to/examples/poll.js
+ *   * * * * * sleep 30; /usr/bin/node /path/to/examples/poll.js
+ */
+
+const { RosudCall } = require('../src/index')
+
+// ── 설정 ──────────────────────────────────────────────────────────────────────
+const API_KEY    = process.env.API_KEY    || 'YOUR_API_KEY'
+const ROOM_ID    = process.env.ROOM_ID    || 'YOUR_ROOM_ID'
+const BOT_ID     = process.env.BOT_ID     || 'my-poll-bot'
+const STATE_FILE = process.env.STATE_FILE || '/tmp/rosud-call-state.json'
+
+// ── 클라이언트 초기화 ─────────────────────────────────────────────────────────
+const rc = new RosudCall({
+  apiKey: API_KEY,
+  botId:  BOT_ID,
+  // skipSenders: ['other-bot'],  // 이 봇들의 메시지 무시
+})
+
+// ── 메시지 핸들러 ─────────────────────────────────────────────────────────────
+rc.on('message', async (msg) => {
+  /**
+   * msg 구조:
+   *   id, roomId, senderId, content, createdAt
+   */
+  console.log(`[poll] ${msg.senderId}: ${msg.content}`)
+
+  // ── 비즈니스 로직 예시 ────────────────────────────────────────────────────
+  // 특정 발신자의 메시지에만 응답
+  // if (msg.senderId === 'target-bot') {
+  //   await rc.send(msg.roomId, `처리 완료: ${msg.content}`)
+  // }
+})
+
+// ── 폴링 실행 ─────────────────────────────────────────────────────────────────
+;(async () => {
+  try {
+    await rc.poll(ROOM_ID, {
+      stateFile: STATE_FILE,
+      limit: 200,
+    })
+    console.log('[poll] 완료')
+  } catch (err) {
+    console.error('[poll] 에러:', err.message)
+    process.exit(1)
+  }
+})()

package/examples/send.js

@@ -0,0 +1,41 @@
+'use strict'
+/**
+ * examples/send.js — 단건 메시지 발신 예제
+ *
+ * 방에 메시지를 한 번 발신하고 종료하는 가장 간단한 예제입니다.
+ *
+ * 중복 발신 방지:
+ *   60초(dedupTtlMs) 이내에 동일한 내용을 send()하면 자동 스킵됩니다.
+ *   /tmp/rosud-call-dedup.json 파일에 MD5 해시로 저장합니다.
+ *
+ * 사용법:
+ *   API_KEY=your-key ROOM_ID=room-id node examples/send.js
+ *   API_KEY=your-key ROOM_ID=room-id MSG="Hello!" node examples/send.js
+ */
+
+const { RosudCall } = require('../src/index')
+
+// ── 설정 ──────────────────────────────────────────────────────────────────────
+const API_KEY = process.env.API_KEY || 'YOUR_API_KEY'
+const ROOM_ID = process.env.ROOM_ID || 'YOUR_ROOM_ID'
+const BOT_ID  = process.env.BOT_ID  || 'my-sender-bot'
+const MSG     = process.env.MSG     || `Hello from rosud-call! (${new Date().toISOString()})`
+
+// ── 클라이언트 초기화 ─────────────────────────────────────────────────────────
+const rc = new RosudCall({
+  apiKey: API_KEY,
+  botId:  BOT_ID,
+  dedupTtlMs: 60_000,  // 60초 중복 방지 (기본값)
+})
+
+// ── 발신 ──────────────────────────────────────────────────────────────────────
+;(async () => {
+  try {
+    console.log(`[send] 발신 중: "${MSG}"`)
+    await rc.send(ROOM_ID, MSG)
+    console.log('[send] 발신 완료')
+  } catch (err) {
+    console.error('[send] 실패:', err.message)
+    process.exit(1)
+  }
+})()

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "rosud-call",
+  "version": "2.0.1",
+  "description": "Bot messaging SDK — npm install rosud-call",
+  "main": "src/index.js",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node test/run-tests.js",
+    "test:bot-a": "node test/bot-a.js",
+    "test:bot-b": "node test/bot-b.js"
+  },
+  "keywords": [
+    "rosud",
+    "bot",
+    "messaging",
+    "websocket",
+    "ai-agent"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "ws": "^8.0.0"
+  }
+}

package/src/client.js

@@ -0,0 +1,86 @@
+'use strict'
+/**
+ * src/client.js — REST API 클라이언트
+ *
+ * X-API-Key 인증, JSON 요청/응답.
+ */
+
+const https = require('https')
+const http  = require('http')
+
+class ApiClient {
+  /**
+   * @param {object} options
+   * @param {string} options.apiKey
+   * @param {string} options.serverUrl  예: 'https://api.rosud.com/bot-api'
+   */
+  constructor({ apiKey, serverUrl }) {
+    this.apiKey    = apiKey
+    this.serverUrl = serverUrl.replace(/\/$/, '')
+  }
+
+  /**
+   * HTTP 요청 실행.
+   * @param {string} method   'GET' | 'POST' | ...
+   * @param {string} pathname  예: '/api/rooms/xxx/messages?limit=200'
+   * @param {object|null} body JSON body (POST 등)
+   * @returns {Promise<object>}
+   */
+  request(method, pathname, body = null) {
+    return new Promise((resolve, reject) => {
+      const url    = new URL(this.serverUrl + pathname)
+      const isHttps = url.protocol === 'https:'
+      const lib    = isHttps ? https : http
+      const bodyStr = body ? JSON.stringify(body) : null
+
+      const opts = {
+        hostname : url.hostname,
+        port     : url.port || (isHttps ? 443 : 80),
+        path     : url.pathname + url.search,
+        method,
+        headers  : {
+          'X-API-Key'    : this.apiKey,
+          'Content-Type' : 'application/json',
+        },
+      }
+      if (bodyStr) opts.headers['Content-Length'] = Buffer.byteLength(bodyStr)
+
+      const req = lib.request(opts, (res) => {
+        let data = ''
+        res.on('data', (c) => { data += c })
+        res.on('end', () => {
+          try { resolve(JSON.parse(data)) }
+          catch { resolve({ raw: data }) }
+        })
+      })
+
+      req.on('error', reject)
+      if (bodyStr) req.write(bodyStr)
+      req.end()
+    })
+  }
+
+  /** 방 목록 조회 */
+  getRooms() {
+    return this.request('GET', '/api/rooms')
+  }
+
+  /**
+   * 방 생성
+   * @param {{ name: string, roomType?: string, maxTurns?: number, memberIds?: string[] }} opts
+   */
+  createRoom(opts) {
+    return this.request('POST', '/api/rooms', opts)
+  }
+
+  /**
+   * 메시지 목록 조회 (limit=200, after 파라미터 금지)
+   * @param {string} roomId
+   * @param {number} [limit=200]
+   */
+  getMessages(roomId, limit = 200) {
+    return this.request('GET', `/api/rooms/${roomId}/messages?limit=${limit}`)
+  }
+}
+
+module.exports = { ApiClient }

package/src/dedup.js

@@ -0,0 +1,62 @@
+'use strict'
+/**
+ * src/dedup.js — 중복 발신 방지 캐시 (파일 기반, TTL)
+ *
+ * content의 MD5 해시를 키로 사용.
+ * TTL 초과 시 자동 만료.
+ */
+
+const fs     = require('fs')
+const crypto = require('crypto')
+
+const DEFAULT_TTL_MS   = 60_000                      // 60초
+const DEFAULT_CACHE    = '/tmp/rosud-call-dedup.json'
+
+function _hash(content) {
+  return crypto.createHash('md5').update(content).digest('hex')
+}
+
+function _load(cacheFile) {
+  try { return JSON.parse(fs.readFileSync(cacheFile, 'utf8')) }
+  catch { return {} }
+}
+
+function _save(cacheFile, cache) {
+  try { fs.writeFileSync(cacheFile, JSON.stringify(cache)) } catch {}
+}
+
+/**
+ * 동일 content가 TTL 내에 이미 전송됐는지 확인.
+ * @param {string} content
+ * @param {number} [ttlMs]
+ * @param {string} [cacheFile]
+ * @returns {boolean}
+ */
+function isDuplicate(content, ttlMs = DEFAULT_TTL_MS, cacheFile = DEFAULT_CACHE) {
+  const cache = _load(cacheFile)
+  const key   = _hash(content)
+  const ts    = cache[key]
+  return !!(ts && Date.now() - ts < ttlMs)
+}
+
+/**
+ * content를 "전송 완료"로 표시. TTL 초과 항목 동시 정리.
+ * @param {string} content
+ * @param {number} [ttlMs]
+ * @param {string} [cacheFile]
+ */
+function markSent(content, ttlMs = DEFAULT_TTL_MS, cacheFile = DEFAULT_CACHE) {
+  const cache = _load(cacheFile)
+  const key   = _hash(content)
+  cache[key]  = Date.now()
+
+  // TTL 초과 항목 정리
+  const now = Date.now()
+  for (const k of Object.keys(cache)) {
+    if (now - cache[k] > ttlMs) delete cache[k]
+  }
+
+  _save(cacheFile, cache)
+}
+
+module.exports = { isDuplicate, markSent }

package/src/index.js

@@ -0,0 +1,231 @@
+'use strict'
+/**
+ * rosud-call v2 — Bot Messaging SDK
+ *
+ * 오늘(2026-03-15) 겪은 버그 10종을 내부에서 모두 처리.
+ * 사용자는 비즈니스 로직만 작성하면 됨.
+ *
+ * 버그 대응 내역:
+ *  #1  limit=30 → 구 메시지 재전송   → 내부 limit=200 + ID 루프
+ *  #2  after 커서 역방향             → after 파라미터 사용 금지
+ *  #3  좀비 프로세스                 → ping/pong 헬스체크 + 지수 백오프
+ *  #4  LLM 헤더 노출                 → sanitizer 내장
+ *  #6  자기 메시지 루프              → botId 자동 필터
+ *  #8  중복 프로세스                 → 파일 기반 lock
+ *  #9  폴러 자기 메시지 스킵         → poll()도 botId 자동 필터
+ *  #10 ws handle() 자동응답          → on('message') 에서 send() 분리
+ */
+
+const EventEmitter = require('events')
+const WebSocket    = require('ws')
+
+const { ApiClient }    = require('./client')
+const { WsClient }     = require('./ws-client')
+const { Poller }       = require('./poller')
+const { isDuplicate, markSent } = require('./dedup')
+const { sanitize }     = require('./sanitizer')
+
+class RosudCall extends EventEmitter {
+  /**
+   * @param {object} options
+   * @param {string}   options.apiKey
+   * @param {string}   options.botId
+   * @param {string}   [options.serverUrl='https://api.rosud.com/bot-api']
+   * @param {string}   [options.wsUrl='wss://api.rosud.com/bot-ws']
+   * @param {number}   [options.dedupTtlMs=60000]
+   * @param {boolean}  [options.sanitize=true]
+   * @param {string[]} [options.skipSenders=[]]
+   * @param {boolean}  [options.filterSelf=true]  false이면 자기 메시지도 emit
+   */
+  constructor(options = {}) {
+    super()
+    const {
+      apiKey,
+      botId,
+      serverUrl   = 'https://api.rosud.com/bot-api',
+      wsUrl       = 'wss://api.rosud.com/bot-ws',
+      dedupTtlMs  = 60_000,
+      sanitize: doSanitize = true,
+      skipSenders = [],
+      filterSelf  = true,
+    } = options
+
+    if (!apiKey) throw new Error('rosud-call: apiKey 필수')
+    if (!botId)  throw new Error('rosud-call: botId 필수')
+
+    this.apiKey      = apiKey
+    this.botId       = botId
+    this.wsUrl       = wsUrl
+    this.dedupTtlMs  = dedupTtlMs
+    this._doSanitize = doSanitize
+    this.skipSenders = new Set(skipSenders)
+    this.filterSelf  = filterSelf
+
+    this._dedupFile  = '/tmp/rosud-call-dedup.json'
+    this._pollingTimer = null
+
+    // REST 클라이언트
+    this._api = new ApiClient({ apiKey, serverUrl })
+
+    // WS 클라이언트
+    this._ws = new WsClient({
+      apiKey,
+      wsUrl,
+      botId,
+      skipSenders : this.skipSenders,
+      filterSelf  : this.filterSelf,
+      onMessage   : (msg) => this.emit('message', msg),
+      toMsg       : (m)   => this._toMsg(m),
+    })
+
+    // WS 이벤트를 RosudCall 이벤트로 전파
+    this._ws.on('connected',    ()    => this.emit('connected'))
+    this._ws.on('disconnected', (e)   => this.emit('disconnected', e))
+    this._ws.on('reconnecting', (sec) => this.emit('reconnecting', sec))
+    this._ws.on('error',        (e)   => this.emit('error', e))
+
+    // Poller
+    this._poller = new Poller({
+      client      : this._api,
+      botId,
+      skipSenders : this.skipSenders,
+      filterSelf  : this.filterSelf,
+      onMessage   : (msg) => this.emit('message', msg),
+      toMsg       : (m)   => this._toMsg(m),
+    })
+  }
+
+  // ────────────────────────────────────────────────
+  // WS 리스너 모드 (장기 데몬용)
+  // ────────────────────────────────────────────────
+
+  /** WS 연결 + 자동 재연결 시작 */
+  async connect(roomId) {
+    return this._ws.connect(roomId)
+  }
+
+  /** WS 연결 종료 */
+  async disconnect() {
+    this.stopPolling()
+    return this._ws.disconnect()
+  }
+
+  // ────────────────────────────────────────────────
+  // REST 폴링 모드 (단기 실행 스크립트용)
+  // ────────────────────────────────────────────────
+
+  /** 1회 REST 폴링 실행 */
+  async poll(roomId, options = {}) {
+    return this._poller.poll(roomId, options)
+  }
+
+  /**
+   * 주기적 폴링 시작.
+   * @param {string} roomId
+   * @param {object} [options]
+   * @param {number} [options.intervalMs=5000]
+   * @param {string} [options.stateFile]
+   */
+  startPolling(roomId, options = {}) {
+    const { intervalMs = 5_000, stateFile } = options
+    if (this._pollingTimer) return
+
+    const tick = async () => {
+      try { await this._poller.poll(roomId, { stateFile }) }
+      catch (e) { this.emit('error', e) }
+      if (this._pollingTimer !== null) {
+        this._pollingTimer = setTimeout(tick, intervalMs)
+      }
+    }
+
+    this._pollingTimer = setTimeout(tick, 0)
+  }
+
+  /** 주기적 폴링 중지 */
+  stopPolling() {
+    if (this._pollingTimer) {
+      clearTimeout(this._pollingTimer)
+      this._pollingTimer = null
+    }
+  }
+
+  // ────────────────────────────────────────────────
+  // 메시지 발신
+  // ────────────────────────────────────────────────
+
+  /**
+   * 메시지 발신.
+   * - 활성 WS 연결이 있으면 그걸로 발신
+   * - 없으면 일회성 WS 연결 사용
+   * - 60초 내 동일 content 재발신 방지
+   */
+  async send(roomId, content) {
+    if (isDuplicate(content, this.dedupTtlMs, this._dedupFile)) {
+      this.emit('debug', `dedup skip: ${content.slice(0, 40)}`)
+      return null
+    }
+
+    // 활성 WS 연결 사용
+    if (this._ws.isOpen()) {
+      await this._ws.sendMessage(roomId, content)
+      markSent(content, this.dedupTtlMs, this._dedupFile)
+      return { ok: true }
+    }
+
+    // 일회성 WS 연결로 발신
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(this.wsUrl, {
+        headers: { Authorization: `Bearer ${this.apiKey}` },
+      })
+      ws.on('open', () => {
+        ws.send(JSON.stringify({ type: 'subscribe', room_id: roomId }))
+      })
+      ws.on('message', (raw) => {
+        const msg = JSON.parse(raw)
+        if (msg.type === 'subscribed') {
+          ws.send(JSON.stringify({ type: 'send_message', room_id: roomId, content }))
+        } else if (msg.type === 'message_new' && msg.message?.content === content) {
+          markSent(content, this.dedupTtlMs, this._dedupFile)
+          ws.close()
+          resolve({ ok: true, id: msg.message.id })
+        }
+      })
+      ws.on('error', reject)
+      setTimeout(() => { ws.close(); resolve({ ok: true }) }, 5000)
+    })
+  }
+
+  // ────────────────────────────────────────────────
+  // REST API
+  // ────────────────────────────────────────────────
+
+  /** 방 목록 조회 */
+  getRooms() {
+    return this._api.getRooms()
+  }
+
+  /**
+   * 방 생성
+   * @param {{ name: string, roomType?: string, maxTurns?: number, memberIds?: string[] }} opts
+   */
+  createRoom(opts) {
+    return this._api.createRoom(opts)
+  }
+
+  // ────────────────────────────────────────────────
+  // 내부 유틸
+  // ────────────────────────────────────────────────
+
+  _toMsg(m) {
+    const content = this._doSanitize ? sanitize(m.content || '') : (m.content || '')
+    return {
+      id        : m.id,
+      roomId    : m.room_id,
+      senderId  : m.sender_id,
+      content,
+      createdAt : m.created_at,
+    }
+  }
+}
+
+module.exports = { RosudCall }

package/src/lock.js

@@ -0,0 +1,61 @@
+'use strict'
+/**
+ * src/lock.js — 파일 기반 프로세스 Lock
+ *
+ * flock() 스타일의 파일 lock.
+ * - stale lock 자동 해제: 600초(10분) 초과 시 강제 해제
+ * - lock 파일에 PID + timestamp 기록
+ */
+
+const fs   = require('fs')
+const path = require('path')
+
+const STALE_TIMEOUT_MS = 600_000  // 10분
+
+/**
+ * lock 획득 시도.
+ * @param {string} lockFile  lock 파일 경로
+ * @returns {{ fd: number, path: string } | null}  성공 시 lock 핸들, 실패 시 null
+ */
+function acquireLock(lockFile) {
+  // stale lock 확인
+  if (fs.existsSync(lockFile)) {
+    try {
+      const raw   = fs.readFileSync(lockFile, 'utf8')
+      const info  = JSON.parse(raw)
+      const age   = Date.now() - (info.ts || 0)
+
+      if (age < STALE_TIMEOUT_MS) {
+        // 유효한 lock — 획득 실패
+        return null
+      }
+      // stale → 강제 삭제
+      fs.unlinkSync(lockFile)
+    } catch {
+      // 읽기/파싱 실패 → stale로 간주, 덮어쓰기
+    }
+  }
+
+  // lock 파일 생성 (exclusive write — 경쟁 조건 최소화)
+  try {
+    const fd = fs.openSync(lockFile, 'wx')  // O_CREAT | O_EXCL
+    const info = JSON.stringify({ pid: process.pid, ts: Date.now() })
+    fs.writeSync(fd, info)
+    return { fd, path: lockFile }
+  } catch (e) {
+    if (e.code === 'EEXIST') return null  // 다른 프로세스가 먼저 획득
+    throw e
+  }
+}
+
+/**
+ * lock 해제.
+ * @param {{ fd: number, path: string }} lockHandle  acquireLock() 반환값
+ */
+function releaseLock(lockHandle) {
+  if (!lockHandle) return
+  try { fs.closeSync(lockHandle.fd) } catch {}
+  try { fs.unlinkSync(lockHandle.path) } catch {}
+}
+
+module.exports = { acquireLock, releaseLock }

package/src/poller.js

@@ -0,0 +1,100 @@
+'use strict'
+/**
+ * src/poller.js — REST 폴링 로직
+ *
+ * 버그 대응:
+ *  #1  limit=30 → 구 메시지 재전송   → 내부 limit=200 + ID 루프
+ *  #2  after 커서 역방향             → after 파라미터 절대 사용 금지
+ *
+ * 동작:
+ *  - limit=200 고정으로 최신 메시지 목록 조회
+ *  - last_id 이후 메시지만 콜백 호출
+ *  - last_id 없으면 최신 ID 저장 후 종료 (초기화 전용)
+ *  - last_id가 조회 범위 초과 시 재전송 없이 최신 ID 갱신
+ */
+
+const fs = require('fs')
+
+const LIMIT = 200
+
+class Poller {
+  /**
+   * @param {object} options
+   * @param {import('./client').ApiClient} options.client
+   * @param {string}   options.botId
+   * @param {Set<string>} options.skipSenders
+   * @param {boolean}  [options.filterSelf=true]  true면 botId 발신 메시지 필터
+   * @param {Function} options.onMessage  (msg) => void
+   * @param {Function} [options.toMsg]    내부 메시지 변환 함수
+   */
+  constructor({ client, botId, skipSenders, filterSelf = true, onMessage, toMsg }) {
+    this.client      = client
+    this.botId       = botId
+    this.skipSenders = skipSenders
+    this.filterSelf  = filterSelf
+    this.onMessage   = onMessage
+    this.toMsg       = toMsg || ((m) => m)
+  }
+
+  /**
+   * 1회 폴링 실행.
+   * @param {string} roomId
+   * @param {object} [options]
+   * @param {string} [options.stateFile='/tmp/rosud-call-state.json']
+   */
+  async poll(roomId, options = {}) {
+    const stateFile = options.stateFile || '/tmp/rosud-call-state.json'
+
+    const lastId = this._loadState(stateFile, roomId)
+    const data   = await this.client.getMessages(roomId, LIMIT)
+    const messages = data.messages || []
+
+    if (!messages.length) return
+
+    if (!lastId) {
+      // 최초 실행: 현재 최신 저장 후 종료 (과거 메시지 재전송 방지)
+      this._saveState(stateFile, roomId, messages[messages.length - 1].id)
+      return
+    }
+
+    // last_id 이후 메시지 수집 (index 0 = oldest)
+    let found   = false
+    const newMsgs = []
+    for (const m of messages) {
+      if (found) newMsgs.push(m)
+      if (m.id === lastId) found = true
+    }
+
+    if (!found) {
+      // last_id가 조회 범위 밖 → 재전송 금지, 최신 ID만 갱신
+      this._saveState(stateFile, roomId, messages[messages.length - 1].id)
+      return
+    }
+
+    if (!newMsgs.length) return
+
+    this._saveState(stateFile, roomId, newMsgs[newMsgs.length - 1].id)
+
+    for (const m of newMsgs) {
+      if (this.filterSelf && m.sender_id === this.botId) continue
+      if (this.skipSenders.has(m.sender_id))  continue
+      this.onMessage(this.toMsg(m))
+    }
+  }
+
+  // ── state 파일 ────────────────────────────────────
+
+  _loadState(stateFile, roomId) {
+    try { return JSON.parse(fs.readFileSync(stateFile, 'utf8'))[roomId] || '' }
+    catch { return '' }
+  }
+
+  _saveState(stateFile, roomId, msgId) {
+    let data = {}
+    try { data = JSON.parse(fs.readFileSync(stateFile, 'utf8')) } catch {}
+    data[roomId] = msgId
+    try { fs.writeFileSync(stateFile, JSON.stringify(data)) } catch {}
+  }
+}
+
+module.exports = { Poller }

package/src/router.js

@@ -0,0 +1,116 @@
+'use strict'
+/**
+ * src/router.js — 메신저 라우팅 규칙 엔진
+ *
+ * 4가지 context에 따라 메시지 라우팅 동작을 결정.
+ *
+ * context:
+ *   'dm'            — 1:1 DM. humanId의 메시지만 처리, messengerChatId로 포워딩
+ *   'group'         — 그룹방. keywords 매칭 시 messengerChatId로 포워딩
+ *   'autonomous'    — 완전 자율 봇. 모든 메시지 처리, 라우팅 없음
+ *   'cross-platform'— 플랫폼 간 브릿지. messengerFn으로 모든 메시지 중계
+ *
+ * 사용 예:
+ *   const router = new MessageRouter({
+ *     context: 'group',
+ *     messengerChatId: '-5208187269',
+ *     humanId: '8171314672',
+ *     messengerFn: async (chatId, text) => { ... },
+ *     keywords: ['완료', '에러', 'done', 'error', 'failed'],
+ *   })
+ *   rc.on('message', (msg) => router.route(msg))
+ */
+
+class MessageRouter {
+  /**
+   * @param {object} options
+   * @param {'dm'|'group'|'autonomous'|'cross-platform'} options.context
+   * @param {string}   [options.messengerChatId]  포워딩 대상 채팅 ID
+   * @param {string}   [options.humanId]          DM 모드: 허용할 발신자 ID
+   * @param {Function} [options.messengerFn]      (chatId, text) => Promise<void>
+   * @param {string[]} [options.keywords]         group 모드: 포워딩 트리거 키워드
+   * @param {Function} [options.onMessage]        라우팅 후 핸들러 (msg) => void
+   */
+  constructor(options = {}) {
+    const {
+      context        = 'autonomous',
+      messengerChatId,
+      humanId,
+      messengerFn,
+      keywords       = [],
+      onMessage,
+    } = options
+
+    this.context         = context
+    this.messengerChatId = messengerChatId
+    this.humanId         = humanId
+    this.messengerFn     = messengerFn
+    this.keywords        = keywords.map((k) => k.toLowerCase())
+    this.onMessage       = onMessage
+
+    if (context !== 'autonomous' && !messengerFn && context !== 'group') {
+      // group은 keywords만 체크, messengerFn 없어도 onMessage 호출 가능
+    }
+  }
+
+  /**
+   * 메시지를 context 규칙에 따라 라우팅.
+   * @param {{ id, roomId, senderId, content, createdAt }} msg
+   * @returns {Promise<void>}
+   */
+  async route(msg) {
+    switch (this.context) {
+      case 'dm':
+        return this._routeDm(msg)
+      case 'group':
+        return this._routeGroup(msg)
+      case 'cross-platform':
+        return this._routeCrossPlatform(msg)
+      case 'autonomous':
+      default:
+        return this._routeAutonomous(msg)
+    }
+  }
+
+  // ── context 처리 ─────────────────────────────────
+
+  /** DM: humanId 발신자 메시지만 → messengerFn 또는 onMessage */
+  async _routeDm(msg) {
+    if (this.humanId && msg.senderId !== this.humanId) return
+    await this._forward(msg)
+  }
+
+  /** Group: keywords 매칭 시 → messengerFn 또는 onMessage */
+  async _routeGroup(msg) {
+    if (this.keywords.length > 0) {
+      const lower = msg.content.toLowerCase()
+      const matched = this.keywords.some((k) => lower.includes(k))
+      if (!matched) return
+    }
+    await this._forward(msg)
+  }
+
+  /** Cross-platform: 모든 메시지 → messengerFn */
+  async _routeCrossPlatform(msg) {
+    await this._forward(msg)
+  }
+
+  /** Autonomous: 모든 메시지 → onMessage만 (외부 메신저 없음) */
+  async _routeAutonomous(msg) {
+    if (this.onMessage) this.onMessage(msg)
+  }
+
+  /** messengerFn 호출 + onMessage 호출 */
+  async _forward(msg) {
+    if (this.messengerFn && this.messengerChatId) {
+      try {
+        await this.messengerFn(this.messengerChatId, msg.content)
+      } catch (e) {
+        // 포워딩 실패는 onMessage 차단 안 함
+      }
+    }
+    if (this.onMessage) this.onMessage(msg)
+  }
+}
+
+module.exports = { MessageRouter }

package/src/sanitizer.js

@@ -0,0 +1,41 @@
+'use strict'
+/**
+ * src/sanitizer.js — LLM 헤더 제거
+ *
+ * LLM 초안 헤더 패턴을 감지해 실제 content만 추출.
+ * "Human:", "Assistant:", "System:", "---\n초안" 등 제거.
+ */
+
+// "---" 이전에 이 키워드가 있으면 헤더로 판단
+const DRAFT_KEYWORDS = ['초안', 'draft', 'Draft', '브릿지 방 답장']
+
+// 줄 단위 LLM 역할 접두사 패턴
+const ROLE_PREFIX_RE = /^(Human|Assistant|System|User|AI)\s*:\s*/i
+
+/**
+ * LLM 헤더를 제거하고 실제 content만 반환.
+ * @param {string} content
+ * @returns {string}
+ */
+function sanitize(content) {
+  if (!content) return content
+
+  // "---" 구분선이 있으면 초안 헤더 여부 확인
+  const sepIdx = content.indexOf('---')
+  if (sepIdx !== -1) {
+    const before = content.slice(0, sepIdx)
+    if (DRAFT_KEYWORDS.some((k) => before.includes(k))) {
+      return content.slice(sepIdx + 3).trim()
+    }
+  }
+
+  // 줄 단위 LLM 역할 접두사 제거 (단일 줄 메시지)
+  const trimmed = content.trimStart()
+  if (ROLE_PREFIX_RE.test(trimmed)) {
+    return trimmed.replace(ROLE_PREFIX_RE, '').trim()
+  }
+
+  return content
+}
+
+module.exports = { sanitize }

package/src/ws-client.js

@@ -0,0 +1,165 @@
+'use strict'
+/**
+ * src/ws-client.js — WebSocket 클라이언트
+ *
+ * 버그 대응:
+ *  #3  좀비 프로세스 → ping/pong 헬스체크 (30초) + 지수 백오프 재연결
+ *  #6  자기 메시지 루프 → botId 자동 필터
+ *
+ * 기능:
+ *  - connect(roomId) — WS 연결 + subscribe ACK 대기
+ *  - disconnect() — 정상 종료
+ *  - send(roomId, content) — 메시지 발신
+ *  - 지수 백오프 재연결: 1→2→4→8→...→60초
+ *  - ping/pong 헬스체크: 30초마다 ping, 무응답 시 재연결
+ */
+
+const WebSocket = require('ws')
+const EventEmitter = require('events')
+
+const PING_INTERVAL_MS = 30_000   // 30초
+const MIN_RETRY_SEC    = 1
+const MAX_RETRY_SEC    = 60
+
+class WsClient extends EventEmitter {
+  /**
+   * @param {object} options
+   * @param {string}   options.apiKey
+   * @param {string}   options.wsUrl
+   * @param {string}   options.botId
+   * @param {Set<string>} options.skipSenders
+   * @param {boolean}  [options.filterSelf=true]  true면 botId 발신 메시지 필터
+   * @param {Function} options.onMessage    (rawMsg) => void
+   * @param {Function} options.toMsg        (m) => msg
+   */
+  constructor({ apiKey, wsUrl, botId, skipSenders, filterSelf = true, onMessage, toMsg }) {
+    super()
+    this.apiKey      = apiKey
+    this.wsUrl       = wsUrl
+    this.botId       = botId
+    this.skipSenders = skipSenders
+    this.filterSelf  = filterSelf
+    this.onMessage   = onMessage
+    this.toMsg       = toMsg || ((m) => m)
+
+    this._ws         = null
+    this._room       = null
+    this._stopped    = false
+    this._retryDelay = MIN_RETRY_SEC
+    this._pingTimer  = null
+  }
+
+  /** WS 연결 + subscribe */
+  async connect(roomId) {
+    this._room    = roomId
+    this._stopped = false
+    await this._wsConnect()
+  }
+
+  /** WS 종료 */
+  async disconnect() {
+    this._stopped = true
+    this._clearPing()
+    if (this._ws) {
+      this._ws.terminate()
+      this._ws = null
+    }
+  }
+
+  /**
+   * WS로 메시지 발신 (연결 필요).
+   * @param {string} roomId
+   * @param {string} content
+   * @returns {Promise<{ ok: boolean }>}
+   */
+  sendMessage(roomId, content) {
+    return new Promise((resolve, reject) => {
+      if (!this._ws || this._ws.readyState !== WebSocket.OPEN) {
+        return reject(new Error('WS not connected'))
+      }
+      const payload = JSON.stringify({ type: 'send_message', room_id: roomId, content })
+      this._ws.send(payload, (err) => {
+        if (err) return reject(err)
+        resolve({ ok: true })
+      })
+    })
+  }
+
+  /** 현재 WS가 열려있는지 확인 */
+  isOpen() {
+    return !!(this._ws && this._ws.readyState === WebSocket.OPEN)
+  }
+
+  // ── 내부 ────────────────────────────────────────
+
+  async _wsConnect() {
+    if (this._stopped) return
+
+    const ws = new WebSocket(this.wsUrl, {
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+    })
+    this._ws = ws
+
+    ws.on('open', () => {
+      ws.send(JSON.stringify({ type: 'subscribe', room_id: this._room }))
+      this._resetPing()
+    })
+
+    ws.on('message', (raw) => {
+      this._resetPing()
+      let msg
+      try { msg = JSON.parse(raw) } catch { return }
+
+      if (msg.type === 'subscribed') {
+        this._retryDelay = MIN_RETRY_SEC
+        this.emit('connected')
+        return
+      }
+
+      if (msg.type === 'message_new') {
+        const m = msg.message
+        if (this.filterSelf && m.sender_id === this.botId) return
+        if (this.skipSenders.has(m.sender_id))  return
+        this.onMessage(this.toMsg(m))
+      }
+    })
+
+    ws.on('pong', () => this._resetPing())
+
+    ws.on('close', (code, reason) => {
+      this._clearPing()
+      this.emit('disconnected', { code, reason: reason?.toString() })
+      if (!this._stopped) this._scheduleReconnect()
+    })
+
+    ws.on('error', (err) => {
+      this.emit('error', err)
+    })
+  }
+
+  _scheduleReconnect() {
+    if (this._stopped) return
+    const delay = this._retryDelay
+    this._retryDelay = Math.min(delay * 2, MAX_RETRY_SEC)
+    this.emit('reconnecting', delay)
+    setTimeout(() => this._wsConnect(), delay * 1000)
+  }
+
+  _resetPing() {
+    this._clearPing()
+    this._pingTimer = setTimeout(() => {
+      if (this._ws && this._ws.readyState === WebSocket.OPEN) {
+        this._ws.ping()
+      }
+    }, PING_INTERVAL_MS)
+  }
+
+  _clearPing() {
+    if (this._pingTimer) {
+      clearTimeout(this._pingTimer)
+      this._pingTimer = null
+    }
+  }
+}
+
+module.exports = { WsClient }