@jc_stack/ez-agents 0.1.0-beta.12

package/src/index.ts

@@ -0,0 +1,812 @@
+import { randomUUID } from 'node:crypto'
+import { stat } from 'node:fs/promises'
+import { queueUpdateAttention } from './update-attention.js'
+import { EventSources, eventRunId, batchReady, type SourceEvent } from './event-sources.js'
+import { dirname, join, basename } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+import { Bot, InlineKeyboard, InputFile, GrammyError, type Context } from 'grammy'
+import type { ChildProcess } from 'node:child_process'
+import { isOwner } from './identity.js'
+import type { Update } from 'grammy/types'
+import { InboxStore, type IncomingItem } from './inbox.js'
+import { loadConfig, type Config } from './config.js'
+import { ControlStore } from './control-state.js'
+import { ApprovalStore } from './approval.js'
+import { startExecutorJob, terminateJob } from './executor.js'
+import { RunStore, type RunRecord } from './runs.js'
+import { splitTelegramText } from './reply.js'
+import { markdownToTelegramHtml, escapeHtml } from './format.js'
+import { sanitizeFileName, stageIncomingFile, workspaceFile } from './files.js'
+import { transcribeAudio, synthesizeSpeech } from './audio.js'
+import { normalizeReactionEmoji } from './reaction.js'
+import { downloadTelegramFile } from './read-request.js'
+import { createAiMenu, mainCommands, mainKeyboard } from './menu.js'
+import { presetLabel } from './ai.js'
+import { initializeWorkspace } from './workspace.js'
+import { softwareStatus } from './software-status.js'
+
+export const createRelay = (config: Config, launch = startExecutorJob) => {
+  const safeError = (error: unknown): string => {
+    let message = error instanceof Error ? error.message : 'Unknown error'
+    for (const secret of [config.telegramBotToken, config.geminiApiKey, config.openaiApiKey]) {
+      if (secret) message = message.replaceAll(secret, '[redacted]')
+    }
+    return message
+  }
+  const bot = new Bot(config.telegramBotToken)
+  const control = new ControlStore(config.controlDir, config.pairingTtlMs)
+  const approvals = new ApprovalStore(config.controlDir)
+  const runs = new RunStore(config.controlDir)
+  const inbox = new InboxStore(config.controlDir)
+  const sources = new EventSources(config.controlDir)
+  const aiMenu = createAiMenu(control, config.executorCli, undefined, config.workspace)
+  const binDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'bin')
+
+  let activeTypingTimer: ReturnType<typeof setInterval> | null = null
+  let activeChild: ChildProcess | null = null
+  let shuttingDown = false
+  let nextSendAt = 0
+  const paceSend = async () => {
+    const delay = nextSendAt - Date.now()
+    if (delay > 0) await new Promise((resolve) => setTimeout(resolve, delay))
+    nextSendAt = Date.now() + 1000
+  }
+  let startLock: Promise<void> = Promise.resolve()
+  const withStartLock = (work: () => Promise<void>): Promise<void> => {
+    const next = startLock.then(work, work)
+    startLock = next.then(
+      () => undefined,
+      () => undefined,
+    )
+    return next
+  }
+
+  const sendChat = async (chatId: number, text: string, replyToMessageId?: number): Promise<number[]> => {
+    const ids: number[] = []
+    const parts = splitTelegramText(text)
+    for (let i = 0; i < parts.length; i++) {
+      await paceSend()
+      const part = parts[i]
+      const replyParams =
+        i === 0 && replyToMessageId ? { reply_parameters: { message_id: replyToMessageId } } : {}
+      try {
+        const html = markdownToTelegramHtml(part)
+        const sent = await bot.api.sendMessage(chatId, html, { parse_mode: 'HTML', ...replyParams })
+        ids.push(sent.message_id)
+      } catch (error) {
+        if (
+          !(error instanceof GrammyError) ||
+          error.error_code !== 400 ||
+          !error.description.includes('parse entities')
+        )
+          throw error
+        // Fallback to plain text if HTML parsing fails
+        const sent = await bot.api.sendMessage(chatId, part, { ...replyParams })
+        ids.push(sent.message_id)
+      }
+    }
+    return ids
+  }
+
+  const startJob = async (run: RunRecord): Promise<void> => {
+    await withStartLock(async () => {
+      if (shuttingDown || activeChild) return
+      // stat uses the effective UID; access uses the relay's isolated real UID.
+      if (await stat(join(config.controlDir,'upgrade-pause.json')).then(()=>true,e=>{if(e.code==='ENOENT')return false;throw e})) return
+      if ((await runs.get(run.id))?.status !== 'queued') return
+      if (await runs.running()) return
+      const owner = (await control.status()).owner
+      if (!owner || owner.telegramUserId !== run.telegramUserId || owner.telegramChatId !== run.chatId) {
+        await runs.patch(run.id, { status: 'failed', endedAt: new Date().toISOString() })
+        return
+      }
+      let texts = run.texts
+      if (run.external) {
+        // Availability failures leave durable queued work for a later check.
+        let events: SourceEvent[]
+        try { events = await sources.check(run.external, owner); unavailableSources.delete(run.external.sourceId) } catch { unavailableSources.add(run.external.sourceId); return }
+        if (!events.length) {
+          await runs.patch(run.id, { status: 'cancelled', endedAt: new Date().toISOString() })
+          return
+        }
+        texts = events.map(event => JSON.stringify(event))
+      }
+      try {
+        const started = await runs.patch(run.id, { status: 'running', startedAt: new Date().toISOString() })
+        if (!started.execution) throw new Error('Legacy queued work has no pinned AI. Resend the request after /new.')
+        const session = run.external
+          ? { sessionId: randomUUID(), hasStarted: false, nativeSessionId: undefined }
+          : await control.executionSession(started.execution)
+        const selected = started.execution.preset
+        const { child, cleanup } = await launch(texts, {
+          workspace: config.workspace,
+          timeoutMs: config.executorTimeoutMs,
+          runId: started.id,
+          controlDir: config.controlDir,
+          binDir,
+          cli: selected.cli,
+          model: selected.model,
+          effort: selected.effort,
+          sessionId: session.nativeSessionId || session.sessionId,
+          isResume: session.hasStarted,
+          eventSource: run.external?.sourceId,
+          onSession: run.external ? undefined : (id) => control.saveNativeSession(session.sessionId, id),
+        })
+        activeChild = child
+        const finished = new Promise<number | null>((resolve) => {
+          if (child.exitCode !== null || child.signalCode !== null) resolve(child.exitCode)
+          else child.once('close', resolve)
+        })
+        await runs.patch(started.id, { pid: child.pid })
+        console.info('run started', {
+          run_id: started.id,
+          pid: child.pid,
+          cli: selected.cli,
+          session: session.sessionId,
+          isResume: session.hasStarted,
+        })
+
+        if (activeTypingTimer) clearInterval(activeTypingTimer)
+        if (!run.external) activeTypingTimer = setInterval(() => {
+          void bot.api.sendChatAction(run.chatId, 'typing').catch(() => {})
+        }, 4000)
+
+        child.stderr?.setEncoding('utf8').on('data', (chunk: string) => {
+          if (chunk.trim()) console.error('executor stderr', started.id, chunk.trim())
+        })
+        void finished.then((code) => {
+          void (async () => {
+            await withStartLock(async () => {
+              try {
+                await cleanup()
+                if (code === 0 && !run.external) await control.markSessionStarted(session.sessionId)
+                await runs.patch(started.id, { status: code === 0 ? 'completed' : 'failed', endedAt: new Date().toISOString() })
+              } catch (error) {
+                await runs.patch(started.id, { status: 'failed', endedAt: new Date().toISOString() })
+                console.error('Session completion failed', safeError(error))
+              } finally {
+                activeChild = null
+                if (activeTypingTimer) clearInterval(activeTypingTimer)
+                activeTypingTimer = null
+              }
+            })
+            console.info('run ended', { run_id: started.id, code })
+            const next = await runs.nextQueued()
+            if (next && !shuttingDown) await startJob(next)
+          })().catch((error) => console.error('Run completion failed', error.message))
+        })
+      } catch (error) {
+        if (activeTypingTimer) {
+          clearInterval(activeTypingTimer)
+          activeTypingTimer = null
+        }
+        await runs.patch(run.id, { status: 'failed', endedAt: new Date().toISOString() })
+        console.error('run start failed', run.id, safeError(error))
+        await sendChat(run.chatId, `Run ${run.id} failed to start. Check the local relay log.`)
+        setImmediate(() => {
+          void runs
+            .nextQueued()
+            .then((next) => next && startJob(next))
+            .catch(console.error)
+        })
+      }
+    })
+  }
+
+  const unavailableSources = new Set<string>()
+  let sourceWork: Promise<void> | undefined
+  const drainSources = (): Promise<void> => {
+    if (sourceWork) return sourceWork
+    sourceWork = (async () => {
+      if (shuttingDown) return
+      const owner = (await control.status()).owner
+      if (!owner) return
+      await queueUpdateAttention(config.controlDir,owner,runs,await control.captureChoice(aiMenu.initial))
+      for (const source of await sources.available(owner)) {
+        try {
+          const batch = await sources.batch(source)
+          unavailableSources.delete(source.id)
+          if (!batchReady(batch.events)) continue
+          await withStartLock(async () => {
+            if (shuttingDown) return
+            await sources.remember(source, batch)
+            const groups = new Map<string, SourceEvent[]>()
+            for (const event of batch.events) groups.set(event.conversationId, [...(groups.get(event.conversationId) || []), event])
+            for (const events of groups.values()) await runs.create({
+              id: eventRunId(source, events), chatId: owner.telegramChatId, telegramUserId: owner.telegramUserId,
+              texts: [], execution: await control.captureChoice(aiMenu.initial),
+              external: { sourceId: source.id, bindingId: source.bindingId, eventIds: events.map(e => e.id) },
+            })
+            // Acknowledgement follows durable run creation; replay uses the saved batch.
+            await sources.advance(source, batch.cursor)
+          })
+        } catch { unavailableSources.add(source.id) }
+      }
+      for (const run of (await runs.list()).filter(r => r.status === 'queued')) {
+        if (activeChild || shuttingDown) break
+        await startJob(run)
+      }
+    })().finally(() => { sourceWork = undefined })
+    return sourceWork
+  }
+  let sourceTimer: ReturnType<typeof setInterval> | undefined
+
+  const replay = new WeakSet<Update>()
+  let collected: IncomingItem[] = []
+  let normalizing: Update | undefined
+  let intakeTimer: ReturnType<typeof setTimeout> | undefined
+  let intakeWork: Promise<void> | undefined
+  const collectItem = (item: IncomingItem) => {
+    const message = normalizing?.message
+    if (message?.media_group_id) item.text = `[Telegram album: ${message.media_group_id}]\n${item.text}`
+    if (message && !message.text && message.reply_to_message) {
+      const quoted = message.reply_to_message
+      item.text = `[Quoted message ${quoted.message_id}]: ${quoted.text || quoted.caption || '[media]'}\n\n${item.text}`
+    }
+    collected.push(item)
+  }
+  const scheduleIntake = () => {
+    if (shuttingDown || intakeTimer) return
+    intakeTimer = setTimeout(() => {
+      intakeTimer = undefined
+      void drainInbox().catch((error) => console.error('Inbox drain failed', safeError(error)))
+    }, 250)
+  }
+  const drainInbox = (force = false): Promise<void> => {
+    if (intakeWork) return intakeWork
+    intakeWork = (async () => {
+      if (shuttingDown) return
+      const batch = await inbox.next(force)
+      if (!batch) return
+      try {
+        let run = await runs.get(batch.id)
+        if (!run) {
+          collected = []
+          for (const entry of batch.entries) {
+            if (shuttingDown || !(await inbox.pending(batch.id))) return
+            normalizing = entry.update
+            replay.add(entry.update)
+            try {
+              await bot.handleUpdate(entry.update)
+            } finally {
+              replay.delete(entry.update)
+              normalizing = undefined
+            }
+          }
+          await withStartLock(async () => {
+            if (shuttingDown || !(await inbox.pending(batch.id))) return
+            const first = collected[0]
+            if (first)
+              run = await runs.create({
+                id: batch.id,
+                chatId: first.chatId,
+                telegramUserId: first.fromId,
+                messageId: first.messageId,
+                texts: collected.map((item) => item.text),
+                execution: batch.entries[0].execution,
+              })
+            await inbox.finish(batch.id)
+          })
+        } else await inbox.finish(batch.id)
+        if (run) await startJob(run)
+      } catch (error) {
+        await inbox.finish(batch.id, true)
+        console.error('Inbox batch failed', batch.id, safeError(error))
+      }
+    })().finally(() => {
+      intakeWork = undefined
+      if (!shuttingDown)
+        void inbox
+          .status()
+          .then((state) => {
+            if (state.pending) scheduleIntake()
+          })
+          .catch((error) => console.error('Inbox status failed', safeError(error)))
+    })
+    return intakeWork
+  }
+
+  let isDraining = false
+  const drainOutbox = async (onlyRunId?: string): Promise<void> => {
+    if (isDraining) return
+    isDraining = true
+    try {
+      for (const item of await runs.pendingOutbox()) {
+        if (onlyRunId && item.runId !== onlyRunId) continue
+        const claimed = await runs.claimOutbox(item.id)
+        if (!claimed) continue
+        let attemptedDelivery = false
+        try {
+          const replyParams = item.replyToMessageId
+            ? { reply_parameters: { message_id: item.replyToMessageId } }
+            : {}
+          const owner = (await control.status()).owner
+          const origin = await runs.get(item.runId)
+          if (
+            !origin ||
+            !owner ||
+            origin.telegramUserId !== owner.telegramUserId ||
+            origin.chatId !== owner.telegramChatId ||
+            item.chatId !== origin.chatId
+          )
+            throw new Error('Outbox ownership mismatch')
+          const receiptIds: number[] = []
+
+          if (item.type === 'reaction' && item.emoji && item.messageId) {
+            const emoji = normalizeReactionEmoji(item.emoji)
+            if (!emoji) throw new Error('Unsupported reaction')
+            attemptedDelivery = true
+            await bot.api.setMessageReaction(item.chatId, item.messageId, [
+              { type: 'emoji', emoji: emoji as any },
+            ])
+            console.info('run reaction sent', { run_id: item.runId, emoji })
+          } else if (item.type === 'document' && item.documentPath) {
+            const docPath = await workspaceFile(config.workspace, item.documentPath)
+            await paceSend()
+            attemptedDelivery = true
+            const sent = await bot.api.sendDocument(item.chatId, new InputFile(docPath), {
+              caption: item.text,
+              ...replyParams,
+            })
+            console.info('run document sent', { run_id: item.runId, path: docPath })
+            receiptIds.push(sent.message_id)
+          } else if (item.type === 'voice' && item.voiceText) {
+            await bot.api.sendChatAction(item.chatId, 'record_voice')
+            const { buffer } = await synthesizeSpeech(item.voiceText, {
+              geminiApiKey: config.geminiApiKey,
+              openaiApiKey: config.openaiApiKey,
+            })
+            await paceSend()
+            attemptedDelivery = true
+            const sent = await bot.api.sendVoice(item.chatId, new InputFile(buffer, 'voice.ogg'), replyParams)
+            receiptIds.push(sent.message_id)
+            console.info('run voice sent', { run_id: item.runId })
+          } else if (item.type === 'approval' && item.approvalPrompt && item.approvalActionId) {
+            const keyboard = new InlineKeyboard()
+              .text('Approve ✅', `approval:${item.approvalActionId}:approve`)
+              .text('Deny ❌', `approval:${item.approvalActionId}:deny`)
+            const html = `⚠️ <b>Approval Required</b>\n\n${markdownToTelegramHtml(item.approvalPrompt)}`
+            await paceSend()
+            attemptedDelivery = true
+            const sent = await bot.api.sendMessage(item.chatId, html, {
+              parse_mode: 'HTML',
+              reply_markup: keyboard,
+              ...replyParams,
+            })
+            console.info('run approval requested', { run_id: item.runId, action_id: item.approvalActionId })
+            receiptIds.push(sent.message_id)
+          } else if (item.text) {
+            attemptedDelivery = true
+            const ids = await sendChat(item.chatId, item.text, item.replyToMessageId)
+            receiptIds.push(...ids)
+            console.info('run message sent', { run_id: item.runId, outbox_id: item.id, message_ids: ids })
+          } else throw new Error('Outbox item has no supported payload')
+          await runs.markOutboxSent(item.id, receiptIds)
+        } catch (error) {
+          console.error('outbox item processing failed', item.id, safeError(error))
+          await runs.failOutbox(
+            item.id,
+            safeError(error),
+            attemptedDelivery && !(error instanceof GrammyError),
+          )
+        }
+      }
+    } finally {
+      isDraining = false
+    }
+  }
+
+  const checkOwner = async (ctx: Context): Promise<boolean> => {
+    if (!ctx.from || ctx.from.is_bot || ctx.chat?.type !== 'private') return false
+    const state = await control.status()
+    if (!state.owner) {
+      const result = await control.requestPairing(ctx.from.id, ctx.chat.id)
+      if (result === 'requested')
+        await ctx.reply('Owner approval is pending. Confirm this request through the local setup assistant.')
+      if (result === 'pending') await ctx.reply('Owner approval is still pending.')
+      if (result === 'capacity')
+        await ctx.reply('Owner setup is unavailable. Ask the local administrator to review pending requests.')
+      if (result === 'owner-exists') await ctx.reply('This agent already has an owner.')
+      return false
+    }
+    return isOwner(ctx, state.owner)
+  }
+
+  const aliases = [
+    { command: 'help', description: 'Show available controls' },
+    { command: 'status', description: 'Work, queue and delivery health' },
+    { command: 'stop', description: 'Stop active work; keep queued messages' },
+    { command: 'cancel', description: 'Cancel pending messages; keep active work' },
+    { command: 'retry', description: 'Retry the latest failed incoming batch' },
+    { command: 'new', description: 'New conversation; keep workspace files' },
+  ]
+  const commands = mainCommands
+  const controlCommand = (text?: string) => text?.trim().replace(/@[a-zA-Z0-9_]+$/, '')
+  const statusText = async () => {
+    const running = await runs.running()
+    const all = await runs.list()
+    const incoming = await inbox.status()
+    const delivery = await runs.deliveryStatus()
+    const session = await control.getActiveSession()
+    const ai = await control.aiState(aiMenu.initial)
+    const selected = ai.presets.find((p) => p.id === ai.selectedId)!
+    return [
+      ...await softwareStatus(config.controlDir),
+      `AI: ${selected.name} (${presetLabel(selected)})`,
+      `Default: ${ai.presets.find((p) => p.id === ai.defaultId)!.name}`,
+      `Session: ${session?.sessionId.slice(0, 8) || 'none'}`,
+      `Work: ${running ? `running ${running.id}` : 'idle'}`,
+      `Queue: ${all.filter((r) => r.status === 'queued').length} runs; ${incoming.pending} incoming messages`,
+      `Failed: ${all.filter((r) => r.status === 'failed').length} runs; ${incoming.failed} incoming batches`,
+      `Delivery: ${delivery.failed} failed; ${delivery.unknown} unknown/in-flight (inspect before retrying)`,
+      ...(unavailableSources.size ? [`Unavailable event sources: ${[...unavailableSources].join(', ')}`] : []),
+      '/stop stops active work only. /cancel clears pending work only.',
+      ...(config.executorCli === 'grok'
+        ? [
+            'Known limitation: interrupted Grok sessions may stall on resume. /new explicitly resets the conversation.',
+          ]
+        : []),
+    ].join('\n')
+  }
+  const cancelPending = async () => {
+    let count = 0
+    await withStartLock(async () => {
+      count += await inbox.cancel()
+      for (const run of await runs.list()) {
+        if (run.status !== 'queued') continue
+        await runs.patch(run.id, { status: 'cancelled', endedAt: new Date().toISOString() })
+        count++
+      }
+    })
+    return `Cancelled ${count} pending messages/runs. Active work was not stopped.`
+  }
+
+  // Returning from the polling handler acknowledges intake, not execution. Only
+  // return after the authorized update has reached the atomic local journal.
+  bot.use(async (ctx, next) => {
+    if (replay.has(ctx.update)) {
+      if (isOwner(ctx, (await control.status()).owner)) return next()
+      return
+    }
+    const message = ctx.message
+    const command = controlCommand(message?.text)
+    if (command && [...commands, ...aliases].map((c) => `/${c.command}`).concat('/menu').includes(command)) return next()
+    const ordinary = message && (message.text || message.photo || message.document || message.voice)
+    const approval = ctx.callbackQuery?.data?.startsWith('approval:')
+    if (!ordinary && !approval) return next()
+    if (!(await checkOwner(ctx))) return
+    if (await inbox.accept(ctx.update, await control.captureChoice(aiMenu.initial))) scheduleIntake()
+  })
+
+  bot.on('message:text', async (ctx) => {
+    if (!(await checkOwner(ctx))) return
+
+    const text = controlCommand(ctx.message.text)
+
+    if (text === '/ai' || text === '/settings') {
+      await aiMenu.list(ctx, text === '/settings')
+      return
+    }
+
+    if (text === '/help') {
+      await ctx.reply([...commands, ...aliases.filter((a) => !commands.some((c) => c.command === a.command))]
+        .map((c) => `/${c.command} — ${c.description}`).join('\n'))
+      return
+    }
+    if (text === '/retry') {
+      const id = await inbox.retryLatest(ctx.from.id, ctx.chat.id)
+      if (id) scheduleIntake()
+      await ctx.reply(id ? `Incoming batch ${id} queued for retry.` : 'No failed incoming batch to retry.')
+      return
+    }
+    if (text === '/cancel') {
+      await ctx.reply(await cancelPending())
+      return
+    }
+
+    // Steering & session commands
+    if (text === '/stop') {
+      const running = await runs.running()
+      if (running && running.pid) {
+        try {
+          if (activeChild) terminateJob(activeChild)
+        } catch {}
+        if (activeTypingTimer) {
+          clearInterval(activeTypingTimer)
+          activeTypingTimer = null
+        }
+        await ctx.reply(
+          '🛑 Stop requested for active work. Queued work remains and will run next. /cancel clears it.',
+        )
+      } else {
+        await ctx.reply('No active run in progress.')
+      }
+      return
+    }
+
+    if (text === '/new') {
+      await control.aiState(aiMenu.initial)
+      const next = await control.resetSession()
+      await ctx.reply(
+        `🔄 Started fresh conversation session (<code>${next.sessionId.slice(0, 8)}</code>). Agent files and memory preserved.`,
+        { parse_mode: 'HTML' },
+      )
+      return
+    }
+
+    if (text === '/status') {
+      await ctx.reply(await statusText(), { reply_markup: new InlineKeyboard()
+        .text('Stop active work', 'menu:stop').text('Cancel queue', 'menu:cancel').row()
+        .text('Retry failed incoming message', 'menu:retry') })
+      return
+    }
+
+    if (text === '/menu') {
+      const menuKeyboard = mainKeyboard()
+      await ctx.reply('⚡ <b>Ezenciel Agent Menu</b>\nSelect an action below:', {
+        parse_mode: 'HTML',
+        reply_markup: menuKeyboard,
+      })
+      return
+    }
+
+    // Quoted reply context forwarding
+    let promptText = ctx.message.text
+    if (ctx.message.reply_to_message) {
+      const quoted = ctx.message.reply_to_message
+      const quotedText = ('text' in quoted && quoted.text) || ('caption' in quoted && quoted.caption) || ''
+      const quotedSender = quoted.from?.is_bot ? 'Agent' : 'Owner'
+      if (quotedText) {
+        promptText = `[Quoted message from ${quotedSender} (ID: ${quoted.message_id})]: "${quotedText}"\n\n${promptText}`
+      }
+    }
+
+    collectItem({
+      text: promptText,
+      messageId: ctx.message.message_id,
+      updateId: ctx.update.update_id,
+      chatId: ctx.chat.id,
+      fromId: ctx.from.id,
+    })
+  })
+
+  bot.on('message:photo', async (ctx) => {
+    if (!(await checkOwner(ctx))) return
+    try {
+      const photos = ctx.message.photo
+      const photo = photos[photos.length - 1] // highest resolution
+      const fileInfo = await ctx.api.getFile(photo.file_id)
+      if (!fileInfo.file_path) throw new Error('Telegram attachment path unavailable')
+      const fileUrl = `https://api.telegram.org/file/bot${config.telegramBotToken}/${fileInfo.file_path}`
+      const buffer = await downloadTelegramFile(fileUrl)
+      const fileName = sanitizeFileName(basename(fileInfo.file_path) || 'photo.jpg')
+      const staged = await stageIncomingFile(config.workspace, fileName, buffer)
+      const caption = ctx.message.caption?.trim() || ''
+      const prompt = `[Attached image staged at ${staged.relativePath} (type: ${staged.fileType}, size: ${buffer.length} bytes)]${caption ? `\n\nCaption: ${caption}` : ''}`
+      collectItem({
+        text: prompt,
+        messageId: ctx.message.message_id,
+        updateId: ctx.update.update_id,
+        chatId: ctx.chat.id,
+        fromId: ctx.from.id,
+      })
+    } catch (err) {
+      console.error('Failed to process incoming photo:', safeError(err))
+      await ctx
+        .reply('⚠️ Photo could not be processed. Check the local relay log; /retry retries the saved batch.')
+        .catch(() => {})
+      throw err
+    }
+  })
+
+  bot.on('message:document', async (ctx) => {
+    if (!(await checkOwner(ctx))) return
+    try {
+      const doc = ctx.message.document
+      const fileInfo = await ctx.api.getFile(doc.file_id)
+      if (!fileInfo.file_path) throw new Error('Telegram attachment path unavailable')
+      const fileUrl = `https://api.telegram.org/file/bot${config.telegramBotToken}/${fileInfo.file_path}`
+      const buffer = await downloadTelegramFile(fileUrl)
+      const fileName = sanitizeFileName(doc.file_name || basename(fileInfo.file_path) || 'document.bin')
+      const staged = await stageIncomingFile(config.workspace, fileName, buffer)
+      const caption = ctx.message.caption?.trim() || ''
+      const prompt = `[Attached document staged at ${staged.relativePath} (type: ${staged.fileType}, size: ${buffer.length} bytes)]${caption ? `\n\nCaption: ${caption}` : ''}`
+      collectItem({
+        text: prompt,
+        messageId: ctx.message.message_id,
+        updateId: ctx.update.update_id,
+        chatId: ctx.chat.id,
+        fromId: ctx.from.id,
+      })
+    } catch (err) {
+      console.error('Failed to process incoming document:', safeError(err))
+      await ctx
+        .reply(
+          '⚠️ Document could not be processed. Check the local relay log; /retry retries the saved batch.',
+        )
+        .catch(() => {})
+      throw err
+    }
+  })
+
+  bot.on('message:voice', async (ctx) => {
+    if (!(await checkOwner(ctx))) return
+    try {
+      await bot.api.sendChatAction(ctx.chat.id, 'typing').catch(() => {})
+      const voice = ctx.message.voice
+      const fileInfo = await ctx.api.getFile(voice.file_id)
+      if (!fileInfo.file_path) throw new Error('Telegram attachment path unavailable')
+      const fileUrl = `https://api.telegram.org/file/bot${config.telegramBotToken}/${fileInfo.file_path}`
+      const buffer = await downloadTelegramFile(fileUrl)
+      const transcript = await transcribeAudio(buffer, voice.mime_type || 'audio/ogg', {
+        geminiApiKey: config.geminiApiKey,
+        openaiApiKey: config.openaiApiKey,
+      })
+      const prompt = `[Inbound Voice Note (duration: ${voice.duration}s)]:\n"${transcript}"`
+      collectItem({
+        text: prompt,
+        messageId: ctx.message.message_id,
+        updateId: ctx.update.update_id,
+        chatId: ctx.chat.id,
+        fromId: ctx.from.id,
+      })
+    } catch (err) {
+      console.error('Failed to transcribe incoming voice note:', safeError(err))
+      await ctx
+        .reply(
+          '⚠️ Voice note could not be transcribed. The log identifies the failing request. Use /retry to retry the saved batch.',
+        )
+        .catch(() => {})
+      throw err
+    }
+  })
+
+  bot.on('callback_query:data', async (ctx) => {
+    if (!isOwner(ctx, (await control.status()).owner)) {
+      await ctx.answerCallbackQuery()
+      return
+    }
+    const data = ctx.callbackQuery.data
+    if (data.startsWith('approval:')) {
+      const [, actionId, decision] = data.split(':')
+      if (actionId && (decision === 'approve' || decision === 'deny')) {
+        const request = await approvals.getDecision(actionId)
+        const run = request?.runId ? await runs.get(request.runId) : null
+        if (!run || run.chatId !== ctx.chat?.id || run.telegramUserId !== ctx.from.id) {
+          await ctx.answerCallbackQuery({ text: 'Approval unavailable' })
+          return
+        }
+        const isApproved = decision === 'approve'
+        try {
+          await approvals.recordDecision(
+            actionId,
+            isApproved ? 'approved' : 'denied',
+            ctx.from.id,
+            ctx.update.update_id,
+          )
+        } catch {
+          await ctx.answerCallbackQuery({ text: 'Approval expired or already decided' })
+          return
+        }
+        await ctx.answerCallbackQuery({ text: isApproved ? 'Approved ✅' : 'Denied ❌' }).catch(() => {})
+        const original = ctx.callbackQuery.message?.text || ''
+        const updated = `${escapeHtml(original)}\n\n<b>Decision:</b> ${isApproved ? 'Approved ✅' : 'Denied ❌'}`
+        await ctx.editMessageText(updated, { parse_mode: 'HTML' }).catch(() => {})
+        collectItem({
+          text: JSON.stringify({ event: 'approval_decision', actionId, decision, prompt: request?.prompt }),
+          messageId: ctx.callbackQuery.message?.message_id,
+          updateId: ctx.update.update_id,
+          chatId: run.chatId,
+          fromId: ctx.from.id,
+        })
+        console.info('Approval decision recorded', { actionId, decision: isApproved ? 'approved' : 'denied' })
+      }
+    } else if (await aiMenu.handle(ctx)) {
+      return
+    } else if (data.startsWith('menu:')) {
+      const action = data.slice(5)
+      if (action === 'ai' || action === 'settings') {
+        await ctx.answerCallbackQuery()
+        await aiMenu.list(ctx, action === 'settings')
+      } else if (action === 'retry') {
+        await ctx.answerCallbackQuery()
+        const id = await inbox.retryLatest(ctx.from.id, ctx.chat!.id)
+        if (id) scheduleIntake()
+        await ctx.reply(id ? `Incoming batch ${id} queued for retry.` : 'No failed incoming batch to retry.')
+      } else if (action === 'new') {
+        await control.aiState(aiMenu.initial)
+        const next = await control.resetSession()
+        await ctx.answerCallbackQuery({ text: 'New session started' })
+        await ctx.reply(
+          `🔄 Started fresh conversation session (<code>${next.sessionId.slice(0, 8)}</code>).`,
+          { parse_mode: 'HTML' },
+        )
+      } else if (action === 'status') {
+        await ctx.answerCallbackQuery()
+        await ctx.reply(await statusText())
+      } else if (action === 'cancel') {
+        await ctx.answerCallbackQuery()
+        await ctx.reply(await cancelPending())
+      } else if (action === 'stop') {
+        const running = await runs.running()
+        if (running && running.pid) {
+          if (activeChild) terminateJob(activeChild)
+          await ctx.answerCallbackQuery({ text: 'Run stopped' })
+          await ctx.reply(
+            '🛑 Stop requested for active work. Queued work remains and will run next. /cancel clears it.',
+          )
+        } else {
+          await ctx.answerCallbackQuery({ text: 'No run active' })
+          await ctx.reply('No active run in progress.')
+        }
+      }
+    }
+  })
+
+  bot.catch((error) => {
+    console.error('Telegram update failure', safeError(error.error))
+    // Do not let polling acknowledge an update whose journal write failed.
+    throw error
+  })
+
+  const stop = async () => {
+    shuttingDown = true
+    if (intakeTimer) clearTimeout(intakeTimer)
+    if (sourceTimer) clearInterval(sourceTimer)
+    if (activeChild) terminateJob(activeChild)
+    if (activeTypingTimer) clearInterval(activeTypingTimer)
+    if (sourceWork) await sourceWork.catch(() => {})
+    if (bot.isRunning()) await bot.stop()
+  }
+
+  const start = async () => {
+    await initializeWorkspace(config.workspace)
+    sourceTimer = setInterval(() => {
+      void drainSources().catch(error => console.error('Event-source drain failed', safeError(error)))
+    }, 1000)
+    const drainTimer = setInterval(() => {
+      void drainOutbox().catch((error) => console.error('Outbox drain failed', error.message))
+    }, 250)
+    drainTimer.unref()
+    try {
+      console.log(`ezenciel-agents listening with workspace ${config.workspace}`)
+      console.log(`Authority control state: ${config.controlDir}`)
+      console.log(`CLI executor: ${config.executorCli}`)
+      await aiMenu.refresh()
+
+      // Reconcile stale runs and start any queued run on boot
+      const currentRunning = await runs.running()
+      if (!currentRunning) {
+        const pendingRun = await runs.nextQueued()
+        if (pendingRun) {
+          console.info('Processing queued run on startup:', pendingRun.id)
+          void startJob(pendingRun)
+        }
+      }
+
+      await bot.api.deleteWebhook({ drop_pending_updates: false })
+      await bot.api.setMyCommands(commands)
+      await bot.api.setMyCommands(commands, { scope: { type: 'all_private_chats' } })
+      await bot.init()
+      scheduleIntake()
+      await bot.start({
+        drop_pending_updates: false,
+        onStart: (botInfo) => console.log(`✓ Bot @${botInfo.username} polling for messages...`),
+      })
+    } finally {
+      clearInterval(drainTimer)
+      if (sourceTimer) clearInterval(sourceTimer)
+    }
+  }
+  return { bot, start, stop, drainOutbox, drainInbox, drainSources }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const relay = createRelay(loadConfig())
+  for (const signal of ['SIGINT', 'SIGTERM'] as const)
+    process.once(signal, () => {
+      void relay.stop()
+    })
+  await relay.start()
+}