@miphamai/cli 0.49.0 → 0.51.0

package/src/core/task-runner.ts

@@ -0,0 +1,163 @@
+// apps/cli/src/core/task-runner.ts
+// CRSI 端到端任务运行器（C-MVP）——行为效果度量基建。
+import { existsSync, readFileSync, mkdirSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import tasksFile from './task-runner-tasks.json' with { type: 'json' }
+import { QueryEngine } from './engine'
+import { ContextManager } from './context'
+import { PermissionSystem } from './permission'
+import { ProviderRegistry } from '../providers/registry'
+import type { Llm } from '../providers/llm'
+import { createToolRegistry } from '../tools'
+import type { PermissionLevel } from '../shared'
+
+export type RunnerGroundTruth = { kind: 'file-contains'; file: string; contains: string[] }
+
+export interface RunnerTask {
+  id: string
+  instruction: string
+  groundTruth: RunnerGroundTruth
+}
+
+export function loadRunnerTasks(): RunnerTask[] {
+  return tasksFile.tasks as unknown as RunnerTask[]
+}
+
+export function judgeTask(task: RunnerTask, taskDir: string): { passed: boolean; detail?: string } {
+  if (task.groundTruth.kind !== 'file-contains') {
+    return { passed: false, detail: `unsupported groundTruth kind: ${task.groundTruth.kind}` }
+  }
+  const filePath = join(taskDir, task.groundTruth.file)
+  if (!existsSync(filePath)) {
+    return { passed: false, detail: `file not found: ${task.groundTruth.file}` }
+  }
+  const content = readFileSync(filePath, 'utf-8')
+  for (const needle of task.groundTruth.contains) {
+    if (!content.includes(needle)) {
+      return { passed: false, detail: `missing substring: ${needle}` }
+    }
+  }
+  return { passed: true }
+}
+
+export interface TaskRunResult {
+  taskId: string
+  passed: boolean
+  detail?: string
+}
+
+const TASK_DIR_PLACEHOLDER = '<taskDir>'
+
+function buildEngine(llm: Llm, permission: PermissionLevel, systemPrompt?: string): QueryEngine {
+  const registry = new ProviderRegistry([], 'test', 'test-model')
+  // 注册一个永不 chat 的占位 provider——llm 被 setLlm 覆盖，但 process() 内部
+  // 多处调用 registry.getActive().config.id 记录 provider id，必须能取到。
+  registry.register('test', {
+    config: { id: 'test', name: 'Test', protocol: 'openai-compatible', apiKey: 'key', models: [] },
+    chat: async function* () {
+      yield { type: 'stop' }
+    },
+    listModels: async () => [],
+    healthCheck: async () => true,
+  })
+  const context = new ContextManager({ maxTokens: 100_000, compactionThreshold: 0.9 })
+  if (systemPrompt !== undefined) context.setSystemPrompt(systemPrompt)
+  const tools = createToolRegistry()
+  const engine = new QueryEngine(registry, context, tools, new PermissionSystem(permission))
+  engine.setLlm(llm)
+  return engine
+}
+
+export async function runTask(
+  task: RunnerTask,
+  llm: Llm,
+  opts: { taskDir?: string; permission?: PermissionLevel; systemPrompt?: string } = {},
+): Promise<TaskRunResult> {
+  const taskDir = opts.taskDir ?? join(process.cwd(), '.mipham', 'task-runner')
+  const permission = opts.permission ?? 'bypassPermissions'
+
+  rmSync(taskDir, { recursive: true, force: true })
+  mkdirSync(taskDir, { recursive: true })
+
+  const instruction = task.instruction.replaceAll(TASK_DIR_PLACEHOLDER, taskDir)
+  const engine = buildEngine(llm, permission, opts.systemPrompt)
+
+  for await (const _ of engine.process(instruction)) {
+    /* drain agentic loop */
+  }
+
+  const verdict = judgeTask(task, taskDir)
+  return { taskId: task.id, passed: verdict.passed, detail: verdict.detail }
+}
+
+export interface TaskRunStats {
+  taskId: string
+  samples: number
+  passed: number
+  /** 0-1 */
+  passRate: number
+}
+
+export async function runTaskN(
+  task: RunnerTask,
+  llm: Llm,
+  n: number,
+  opts: { taskDir?: string; permission?: PermissionLevel; systemPrompt?: string } = {},
+): Promise<TaskRunStats> {
+  let passed = 0
+  for (let i = 0; i < n; i++) {
+    const result = await runTask(task, llm, opts)
+    if (result.passed) passed++
+  }
+  return { taskId: task.id, samples: n, passed, passRate: n > 0 ? passed / n : 0 }
+}
+
+export interface RunComparison {
+  baseline: TaskRunStats
+  candidate: TaskRunStats
+  /** 弱判：candidate 不退化（不低于 baseline 且至少 1 次成功） */
+  notDegraded: boolean
+  /** candidate 严格更好（通过率更高） */
+  improved: boolean
+}
+
+export function isNotDegraded(baseline: TaskRunStats, candidate: TaskRunStats): boolean {
+  return candidate.passRate >= baseline.passRate && candidate.passed >= 1
+}
+
+export function isImproved(baseline: TaskRunStats, candidate: TaskRunStats): boolean {
+  return candidate.passRate > baseline.passRate
+}
+
+export function compareRuns(baseline: TaskRunStats, candidate: TaskRunStats): RunComparison {
+  return {
+    baseline,
+    candidate,
+    notDegraded: isNotDegraded(baseline, candidate),
+    improved: isImproved(baseline, candidate),
+  }
+}
+
+export async function runBeforeAfter(
+  task: RunnerTask,
+  llm: Llm,
+  n: number,
+  opts: {
+    beforePrompt?: string
+    afterPrompt?: string
+    taskDir?: string
+    permission?: PermissionLevel
+  } = {},
+): Promise<RunComparison> {
+  const baseline = await runTaskN(task, llm, n, {
+    taskDir: opts.taskDir,
+    permission: opts.permission,
+    systemPrompt: opts.beforePrompt,
+  })
+  const candidate = await runTaskN(task, llm, n, {
+    taskDir: opts.taskDir,
+    permission: opts.permission,
+    systemPrompt: opts.afterPrompt,
+  })
+  return compareRuns(baseline, candidate)
+}

package/src/daemon/database.ts

@@ -289,7 +289,6 @@ export class DaemonDatabase {
     }
 
     vals.push(id)
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     this.db.run(`UPDATE goals SET ${sets.join(', ')} WHERE id = ?`, vals as any)
   }
 

package/src/daemon/feishu/adapter.ts

@@ -28,7 +28,8 @@ export function createFeishuAdapter(config: FeishuConfig, deps: FeishuAdapterDep
       if (!allowed.has(msg.openId)) return
       if (!deps.rateLimiter.check(`feishu:${msg.openId}`).allowed) return
 
-      const session = deps.sm.getOrCreateByFeishuOpenId(
+      const session = deps.sm.getOrCreateByExternalUser(
+        'feishu',
         msg.openId,
         deps.cwd,
         deps.provider,

package/src/daemon/heartbeat.ts

@@ -0,0 +1,83 @@
+// apps/cli/src/daemon/heartbeat.ts — 心跳式通知（保守版 KAIROS「订阅与推送」）
+//
+// 借鉴 Claude Code KAIROS 的「主动感知」思路，但严格约束为「只通知、不自主行动」：
+//   - 定时扫描 pending 的 goal（active）与 schedule（enabled）
+//   - 有 pending 时推送一条摘要（默认走 Feishu），无 pending 时静默
+//   - 绝不替用户执行任何动作——「主动感知可以，自主行动必须有闸门」（CRSI 受约束哲学）
+//
+// 纯函数（collectPendingItems / buildHeartbeatMessage / heartbeatTick）便于测试；
+// startHeartbeat 只做 setInterval + unref 的薄接线。
+
+import type { DaemonGoal, DaemonSchedule } from './types'
+
+/** 默认心跳间隔：30 分钟（提醒型通知，不宜过频）。 */
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 30 * 60_000
+
+export interface PendingItems {
+  goalCount: number
+  scheduleCount: number
+  summaries: string[]
+}
+
+/** 收集待办项：active 的 goal + enabled 的 schedule。纯函数。 */
+export function collectPendingItems(
+  goals: DaemonGoal[],
+  schedules: DaemonSchedule[],
+): PendingItems {
+  const activeGoals = goals.filter((g) => g.status === 'active')
+  const enabledSchedules = schedules.filter((s) => s.enabled)
+
+  const summaries: string[] = []
+  for (const g of activeGoals) summaries.push(`🎯 ${g.description}`)
+  for (const s of enabledSchedules) summaries.push(`⏰ [${s.cronExpr}] ${s.prompt}`)
+
+  return {
+    goalCount: activeGoals.length,
+    scheduleCount: enabledSchedules.length,
+    summaries,
+  }
+}
+
+const MAX_SUMMARY_ITEMS = 10
+
+/** 把待办渲染成通知文案；无可待办时返回 null（不打扰）。纯函数。 */
+export function buildHeartbeatMessage(pending: PendingItems): string | null {
+  if (pending.goalCount === 0 && pending.scheduleCount === 0) return null
+
+  const lines = [
+    `💓 Mipham 心跳提醒：${pending.goalCount} 个待办 goal，${pending.scheduleCount} 个定时任务`,
+    '',
+    ...pending.summaries.slice(0, MAX_SUMMARY_ITEMS),
+  ]
+  if (pending.summaries.length > MAX_SUMMARY_ITEMS) {
+    lines.push(`… 另外 ${pending.summaries.length - MAX_SUMMARY_ITEMS} 项`)
+  }
+  return lines.join('\n')
+}
+
+export interface HeartbeatSource {
+  listGoals(): DaemonGoal[]
+  listSchedules(): DaemonSchedule[]
+}
+
+/** 单次心跳：收集待办，有则推送。抽出来便于直接测试。 */
+export function heartbeatTick(source: HeartbeatSource, push: (message: string) => void): void {
+  const pending = collectPendingItems(source.listGoals(), source.listSchedules())
+  const message = buildHeartbeatMessage(pending)
+  if (message) push(message)
+}
+
+export interface HeartbeatDeps {
+  source: HeartbeatSource
+  push: (message: string) => void
+  intervalMs?: number
+}
+
+/** 启动心跳定时器（unref 不阻止进程退出），返回 stop 函数。 */
+export function startHeartbeat(deps: HeartbeatDeps): () => void {
+  const intervalMs = deps.intervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS
+  const id = setInterval(() => heartbeatTick(deps.source, deps.push), intervalMs)
+  // Bun 的 Timer 有 unref；假定时器/其它运行时不保证——用可选调用容错。
+  ;(id as { unref?: () => void }).unref?.()
+  return () => clearInterval(id)
+}

package/src/daemon/index.ts

@@ -25,6 +25,8 @@ import type { DaemonStatus } from './types'
 import { logger } from './logger'
 import { parseFeishuEnv } from './feishu/env.js'
 import type { FeishuConfig } from './feishu/types.js'
+import { parseTelegramEnv } from './telegram/env.js'
+import type { TelegramConfig } from './telegram/types.js'
 import { loadConfig } from '../config/loader'
 
 const HOME = homedir()
@@ -40,8 +42,6 @@ const DEFAULT_PORT = 45671
 let activeServer: Server<unknown> | null = null
 let activeDb: DaemonDatabase | null = null
 let activePool: WorkerPool | null = null
-let activeAgentManager: AgentManager | null = null
-let activeMessageBus: MessageBus | null = null
 let activeScheduleManager: ScheduleManager | null = null
 let activeRateLimiter: RateLimiter | null = null
 
@@ -150,9 +150,7 @@ export async function startDaemon(): Promise<{ port: number; token: string }> {
 
   // Create agent manager and message bus (Phase 3)
   const agentManager = new AgentManager(db)
-  activeAgentManager = agentManager
   const messageBus = new MessageBus()
-  activeMessageBus = messageBus
 
   // Create goal manager and schedule manager (Phase 4)
   const goalManager = new GoalManager(db)
@@ -181,6 +179,21 @@ export async function startDaemon(): Promise<{ port: number; token: string }> {
     }
   }
 
+  // Telegram remote-control adapter（env 未配置时跳过；配置则解析 session 默认 provider/model）
+  const telegramConfig = parseTelegramEnv()
+  let telegram: { config: TelegramConfig; cwd: string; provider: string; model: string } | undefined
+  if (telegramConfig) {
+    const cfg = loadConfig()
+    // 取第一个非 upcoming（即非「待上线」）的 provider 及其首个 model
+    const provider = cfg.providers.find((p) => p.status !== 'upcoming') ?? cfg.providers[0]
+    telegram = {
+      config: telegramConfig,
+      cwd: process.env.TELEGRAM_CWD || process.cwd(),
+      provider: provider?.id ?? 'anthropic',
+      model: provider?.models?.[0]?.id ?? 'claude-sonnet-5',
+    }
+  }
+
   // Start HTTP server (Bun.serve starts listening immediately)
   const server = createServer({
     db,
@@ -196,6 +209,7 @@ export async function startDaemon(): Promise<{ port: number; token: string }> {
     scheduleManager,
     rateLimiter,
     feishu,
+    telegram,
   })
   activeServer = server
 
@@ -250,10 +264,6 @@ export async function stopDaemon(force: boolean = false): Promise<void> {
     activeRateLimiter = null
   }
 
-  // Clean up agent manager and message bus (Phase 3)
-  activeAgentManager = null
-  activeMessageBus = null
-
   // Close database (commits any pending WAL)
   if (activeDb) {
     activeDb.close()

package/src/daemon/server.ts

@@ -22,9 +22,14 @@ import { bootstrapProviders } from '../providers/bootstrap'
 import { createToolRegistry } from '../tools'
 import { PermissionSystem } from '../core/permission'
 import type { ProviderRegistry } from '../providers/registry'
-import type { ToolDefinition, PermissionMode } from '../shared/types'
+import type { ToolDefinition, PermissionMode, PermissionRestrictions } from '../shared/types'
 import { createFeishuAdapter } from './feishu/adapter.js'
+import { createFeishuApi } from './feishu/api.js'
 import type { FeishuConfig } from './feishu/types.js'
+import { createTelegramAdapter } from './telegram/adapter.js'
+import { createTelegramApi } from './telegram/api.js'
+import type { TelegramConfig } from './telegram/types.js'
+import { startHeartbeat } from './heartbeat'
 
 interface ServerConfig {
   db: DaemonDatabase
@@ -40,6 +45,7 @@ interface ServerConfig {
   scheduleManager: ScheduleManager
   rateLimiter: RateLimiter
   feishu?: { config: FeishuConfig; cwd: string; provider: string; model: string }
+  telegram?: { config: TelegramConfig; cwd: string; provider: string; model: string }
 }
 
 interface WsData {
@@ -67,6 +73,25 @@ function resolveDaemonPermission(): PermissionMode {
     : 'default'
 }
 
+/**
+ * Build the daemon's PermissionSystem, honoring org-level restrictions
+ * (permissionRestrictions) and user-defined allow/deny rules. setRestrictions
+ * re-clamps the env-derived mode, so a `MIPHAM_DAEMON_PERMISSION=bypassPermissions`
+ * is downgraded when the config forbids it — mirroring the CLI's fail-closed behavior.
+ */
+export function buildDaemonPermission(
+  restrictions?: PermissionRestrictions,
+  rules?: { allow?: string[]; deny?: string[] },
+): PermissionSystem {
+  const permission = new PermissionSystem(resolveDaemonPermission())
+  if (restrictions) permission.setRestrictions(restrictions)
+  if (rules) {
+    for (const rule of rules.allow ?? []) permission.allow(rule)
+    for (const rule of rules.deny ?? []) permission.deny(rule)
+  }
+  return permission
+}
+
 const DAEMON_DEFAULT_CONTEXT_WINDOW = 200_000
 
 /**
@@ -98,6 +123,7 @@ export function createServer(config: ServerConfig): Server<WsData> {
     scheduleManager,
     rateLimiter,
     feishu,
+    telegram,
   } = config
 
   const wsClients = new Map<string, Set<ServerWebSocket<WsData>>>()
@@ -185,7 +211,11 @@ export function createServer(config: ServerConfig): Server<WsData> {
       }
     }
 
-    const permission = new PermissionSystem(resolveDaemonPermission())
+    const daemonConfig = loadConfig(cwd)
+    const permission = buildDaemonPermission(
+      daemonConfig.permissionRestrictions,
+      daemonConfig.permissionRules,
+    )
     const engine = new QueryEngine(sharedRegistry, context, sharedTools, permission)
     engine.setSessionId(sessionId)
     engineCache.set(sessionId, engine)
@@ -194,7 +224,7 @@ export function createServer(config: ServerConfig): Server<WsData> {
 
   function getOrCreateWorker(
     sessionId: string,
-    ws?: ServerWebSocket<WsData>,
+    _ws?: ServerWebSocket<WsData>,
   ): SessionWorker | null {
     try {
       const session = db.getSession(sessionId)
@@ -231,6 +261,51 @@ export function createServer(config: ServerConfig): Server<WsData> {
       })
     : undefined
 
+  // ── Telegram remote-control adapter（长轮询，无需 webhook 路由）──
+  const telegramAdapter = telegram
+    ? createTelegramAdapter(telegram.config, createTelegramApi(telegram.config), {
+        sm,
+        getOrCreateWorker,
+        rateLimiter,
+        cwd: telegram.cwd,
+        provider: telegram.provider,
+        model: telegram.model,
+      })
+    : undefined
+  telegramAdapter?.start()
+
+  // ── 心跳式通知：定时扫 pending（goal/schedule），只通知、不自主行动 ──
+  const heartbeatSource = {
+    listGoals: () => sm.listSessions().flatMap((s) => goalManager.getGoals(s.id)),
+    listSchedules: () => sm.listSessions().flatMap((s) => scheduleManager.getSchedules(s.id)),
+  }
+  if (feishu) {
+    const feishuApi = createFeishuApi(feishu.config)
+    startHeartbeat({
+      source: heartbeatSource,
+      push: (message) => {
+        for (const openId of feishu.config.allowedOpenIds) {
+          void feishuApi.sendText(openId, message).catch(() => {
+            /* 推送失败静默，不打断心跳 */
+          })
+        }
+      },
+    })
+  }
+  if (telegram) {
+    const telegramApi = createTelegramApi(telegram.config)
+    startHeartbeat({
+      source: heartbeatSource,
+      push: (message) => {
+        for (const chatId of telegram.config.allowedChatIds) {
+          void telegramApi.sendText(chatId, message).catch(() => {
+            /* 推送失败静默，不打断心跳 */
+          })
+        }
+      },
+    })
+  }
+
   const server = Bun.serve<WsData>({
     port,
     hostname,

package/src/daemon/session-manager.ts

@@ -1,5 +1,5 @@
 import type { DaemonDatabase } from './database'
-import type { DaemonSession, SessionStatus } from './types'
+import type { DaemonSession } from './types'
 
 type SessionCloseCallback = (sessionId: string) => void
 
@@ -23,13 +23,14 @@ export class SessionManager {
     return this.db.listSessions(status)
   }
 
-  getOrCreateByFeishuOpenId(
-    openId: string,
+  getOrCreateByExternalUser(
+    channel: string,
+    userId: string,
     cwd: string,
     provider: string,
     model: string,
   ): DaemonSession {
-    const name = `feishu-${openId}`
+    const name = `${channel}-${userId}`
     const existing = this.db.listSessions().find((s) => s.name === name && s.status !== 'closed')
     if (existing) return existing
     return this.db.createSession({ name, cwd, provider, model })

package/src/daemon/telegram/adapter.ts

@@ -0,0 +1,70 @@
+import type { TelegramApi } from './api.js'
+import type { TelegramConfig, TelegramMessage } from './types.js'
+import type { SessionManager } from '../session-manager'
+import type { SessionWorker } from '../session-worker'
+import type { RateLimiter } from '../rate-limiter'
+import { startTelegramPoller } from './poller.js'
+
+export interface TelegramAdapterDeps {
+  sm: SessionManager
+  getOrCreateWorker: (sessionId: string) => SessionWorker | null
+  rateLimiter: RateLimiter
+  cwd: string
+  provider: string
+  model: string
+}
+
+export interface TelegramAdapter {
+  start(): () => void
+  handleMessage(msg: TelegramMessage): Promise<void>
+  isAllowed(chatId: string): boolean
+}
+
+export function createTelegramAdapter(
+  config: TelegramConfig,
+  api: TelegramApi,
+  deps: TelegramAdapterDeps,
+): TelegramAdapter {
+  const allowed = new Set(config.allowedChatIds)
+  let stopPoller: (() => void) | null = null
+
+  async function handleMessage(msg: TelegramMessage): Promise<void> {
+    try {
+      if (!allowed.has(msg.chatId)) return
+      if (!deps.rateLimiter.check(`telegram:${msg.chatId}`).allowed) return
+
+      const session = deps.sm.getOrCreateByExternalUser(
+        'telegram',
+        msg.chatId,
+        deps.cwd,
+        deps.provider,
+        deps.model,
+      )
+      const worker = deps.getOrCreateWorker(session.id)
+      if (!worker) {
+        await api.sendText(msg.chatId, '（会话初始化失败，请稍后重试）')
+        return
+      }
+      await worker.processPrompt(msg.text)
+      const result = worker.getLastAssistantContent()
+      await api.sendText(msg.chatId, result ? result.slice(0, 4096) : '（无回复）')
+    } catch (err) {
+      console.error('[telegram] message handling failed:', err)
+      try {
+        await api.sendText(msg.chatId, '（处理失败，请稍后重试）')
+      } catch {
+        /* 忽略回送失败，不 rethrow */
+      }
+    }
+  }
+
+  return {
+    handleMessage,
+    isAllowed: (chatId) => allowed.has(chatId),
+    start() {
+      if (stopPoller) return stopPoller
+      stopPoller = startTelegramPoller(api, handleMessage)
+      return stopPoller
+    },
+  }
+}

package/src/daemon/telegram/api.ts

@@ -0,0 +1,45 @@
+import type { TelegramConfig } from './types.js'
+
+export interface TelegramApi {
+  getUpdates(
+    offset: number,
+    timeoutSeconds: number,
+  ): Promise<Array<{ update_id: number; message?: unknown }>>
+  sendText(chatId: string, text: string): Promise<void>
+}
+
+/** 裸 fetch 直连 Telegram Bot API，零依赖。 */
+export function createTelegramApi(config: TelegramConfig): TelegramApi {
+  const base = `https://api.telegram.org/bot${config.botToken}`
+  return {
+    async getUpdates(offset, timeoutSeconds) {
+      const url =
+        `${base}/getUpdates?offset=${offset}&timeout=${timeoutSeconds}` +
+        `&limit=100&allowed_updates=%5B%22message%22%5D`
+      const res = await fetch(url)
+      if (!res.ok) throw new Error(`getUpdates ${res.status}`)
+      const data = (await res.json()) as {
+        ok: boolean
+        result?: Array<{ update_id: number; message?: unknown }>
+        error_code?: number
+        description?: string
+      }
+      if (!data.ok) throw new Error(`getUpdates failed: ${data.error_code ?? res.status}`)
+      return data.result ?? []
+    },
+    async sendText(chatId, text) {
+      const res = await fetch(`${base}/sendMessage`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ chat_id: chatId, text }),
+      })
+      if (!res.ok) throw new Error(`sendMessage ${res.status}`)
+      const data = (await res.json()) as {
+        ok: boolean
+        error_code?: number
+        description?: string
+      }
+      if (!data.ok) throw new Error(`sendMessage failed: ${data.error_code ?? res.status}`)
+    },
+  }
+}

package/src/daemon/telegram/env.ts

@@ -0,0 +1,14 @@
+import type { TelegramConfig } from './types.js'
+
+/** fail-closed：缺 botToken → null（daemon 不启用 Telegram）。 */
+export function parseTelegramEnv(): TelegramConfig | null {
+  const botToken = process.env.TELEGRAM_BOT_TOKEN
+  if (!botToken) return null
+  return {
+    botToken,
+    allowedChatIds: (process.env.TELEGRAM_ALLOWED_CHAT_IDS || '')
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean),
+  }
+}

package/src/daemon/telegram/poller.ts

@@ -0,0 +1,64 @@
+import type { TelegramApi } from './api.js'
+import type { TelegramMessage } from './types.js'
+
+/** 从 update 提取文本消息；非文本/缺 message → null。chat.id 统一字符串化比对（id < 2^53；超范围 bigint 后续再引入）。 */
+export function extractTextMessage(update: unknown): TelegramMessage | null {
+  const msg = (
+    update as { message?: { chat?: { id?: number | string }; message_id?: number; text?: string } }
+  )?.message
+  if (!msg?.text || msg.chat?.id == null) return null
+  return { chatId: String(msg.chat.id), messageId: msg.message_id ?? 0, text: msg.text }
+}
+
+/** 推进 offset：最大 update_id + 1；空列表沿用 prev。 */
+export function nextOffset(updates: Array<{ update_id?: number }>, prevOffset: number): number {
+  if (updates.length === 0) return prevOffset
+  return Math.max(...updates.map((u) => u.update_id ?? prevOffset)) + 1
+}
+
+/** 指数退避，封顶 30s。 */
+export function nextBackoff(currentMs: number): number {
+  return Math.min(currentMs * 2, 30_000)
+}
+
+/** 长轮询循环（unref 不阻退出）。返回 stop 函数。循环行为由 Task 7 集成测试覆盖。 */
+export function startTelegramPoller(
+  api: TelegramApi,
+  onMessage: (msg: TelegramMessage) => Promise<void>,
+  opts?: { pollTimeoutSeconds?: number },
+): () => void {
+  let offset = 0
+  let backoffMs = 1000
+  let stopped = false
+  let timer: ReturnType<typeof setTimeout> | null = null
+
+  async function loop() {
+    if (stopped) return
+    try {
+      const updates = await api.getUpdates(offset, opts?.pollTimeoutSeconds ?? 30)
+      for (const u of updates) {
+        const msg = extractTextMessage(u)
+        if (msg) {
+          try {
+            await onMessage(msg)
+          } catch {
+            /* 单条失败不中断轮询 */
+          }
+        }
+      }
+      offset = nextOffset(updates, offset)
+      backoffMs = 1000
+    } catch {
+      backoffMs = nextBackoff(backoffMs)
+    }
+    if (stopped) return
+    timer = setTimeout(loop, backoffMs)
+    ;(timer as { unref?: () => void }).unref?.()
+  }
+
+  void loop()
+  return () => {
+    stopped = true
+    if (timer) clearTimeout(timer)
+  }
+}