claude-telegram-bot 0.3.14 → 0.3.17

package/README.ko.md

@@ -6,6 +6,8 @@
 [![npm downloads](https://img.shields.io/npm/dm/claude-telegram-bot.svg)](https://www.npmjs.com/package/claude-telegram-bot)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+텔레그램으로 Claude Code를 — 어디서든, 어떤 기기에서도.
+
 텔레그램으로 메시지를 보내면, 집이나 서버에 켜둔 Claude Code가 작업하고 결과를 다시 텔레그램으로 돌려주는 봇입니다.
 
 ```
@@ -116,7 +118,7 @@ claude-telegram-bot ~/botconfigs/myproj/mybot.json
    - `테스트 돌려보고 통과하면 커밋하고 push 해줘`
    - `api.ts 에 에러 핸들링 추가해줘`
 
-명령어: `/new`(맥락 초기화) · `/stop`(작업 중단; `--reset`으로 세션도 롤백) · `/cron`(예약 작업 보기·추가·삭제) · `/restart`(문법 검사 후 재시작) · `/status`(봇 상태·버전) · `/model`(모델 보기·전환) · `/id`(채팅 ID 확인) · `/help`(도움말)
+명령어: `/new`(맥락 초기화) · `/stop`(작업 중단; `--reset`으로 세션도 롤백) · `/cron`(예약 작업 보기·추가·삭제) · `/reserve`(한도 리셋 시 재시도 예약) · `/restart`(문법 검사 후 재시작) · `/status`(봇 상태·버전) · `/model`(모델 보기·전환) · `/id`(채팅 ID 확인) · `/help`(도움말)
 
 > **`/stop`** 은 실행 중인 Claude 프로세스를 즉시 종료하고 대기 중인 메시지 큐도 비웁니다. `--reset`을 붙이면 세션을 작업 시작 이전 상태로 되돌려 중단된 작업이 대화 맥락에 남지 않습니다.
 
@@ -127,6 +129,7 @@ claude-telegram-bot ~/botconfigs/myproj/mybot.json
 - **세션 유지** — 대화는 `--resume`으로 자동으로 이어집니다. 마지막 세션 ID가 `state.json`에 저장되므로 봇을 재시작해도 맥락이 남습니다. 새로 시작하려면 `/new`.
 - **메시지 큐** — 작업 중에 새 메시지가 오면 버리지 않고 큐에 쌓아둡니다. 작업이 끝나면 대기 중인 메시지를 모두 하나의 프롬프트로 합쳐서 처리합니다(예: "A 해줘" → "아니다 B 해줘"를 한 번에 처리). `/stop`으로 실행 중인 작업과 큐를 동시에 취소할 수 있습니다.
 - **모델 권유** — 봇이 Claude에게 현재 모델을 알려줍니다. 질문 난이도가 현재 모델 수준을 넘는다고 판단되면 답변 끝에 전환 권유 한 줄이 붙습니다(예: 💡 `/model sonnet`). `/model <이름>`으로 전환(`haiku`, `sonnet`, `opus`, `fable`, 또는 전체 모델 ID) — `state.json`에 저장돼 재시작 후에도 유지됩니다.
+- **한도 초과 재시도** — Claude Max / API 레이트 리밋 에러에 리셋 시간이 포함되면 `/reserve` 힌트를 표시합니다. `/reserve`를 입력하면 마지막 메시지를 해당 시각에 자동 재전송 예약. `/reserve <다른 메시지>`로 내용 변경, `/reserve rm`으로 취소.
 - **간결한 답변** — 텔레그램에 맞게 짧게 답하도록 시스템 프롬프트가 기본으로 붙습니다. 바꾸려면 `appendSystemPrompt`에 직접 넣으세요 (빈 문자열이면 끔).
 - **언어** — 봇 자체 문구(`/help`, 명령 메뉴, 상태 메시지)는 **기본 영어**, 텔레그램이 한국어인 사용자에겐 한국어로 나옵니다. `lang`(`"en"`/`"ko"`)으로 고정할 수 있습니다. Claude의 실제 답변은 **사용자가 쓴 언어**를 따라갑니다. `/` 명령 메뉴는 `setMyCommands`로 언어별 등록됩니다.
 - **서식 변환** — 답변의 마크다운(굵게·코드·표 등)을 텔레그램 HTML로 바꿔 보냅니다. 변환이 깨지는 경우엔 평문으로 다시 보냅니다.

package/README.md

@@ -6,6 +6,8 @@
 [![npm downloads](https://img.shields.io/npm/dm/claude-telegram-bot.svg)](https://www.npmjs.com/package/claude-telegram-bot)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+Use Claude Code from Telegram — run it anywhere, from any device.
+
 **A zero-dependency, single-file, daemonized Claude Code bot — no Bun, no Python, no open session.**
 
 A tiny bridge that takes your Telegram messages, runs `claude -p` (Claude Code headless mode)
@@ -160,7 +162,7 @@ auth layer.)
 - `run the solver tests and commit + push if they pass`
 - `add an edge case to solve-2nd-floor-edges.ts`
 
-Commands: `/new` (reset context / new session) · `/stop` (stop current task; `--reset` to also roll back the session) · `/cron` (list / add / remove scheduled tasks) · `/restart` (syntax-check & restart the bot) · `/status` (bot status & version) · `/model` (view / switch the model) · `/id` (show chat ID) · `/help`.
+Commands: `/new` (reset context / new session) · `/stop` (stop current task; `--reset` to also roll back the session) · `/cron` (list / add / remove scheduled tasks) · `/reserve` (schedule retry at usage-limit reset) · `/restart` (syntax-check & restart the bot) · `/status` (bot status & version) · `/model` (view / switch the model) · `/id` (show chat ID) · `/help`.
 
 > **`/stop`** kills the running Claude process immediately and clears any queued messages.
 > Add `--reset` to also restore the session to the state it was in *before* the task started,
@@ -223,6 +225,7 @@ your launchd plist points them.
   `state.json`, so context survives restarts. Use `/new` to start fresh.
 - **Message queue**: if you send a message while a task is running, it is queued (not dropped). When the task finishes, all queued messages are merged into a single prompt so Claude can resolve corrections and follow-ups in one pass (e.g. "do X" then "never mind, do Y" → handled together). Use `/stop` to cancel the running task and discard the queue.
 - **Model hint**: the bot tells Claude which model it is running as. If Claude judges a question to be beyond its current tier, it appends a one-line suggestion at the end of the reply (e.g. 💡 `/model sonnet`). Switch with `/model <name>` — `haiku`, `sonnet`, `opus`, `fable`, or a full model id. The choice persists in `state.json` across restarts.
+- **Usage-limit retry**: when a Claude Max / API rate-limit error includes a reset time, the bot shows a `/reserve` hint. `/reserve` schedules your last message to be resent automatically at that time. Use `/reserve <different text>` to change what's sent, or `/reserve rm` to cancel.
 
 ### Scheduled tasks (cron)
 

package/bot.mjs

@@ -114,6 +114,11 @@ if (!existsSync(CONFIG_PATH)) {
 const cfg = JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
 console.log({ ...cfg, token: cfg.token ? "<redacted>" : "(none)" });
 const TG = `https://api.telegram.org/bot${cfg.token}`;
+// allowedChatId 는 문자열 또는 배열 모두 허용 (하위 호환)
+const allowedIds = []
+  .concat(cfg.allowedChatId)
+  .filter(Boolean)
+  .map(String);
 
 // ── i18n (영어 기본 + 한국어) ─────────────────────────────────────────────
 // cfg.lang 를 "en"/"ko" 로 주면 그 언어로 고정. 비우면 메시지의 from.language_code 로
@@ -133,6 +138,7 @@ const STR = {
       "• /cron — list tasks · /cron add <natural language> to add · /cron rm <id> to remove\n" +
       "• /remember <text> — save to persistent memory (survives /new)\n" +
       "• /memory — view memory · /memory clear to wipe\n" +
+      "• /reserve — retry at usage-limit reset time · /reserve <msg> for a different message · /reserve rm to cancel\n" +
       "• /restart — restart the bot (after a syntax check)\n" +
       "• /status — bot status & version\n" +
       "• /model — view / switch the model\n" +
@@ -192,6 +198,11 @@ const STR = {
     remembered: "💾 Saved to memory.",
     rememberUsage: "Usage: /remember <text to remember>",
     memoryUsage: "Usage: /memory · /memory clear",
+    reserveHint: "\n\nTo retry when the limit resets, send `/reserve` (or `/reserve <different message>`).",
+    reserveOk: (time) => `⏰ Retry scheduled for ${time}. Cancel with /reserve rm.`,
+    reserveRm: "🚫 Scheduled retry canceled.",
+    reserveNone: "No retry is scheduled.",
+    reserveNoLimit: "No recent usage limit error. Send a message first.",
   },
   ko: {
     help: () =>
@@ -202,6 +213,7 @@ const STR = {
       "• /cron — 예약 작업 보기 · /cron add <자연어>로 추가 · /cron rm <번호>로 삭제\n" +
       "• /remember <내용> — 퍼시스턴트 메모리에 저장 (/new 로 초기화해도 유지)\n" +
       "• /memory — 메모리 보기 · /memory clear 로 삭제\n" +
+      "• /reserve — 한도 리셋 시 재시도 예약 · /reserve <다른 메시지> 로 내용 변경 · /reserve rm 으로 취소\n" +
       "• /restart — 봇 재시작 (문법 검사 후 안전하게)\n" +
       "• /status — 봇 상태·버전 보기\n" +
       "• /model — 모델 보기·전환\n" +
@@ -260,6 +272,11 @@ const STR = {
     remembered: "💾 메모리에 저장했습니다.",
     rememberUsage: "사용법: /remember <기억할 내용>",
     memoryUsage: "사용법: /memory · /memory clear",
+    reserveHint: "\n\n리셋 후 재시도하려면 `/reserve` (또는 `/reserve <다른 메시지>`)를 입력하세요.",
+    reserveOk: (time) => `⏰ ${time}에 재시도 예약됨. 취소: /reserve rm`,
+    reserveRm: "🚫 예약된 재시도를 취소했습니다.",
+    reserveNone: "예약된 재시도가 없습니다.",
+    reserveNoLimit: "최근 한도 초과 에러가 없습니다. 먼저 메시지를 보내주세요.",
   },
 };
 const t = (l, key, ...a) => {
@@ -281,6 +298,7 @@ const COMMANDS = {
     { command: "restart", description: "Restart the bot (after syntax check)" },
     { command: "status", description: "Bot status / version" },
     { command: "model", description: "View / switch the model" },
+    { command: "reserve", description: "Schedule retry when usage limit resets · /reserve rm to cancel" },
     { command: "id", description: "Show this chat ID" },
     { command: "help", description: "Help" },
   ],
@@ -293,6 +311,7 @@ const COMMANDS = {
     { command: "restart", description: "봇 재시작 (문법 검사 후)" },
     { command: "status", description: "봇 상태·버전 보기" },
     { command: "model", description: "모델 보기·전환" },
+    { command: "reserve", description: "한도 리셋 시 재시도 예약 · /reserve rm 으로 취소" },
     { command: "id", description: "이 채팅 ID 확인" },
     { command: "help", description: "도움말" },
   ],
@@ -340,7 +359,7 @@ function isNewer(latest, current) {
 }
 
 async function checkForUpdate() {
-  if (!cfg.allowedChatId) return;
+  if (!allowedIds.length) return;
   const now = Date.now();
   if (state.lastVersionCheck && now - state.lastVersionCheck < VERSION_CHECK_INTERVAL) return;
   const latest = await fetchLatestVersion();
@@ -350,9 +369,10 @@ async function checkForUpdate() {
   if (state.notifiedVersion === latest) return; // 이미 알린 버전
   state.notifiedVersion = latest;
   saveState(state);
-  await send(cfg.allowedChatId,
-    `✨ 업데이트가 있습니다: ${VERSION} → ${latest}\n\`npm i -g claude-telegram-bot\` 후 /restart`
-  ).catch(() => {});
+  for (const id of allowedIds)
+    await send(id,
+      `✨ 업데이트가 있습니다: ${VERSION} → ${latest}\n\`npm i -g claude-telegram-bot\` 후 /restart`
+    ).catch(() => {});
 }
 
 // ── 퍼시스턴트 메모리 ─────────────────────────────────────────────────────
@@ -482,11 +502,34 @@ async function send(chatId, text) {
 }
 
 // ── Claude 에러 분류 ──────────────────────────────────────────────────────
+function parseResetTime(raw) {
+  // ISO timestamp: 2026-06-17T14:00:00Z
+  const iso = raw.match(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z?/);
+  if (iso) { const d = new Date(iso[0]); if (!isNaN(d)) return d; }
+  // "in X minutes" / "in X hours"
+  const inMin = raw.match(/in (\d+)\s*minute/i);
+  if (inMin) return new Date(Date.now() + parseInt(inMin[1]) * 60000);
+  const inHour = raw.match(/in (\d+)\s*hour/i);
+  if (inHour) return new Date(Date.now() + parseInt(inHour[1]) * 3600000);
+  // "resets at HH:MM" or "available at HH:MM"
+  const atTime = raw.match(/(?:resets?|reset|available|retry)\s+at\s+(\d{1,2}):(\d{2})(?:\s*(AM|PM))?/i);
+  if (atTime) {
+    let h = parseInt(atTime[1]);
+    const m = parseInt(atTime[2]);
+    if (atTime[3]) { if (/pm/i.test(atTime[3]) && h < 12) h += 12; if (/am/i.test(atTime[3]) && h === 12) h = 0; }
+    const d = new Date(); d.setHours(h, m, 0, 0);
+    if (d <= new Date()) d.setDate(d.getDate() + 1);
+    return d;
+  }
+  return null;
+}
+
 function classifyClaudeError(raw, code) {
   const t = raw.toLowerCase();
   if (t.includes("credit") || t.includes("balance") || t.includes("billing") || t.includes("payment"))
     return "💳 API 크레딧이 부족합니다. console.anthropic.com 에서 충전해주세요.";
-  if (t.includes("rate_limit") || t.includes("rate limit") || t.includes("too many requests") || code === 429)
+  if (t.includes("rate_limit") || t.includes("rate limit") || t.includes("too many requests") || code === 429
+      || t.includes("usage limit") || t.includes("monthly limit"))
     return "⏱️ 요청이 너무 많습니다. 잠시 후 다시 시도해주세요.";
   if (t.includes("overloaded") || code === 529)
     return "🔄 Claude 서버가 일시적으로 과부하 상태입니다. 잠시 후 다시 시도해주세요.";
@@ -516,9 +559,9 @@ function runClaude(prompt, sessionId, opts = {}) {
       : null;
     // opts.injectMemory: 퍼시스턴트 메모리를 시스템 프롬프트에 주입 (/new 로 초기화해도 유지)
     const mem = opts.injectMemory ? loadMemory() : "";
-    const memoryBlock = mem ? `## Persistent memory (survives /new)\n${mem}` : null;
-    // 페르소나(cfg.persona) + 간결 지침 + 모델 힌트 + 메모리를 함께 주입
-    const appendSys = [cfg.persona, brevity, modelHint, memoryBlock].filter(Boolean).join("\n\n");
+    // 메모리는 persona보다 앞에 배치하고 헤더를 강화 → persona가 덮어쓰는 것 방지
+    const memoryBlock = mem ? `## RULES (must follow before anything else)\n${mem}` : null;
+    const appendSys = [memoryBlock, cfg.persona, brevity, modelHint].filter(Boolean).join("\n\n");
     if (appendSys) args.push("--append-system-prompt", appendSys);
     if (model) args.push("--model", model);
     if (sessionId) args.push("--resume", sessionId);
@@ -545,13 +588,13 @@ function runClaude(prompt, sessionId, opts = {}) {
       currentChild = null;
       try {
         const j = JSON.parse(out);
-        const text = j.is_error
-          ? classifyClaudeError(j.result ?? "", code)
-          : (j.result ?? "(empty response)");
-        resolve({ ok: !j.is_error, text, sessionId: j.session_id, cost: j.total_cost_usd });
+        const rawErr = j.result ?? "";
+        const text = j.is_error ? classifyClaudeError(rawErr, code) : (rawErr || "(empty response)");
+        const resetAt = j.is_error ? parseResetTime(rawErr) : null;
+        resolve({ ok: !j.is_error, text, sessionId: j.session_id, cost: j.total_cost_usd, resetAt });
       } catch {
         const raw = (err || out || "no output").slice(0, 3500);
-        resolve({ ok: false, text: classifyClaudeError(raw, code) });
+        resolve({ ok: false, text: classifyClaudeError(raw, code), resetAt: parseResetTime(raw) });
       }
     });
   });
@@ -643,9 +686,9 @@ async function runScheduled(job) {
     const footer = res.ok
       ? `\n\n— ⏰ ${label} · ${secs}s${res.cost ? ` · $${res.cost.toFixed(4)}` : ""}`
       : `\n\n— ⏰ ${label}`;
-    await send(cfg.allowedChatId, (res.ok ? res.text : `⚠️ ${res.text}`) + footer);
+    for (const id of allowedIds) await send(id, (res.ok ? res.text : `⚠️ ${res.text}`) + footer);
   } catch (e) {
-    await send(cfg.allowedChatId, t(BOT_LANG, "scheduledError", e.message));
+    for (const id of allowedIds) await send(id, t(BOT_LANG, "scheduledError", e.message));
   } finally {
     busy = false;
   }
@@ -654,7 +697,7 @@ async function runScheduled(job) {
 function startScheduler() {
   // allowedChatId 없으면 결과를 보낼 곳이 없으니 비활성화. /cron add 로 나중에 작업이
   // 늘 수 있으므로, schedule 이 지금 비어 있어도 인터벌은 항상 돌린다(없으면 no-op).
-  if (!cfg.allowedChatId) {
+  if (!allowedIds.length) {
     console.warn("allowedChatId missing → scheduler disabled");
     return;
   }
@@ -795,10 +838,12 @@ async function downloadAttachment(att) {
 let busy = false;
 const msgQueue = []; // { msg, receivedAt } — busy 중 수신 메시지 대기열
 const mediaGroups = new Map(); // media_group_id → { msgs, timer } — 미디어 그룹 수집 대기
-let currentChild = null;  // 실행 중인 claude child process (/stop 용)
-let currentTyping = null; // 타이핑 인터벌 (/stop 시 정리용)
-let prevSessionId;        // /stop --reset 복원 대상
-let stopping = false;     // /stop 처리 중 오류 메시지 억제 플래그
+let currentChild = null;    // 실행 중인 claude child process (/stop 용)
+let currentTyping = null;   // 타이핑 인터벌 (/stop 시 정리용)
+let prevSessionId;          // /stop --reset 복원 대상
+let stopping = false;       // /stop 처리 중 오류 메시지 억제 플래그
+let rateLimitState = null;  // 마지막 레이트 리밋 { prompt, resetAt } — /reserve 용
+let pendingRetry = null;    // /reserve 로 예약된 재시도 { timer, resetAt }
 
 async function handle(msg) {
   const chatId = msg.chat?.id;
@@ -809,11 +854,11 @@ async function handle(msg) {
   if (!text && !attachment && !msg._mediaGroup?.length) return;
 
   // 화이트리스트
-  if (!cfg.allowedChatId) {
+  if (!allowedIds.length) {
     await send(chatId, t(l, "needChatId", chatId));
     return;
   }
-  if (String(chatId) !== String(cfg.allowedChatId)) {
+  if (!allowedIds.includes(String(chatId))) {
     console.warn(`Ignoring unauthorized chatId ${chatId}`);
     return;
   }
@@ -928,6 +973,32 @@ async function handle(msg) {
     await send(chatId, mem ? t(l, "memoryShow", mem) : t(l, "memoryEmpty"));
     return;
   }
+  if (text === "/reserve" || text.startsWith("/reserve ")) {
+    const arg = text.slice(8).trim();
+    if (arg === "rm") {
+      if (!pendingRetry) { await send(chatId, t(l, "reserveNone")); return; }
+      clearTimeout(pendingRetry.timer); pendingRetry = null;
+      await send(chatId, t(l, "reserveRm"));
+      return;
+    }
+    if (!rateLimitState) { await send(chatId, t(l, "reserveNoLimit")); return; }
+    const { resetAt } = rateLimitState;
+    const reservePrompt = arg || rateLimitState.prompt;
+    if (pendingRetry) clearTimeout(pendingRetry.timer);
+    const capturedPrompt = reservePrompt;
+    const capturedMsg = msg;
+    const delay = Math.max(resetAt - Date.now(), 1000);
+    pendingRetry = {
+      resetAt,
+      timer: setTimeout(() => {
+        pendingRetry = null;
+        handle({ ...capturedMsg, text: capturedPrompt, caption: undefined });
+      }, delay),
+    };
+    const timeStr = resetAt.toLocaleTimeString(l === "ko" ? "ko-KR" : "en-US", { hour: "2-digit", minute: "2-digit" });
+    await send(chatId, t(l, "reserveOk", timeStr));
+    return;
+  }
 
   if (busy) {
     msgQueue.push({ msg, receivedAt: Date.now() });
@@ -979,10 +1050,16 @@ async function handle(msg) {
       saveState(state);
     }
     const secs = Math.round((Date.now() - started) / 1000);
-    const footer = res.ok
-      ? `\n\n— ${secs}s${res.cost ? ` · $${res.cost.toFixed(4)}` : ""}`
-      : "";
-    if (!stopping) await send(chatId, (res.ok ? res.text : `⚠️ ${res.text}`) + footer);
+    if (!res.ok) {
+      // 레이트 리밋이고 리셋 시간을 알면 /reserve 힌트 추가
+      const hint = res.resetAt ? t(l, "reserveHint") : "";
+      rateLimitState = res.resetAt ? { prompt, resetAt: res.resetAt } : null;
+      if (!stopping) await send(chatId, `⚠️ ${res.text}${hint}`);
+    } else {
+      rateLimitState = null;
+      const footer = `\n\n— ${secs}s${res.cost ? ` · $${res.cost.toFixed(4)}` : ""}`;
+      if (!stopping) await send(chatId, res.text + footer);
+    }
   } catch (e) {
     if (!stopping) await send(chatId, t(l, "botError", e.message));
   } finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-telegram-bot",
-  "version": "0.3.14",
+  "version": "0.3.17",
   "description": "Drive Claude Code from Telegram — messages run headless `claude -p` in a project dir and replies come back to the chat. Zero dependencies.",
   "type": "module",
   "bin": {