@dotsetlabs/dotclaw 1.1.0

package/dist/index.js

@@ -0,0 +1,2072 @@
+import dotenv from 'dotenv';
+import { Telegraf } from 'telegraf';
+import { execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { DATA_DIR, MAIN_GROUP_FOLDER, GROUPS_DIR, IPC_POLL_INTERVAL, TIMEZONE, CONTAINER_MODE, WARM_START_ENABLED, ENV_PATH } from './config.js';
+// Load .env from the canonical location (~/.dotclaw/.env)
+dotenv.config({ path: ENV_PATH });
+import { initDatabase, storeMessage, getMessagesSinceCursor, getChatState, updateChatState, createTask, updateTask, deleteTask, getTaskById, getAllGroupSessions, setGroupSession, deleteGroupSession, pauseTasksForGroup, linkMessageToTrace, getTraceIdForMessage, recordUserFeedback } from './db.js';
+import { startSchedulerLoop } from './task-scheduler.js';
+import { loadJson, saveJson, isSafeGroupFolder } from './utils.js';
+import { writeTrace } from './trace-writer.js';
+import { formatTelegramMessage, TELEGRAM_PARSE_MODE } from './telegram-format.js';
+import { initMemoryStore, getMemoryStats, upsertMemoryItems, searchMemories, listMemories, forgetMemories, cleanupExpiredMemories } from './memory-store.js';
+import { startEmbeddingWorker } from './memory-embeddings.js';
+import { createProgressNotifier, DEFAULT_PROGRESS_MESSAGES } from './progress.js';
+import { parseAdminCommand } from './admin-commands.js';
+import { loadModelRegistry, saveModelRegistry } from './model-registry.js';
+import { startMetricsServer, recordMessage, recordError } from './metrics.js';
+import { startMaintenanceLoop } from './maintenance.js';
+import { warmGroupContainer, startDaemonHealthCheckLoop } from './container-runner.js';
+import { loadRuntimeConfig } from './runtime-config.js';
+import { createTraceBase, executeAgentRun, recordAgentTelemetry, AgentExecutionError } from './agent-execution.js';
+import { logger } from './logger.js';
+import { startDashboard, setTelegramConnected, setLastMessageTime, setMessageQueueDepth } from './dashboard.js';
+import { humanizeError } from './error-messages.js';
+const runtime = loadRuntimeConfig();
+function buildTriggerRegex(pattern) {
+    if (!pattern)
+        return null;
+    try {
+        return new RegExp(pattern, 'i');
+    }
+    catch {
+        return null;
+    }
+}
+function isPreemptedError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return message.toLowerCase().includes('preempt');
+}
+function buildAvailableGroupsSnapshot() {
+    return Object.entries(registeredGroups).map(([jid, info]) => ({
+        jid,
+        name: info.name,
+        lastActivity: getChatState(jid)?.last_agent_timestamp || info.added_at,
+        isRegistered: true
+    }));
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isMemoryScope(value) {
+    return value === 'user' || value === 'group' || value === 'global';
+}
+function isMemoryType(value) {
+    return value === 'identity'
+        || value === 'preference'
+        || value === 'fact'
+        || value === 'relationship'
+        || value === 'project'
+        || value === 'task'
+        || value === 'note'
+        || value === 'archive';
+}
+function isMemoryKind(value) {
+    return value === 'semantic'
+        || value === 'episodic'
+        || value === 'procedural'
+        || value === 'preference';
+}
+function clampInputMessage(content, maxChars) {
+    if (!content)
+        return '';
+    if (!Number.isFinite(maxChars) || maxChars <= 0)
+        return content;
+    if (content.length <= maxChars)
+        return content;
+    return `${content.slice(0, maxChars)}\n\n[Message truncated for length]`;
+}
+function coerceMemoryItems(input) {
+    if (!Array.isArray(input))
+        return [];
+    const items = [];
+    for (const raw of input) {
+        if (!isRecord(raw))
+            continue;
+        const scope = raw.scope;
+        const type = raw.type;
+        const kind = raw.kind;
+        const content = raw.content;
+        if (!isMemoryScope(scope) || !isMemoryType(type) || typeof content !== 'string' || !content.trim()) {
+            continue;
+        }
+        items.push({
+            scope,
+            type,
+            kind: isMemoryKind(kind) ? kind : undefined,
+            conflict_key: typeof raw.conflict_key === 'string' ? raw.conflict_key : undefined,
+            content: content.trim(),
+            subject_id: typeof raw.subject_id === 'string' ? raw.subject_id : null,
+            importance: typeof raw.importance === 'number' ? raw.importance : undefined,
+            confidence: typeof raw.confidence === 'number' ? raw.confidence : undefined,
+            tags: Array.isArray(raw.tags) ? raw.tags.filter((tag) => typeof tag === 'string') : undefined,
+            ttl_days: typeof raw.ttl_days === 'number' ? raw.ttl_days : undefined,
+            source: typeof raw.source === 'string' ? raw.source : undefined,
+            metadata: isRecord(raw.metadata) ? raw.metadata : undefined
+        });
+    }
+    return items;
+}
+// Rate limiting configuration
+const RATE_LIMIT_MAX_MESSAGES = 20; // Max messages per user per window
+const RATE_LIMIT_WINDOW_MS = 60_000; // 1 minute window
+const rateLimiter = new Map();
+function checkRateLimit(userId) {
+    const now = Date.now();
+    const entry = rateLimiter.get(userId);
+    if (!entry || now > entry.resetAt) {
+        // New window
+        rateLimiter.set(userId, { count: 1, resetAt: now + RATE_LIMIT_WINDOW_MS });
+        return { allowed: true };
+    }
+    if (entry.count >= RATE_LIMIT_MAX_MESSAGES) {
+        // Rate limited
+        return { allowed: false, retryAfterMs: entry.resetAt - now };
+    }
+    // Increment counter
+    entry.count += 1;
+    return { allowed: true };
+}
+function cleanupRateLimiter() {
+    const now = Date.now();
+    for (const [key, entry] of rateLimiter.entries()) {
+        if (now > entry.resetAt) {
+            rateLimiter.delete(key);
+        }
+    }
+}
+// Clean up expired rate limit entries periodically
+setInterval(cleanupRateLimiter, 60_000);
+const TELEGRAM_HANDLER_TIMEOUT_MS = runtime.host.telegram.handlerTimeoutMs;
+const TELEGRAM_SEND_RETRIES = runtime.host.telegram.sendRetries;
+const TELEGRAM_SEND_RETRY_DELAY_MS = runtime.host.telegram.sendRetryDelayMs;
+const TELEGRAM_STREAM_MODE = runtime.host.telegram.streamMode.toLowerCase();
+const TELEGRAM_STREAM_MIN_INTERVAL_MS = runtime.host.telegram.streamMinIntervalMs;
+const TELEGRAM_STREAM_MIN_CHARS = runtime.host.telegram.streamMinChars;
+const MEMORY_RECALL_MAX_RESULTS = runtime.host.memory.recall.maxResults;
+const MEMORY_RECALL_MAX_TOKENS = runtime.host.memory.recall.maxTokens;
+const INPUT_MESSAGE_MAX_CHARS = runtime.host.telegram.inputMessageMaxChars;
+const PROGRESS_ENABLED = runtime.host.progress.enabled;
+const PROGRESS_INITIAL_MS = runtime.host.progress.initialMs;
+const PROGRESS_INTERVAL_MS = runtime.host.progress.intervalMs;
+const PROGRESS_MAX_UPDATES = runtime.host.progress.maxUpdates;
+const PROGRESS_MESSAGES = runtime.host.progress.messages.length > 0
+    ? runtime.host.progress.messages
+    : DEFAULT_PROGRESS_MESSAGES;
+const HEARTBEAT_ENABLED = runtime.host.heartbeat.enabled;
+const HEARTBEAT_INTERVAL_MS = runtime.host.heartbeat.intervalMs;
+const HEARTBEAT_GROUP_FOLDER = (runtime.host.heartbeat.groupFolder || MAIN_GROUP_FOLDER).trim() || MAIN_GROUP_FOLDER;
+const BACKGROUND_TASKS_ENABLED = runtime.host.backgroundTasks.enabled;
+const BACKGROUND_TRIGGER_REGEX = runtime.host.backgroundTasks.triggerRegex;
+const BACKGROUND_TRIGGER = buildTriggerRegex(BACKGROUND_TRIGGER_REGEX);
+const BACKGROUND_ACK_MESSAGE = runtime.host.backgroundTasks.ackMessage;
+const BACKGROUND_TOOL_DENY = runtime.host.backgroundTasks.toolDeny;
+const PREEMPT_ON_NEW_MESSAGE = runtime.host.backgroundTasks.preemptOnNewMessage;
+function shouldRunInBackground(content) {
+    if (!BACKGROUND_TASKS_ENABLED)
+        return false;
+    const trimmed = content.trim();
+    if (!trimmed)
+        return false;
+    if (BACKGROUND_TRIGGER && BACKGROUND_TRIGGER.test(trimmed))
+        return true;
+    return false;
+}
+// Initialize Telegram bot with extended timeout for long-running agent tasks
+const telegrafBot = new Telegraf(process.env.TELEGRAM_BOT_TOKEN, {
+    handlerTimeout: TELEGRAM_HANDLER_TIMEOUT_MS
+});
+telegrafBot.catch((err, ctx) => {
+    logger.error({ err, chatId: ctx?.chat?.id }, 'Unhandled Telegraf error');
+});
+let sessions = {};
+let registeredGroups = {};
+const TELEGRAM_MAX_MESSAGE_LENGTH = 4000;
+const TELEGRAM_SEND_DELAY_MS = 250;
+const messageQueues = new Map();
+const inFlightRuns = new Map();
+const draftSessions = new Map();
+function parseTelegramStreamMode(value) {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'draft' || normalized === 'edit' || normalized === 'auto' || normalized === 'off') {
+        return normalized;
+    }
+    return 'off';
+}
+function getDraftKey(chatId, draftId) {
+    return `${chatId}:${draftId}`;
+}
+function createDraftId() {
+    const max = 2_147_483_647;
+    return Math.floor(Math.random() * (max - 1)) + 1;
+}
+async function setTyping(chatId) {
+    try {
+        await telegrafBot.telegram.sendChatAction(chatId, 'typing');
+    }
+    catch (err) {
+        logger.debug({ chatId, err }, 'Failed to set typing indicator');
+    }
+}
+function canUseTelegramDraft(msg) {
+    return msg.chatType === 'private' && Number.isFinite(msg.messageThreadId);
+}
+function registerDraftSession(msg) {
+    const mode = parseTelegramStreamMode(TELEGRAM_STREAM_MODE);
+    if (mode === 'off')
+        return null;
+    if (msg.chatType !== 'private')
+        return null;
+    const supportsDraft = canUseTelegramDraft(msg);
+    const resolvedMode = mode === 'auto'
+        ? (supportsDraft ? 'draft' : 'edit')
+        : (mode === 'draft' ? (supportsDraft ? 'draft' : 'edit') : (mode === 'edit' ? 'edit' : null));
+    if (!resolvedMode)
+        return null;
+    const draftId = createDraftId();
+    draftSessions.set(getDraftKey(msg.chatId, draftId), {
+        mode: resolvedMode,
+        messageThreadId: msg.messageThreadId,
+        started: false,
+        lastSentAt: 0,
+        lastChunk: undefined
+    });
+    return { mode: resolvedMode, draftId };
+}
+function clearDraftSession(chatId, draftId) {
+    draftSessions.delete(getDraftKey(chatId, draftId));
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+function isBotMentioned(text, entities, botUsername, botId) {
+    if (!entities || entities.length === 0)
+        return false;
+    const normalized = botUsername ? botUsername.toLowerCase() : '';
+    for (const entity of entities) {
+        const segment = text.slice(entity.offset, entity.offset + entity.length);
+        if (entity.type === 'mention') {
+            if (segment.toLowerCase() === `@${normalized}`)
+                return true;
+        }
+        if (entity.type === 'text_mention' && botId && entity.user?.id === botId)
+            return true;
+        if (entity.type === 'bot_command') {
+            if (segment.toLowerCase().includes(`@${normalized}`))
+                return true;
+        }
+    }
+    return false;
+}
+function isBotReplied(message, botId) {
+    if (!message?.reply_to_message?.from?.id || !botId)
+        return false;
+    return message.reply_to_message.from.id === botId;
+}
+function getTelegramErrorCode(err) {
+    const anyErr = err;
+    if (typeof anyErr?.code === 'number')
+        return anyErr.code;
+    if (typeof anyErr?.response?.error_code === 'number')
+        return anyErr.response.error_code;
+    return null;
+}
+function getTelegramRetryAfterMs(err) {
+    const anyErr = err;
+    const retryAfter = anyErr?.parameters?.retry_after ?? anyErr?.response?.parameters?.retry_after;
+    if (typeof retryAfter === 'number' && Number.isFinite(retryAfter))
+        return retryAfter * 1000;
+    if (typeof retryAfter === 'string') {
+        const parsed = Number.parseInt(retryAfter, 10);
+        if (Number.isFinite(parsed))
+            return parsed * 1000;
+    }
+    return null;
+}
+function isRetryableTelegramError(err) {
+    const code = getTelegramErrorCode(err);
+    if (code === 429)
+        return true;
+    if (code && code >= 500 && code < 600)
+        return true;
+    const anyErr = err;
+    if (!anyErr?.code)
+        return false;
+    return ['ETIMEDOUT', 'ECONNRESET', 'ECONNREFUSED', 'EAI_AGAIN', 'ENOTFOUND'].includes(anyErr.code);
+}
+function loadState() {
+    sessions = {};
+    const loadedGroups = loadJson(path.join(DATA_DIR, 'registered_groups.json'), {});
+    const sanitizedGroups = {};
+    const usedFolders = new Set();
+    let invalidCount = 0;
+    let duplicateCount = 0;
+    for (const [chatId, group] of Object.entries(loadedGroups)) {
+        if (!group || typeof group !== 'object') {
+            logger.warn({ chatId }, 'Skipping registered group with invalid entry');
+            invalidCount += 1;
+            continue;
+        }
+        if (typeof group.name !== 'string' || group.name.trim() === '') {
+            logger.warn({ chatId }, 'Skipping registered group with invalid name');
+            invalidCount += 1;
+            continue;
+        }
+        if (!isSafeGroupFolder(group.folder, GROUPS_DIR)) {
+            logger.warn({ chatId, folder: group.folder }, 'Skipping registered group with invalid folder');
+            invalidCount += 1;
+            continue;
+        }
+        if (usedFolders.has(group.folder)) {
+            logger.warn({ chatId, folder: group.folder }, 'Skipping registered group with duplicate folder');
+            duplicateCount += 1;
+            continue;
+        }
+        usedFolders.add(group.folder);
+        sanitizedGroups[chatId] = group;
+    }
+    registeredGroups = sanitizedGroups;
+    if (invalidCount > 0 || duplicateCount > 0) {
+        logger.error({ invalidCount, duplicateCount }, 'Registered groups contained invalid or duplicate folders');
+    }
+    logger.info({ groupCount: Object.keys(registeredGroups).length }, 'State loaded');
+    const finalSessions = getAllGroupSessions();
+    sessions = finalSessions.reduce((acc, row) => {
+        acc[row.group_folder] = row.session_id;
+        return acc;
+    }, {});
+}
+function registerGroup(chatId, group) {
+    if (!isSafeGroupFolder(group.folder, GROUPS_DIR)) {
+        logger.warn({ chatId, folder: group.folder }, 'Refusing to register group with invalid folder');
+        return;
+    }
+    const folderCollision = Object.values(registeredGroups).some(g => g.folder === group.folder);
+    if (folderCollision) {
+        logger.warn({ chatId, folder: group.folder }, 'Refusing to register group with duplicate folder');
+        return;
+    }
+    registeredGroups[chatId] = group;
+    saveJson(path.join(DATA_DIR, 'registered_groups.json'), registeredGroups);
+    // Create group folder
+    const groupDir = path.join(GROUPS_DIR, group.folder);
+    fs.mkdirSync(path.join(groupDir, 'logs'), { recursive: true });
+    logger.info({ chatId, name: group.name, folder: group.folder }, 'Group registered');
+    if (CONTAINER_MODE === 'daemon' && WARM_START_ENABLED) {
+        try {
+            warmGroupContainer(group, group.folder === MAIN_GROUP_FOLDER);
+            logger.info({ group: group.folder }, 'Warmed daemon container for new group');
+        }
+        catch (err) {
+            logger.warn({ group: group.folder, err }, 'Failed to warm container for new group');
+        }
+    }
+}
+function listRegisteredGroups() {
+    return Object.entries(registeredGroups).map(([chatId, group]) => ({
+        chat_id: chatId,
+        name: group.name,
+        folder: group.folder,
+        trigger: group.trigger,
+        added_at: group.added_at
+    }));
+}
+function resolveGroupIdentifier(identifier) {
+    const trimmed = identifier.trim();
+    if (!trimmed)
+        return null;
+    const normalized = trimmed.toLowerCase();
+    for (const [chatId, group] of Object.entries(registeredGroups)) {
+        if (chatId === trimmed)
+            return chatId;
+        if (group.name.toLowerCase() === normalized)
+            return chatId;
+        if (group.folder.toLowerCase() === normalized)
+            return chatId;
+    }
+    return null;
+}
+function unregisterGroup(identifier) {
+    const chatId = resolveGroupIdentifier(identifier);
+    if (!chatId) {
+        return { ok: false, error: 'Group not found' };
+    }
+    const group = registeredGroups[chatId];
+    if (!group) {
+        return { ok: false, error: 'Group not found' };
+    }
+    if (group.folder === MAIN_GROUP_FOLDER) {
+        return { ok: false, error: 'Cannot remove main group' };
+    }
+    delete registeredGroups[chatId];
+    saveJson(path.join(DATA_DIR, 'registered_groups.json'), registeredGroups);
+    delete sessions[group.folder];
+    deleteGroupSession(group.folder);
+    pauseTasksForGroup(group.folder);
+    logger.info({ chatId, name: group.name, folder: group.folder }, 'Group removed');
+    return { ok: true, group: { ...group, chat_id: chatId } };
+}
+function splitPlainText(text, maxLength) {
+    if (text.length <= maxLength)
+        return [text];
+    const chunks = [];
+    for (let i = 0; i < text.length; i += maxLength) {
+        chunks.push(text.slice(i, i + maxLength));
+    }
+    return chunks;
+}
+async function sendMessage(chatId, text, options) {
+    const parseMode = options?.parseMode === undefined ? TELEGRAM_PARSE_MODE : options.parseMode;
+    const chunks = parseMode
+        ? formatTelegramMessage(text, TELEGRAM_MAX_MESSAGE_LENGTH)
+        : splitPlainText(text, TELEGRAM_MAX_MESSAGE_LENGTH);
+    let firstMessageId;
+    const sendChunk = async (chunk) => {
+        for (let attempt = 1; attempt <= TELEGRAM_SEND_RETRIES; attempt += 1) {
+            try {
+                const payload = {};
+                if (parseMode)
+                    payload.parse_mode = parseMode;
+                if (options?.messageThreadId)
+                    payload.message_thread_id = options.messageThreadId;
+                const sent = await telegrafBot.telegram.sendMessage(chatId, chunk, payload);
+                if (!firstMessageId) {
+                    firstMessageId = String(sent.message_id);
+                }
+                return true;
+            }
+            catch (err) {
+                const retryAfterMs = getTelegramRetryAfterMs(err);
+                const retryable = isRetryableTelegramError(err);
+                if (!retryable || attempt === TELEGRAM_SEND_RETRIES) {
+                    logger.error({ chatId, attempt, err }, 'Failed to send Telegram message chunk');
+                    return false;
+                }
+                const delayMs = retryAfterMs ?? (TELEGRAM_SEND_RETRY_DELAY_MS * attempt);
+                logger.warn({ chatId, attempt, delayMs }, 'Telegram send failed; retrying');
+                await sleep(delayMs);
+            }
+        }
+        return false;
+    };
+    try {
+        // Telegram bots send messages as themselves, no prefix needed
+        for (let i = 0; i < chunks.length; i += 1) {
+            const ok = await sendChunk(chunks[i]);
+            if (!ok)
+                return { success: false };
+            if (i < chunks.length - 1) {
+                await sleep(TELEGRAM_SEND_DELAY_MS);
+            }
+        }
+        logger.info({ chatId, length: text.length }, 'Message sent');
+        return { success: true, messageId: firstMessageId };
+    }
+    catch (err) {
+        logger.error({ chatId, err }, 'Failed to send message');
+        return { success: false };
+    }
+}
+async function sendDraftUpdate(chatId, draftId, text) {
+    const key = getDraftKey(chatId, draftId);
+    const session = draftSessions.get(key);
+    if (!session)
+        return;
+    if (!text || !text.trim())
+        return;
+    const now = Date.now();
+    if (now - session.lastSentAt < TELEGRAM_STREAM_MIN_INTERVAL_MS)
+        return;
+    session.lastSentAt = now;
+    const chunk = splitPlainText(text, TELEGRAM_MAX_MESSAGE_LENGTH)[0] ?? '';
+    if (!chunk)
+        return;
+    if (session.lastChunk === chunk)
+        return;
+    session.lastChunk = chunk;
+    if (session.mode === 'draft') {
+        try {
+            await telegrafBot.telegram
+                .callApi('sendMessageDraft', {
+                chat_id: chatId,
+                draft_id: draftId,
+                text: chunk,
+                message_thread_id: session.messageThreadId
+            });
+            session.started = true;
+            return;
+        }
+        catch (err) {
+            logger.warn({ chatId, err }, 'sendMessageDraft failed; switching to edit fallback');
+            session.mode = 'edit';
+        }
+    }
+    if (!session.messageId) {
+        try {
+            const payload = {};
+            if (session.messageThreadId)
+                payload.message_thread_id = session.messageThreadId;
+            const sent = await telegrafBot.telegram.sendMessage(chatId, chunk, payload);
+            session.messageId = sent.message_id;
+            session.started = true;
+            return;
+        }
+        catch (err) {
+            logger.warn({ chatId, err }, 'Failed to send draft placeholder');
+            return;
+        }
+    }
+    try {
+        await telegrafBot.telegram.editMessageText(chatId, session.messageId, undefined, chunk);
+        session.started = true;
+    }
+    catch (err) {
+        logger.debug({ chatId, err }, 'Failed to edit draft message');
+    }
+}
+function isTelegramNotModifiedError(err) {
+    const description = err?.response?.description;
+    if (typeof description === 'string' && description.toLowerCase().includes('message is not modified')) {
+        return true;
+    }
+    return false;
+}
+async function finalizeStreamedMessage(msg, draftId, text) {
+    if (!draftId) {
+        await sendMessage(msg.chatId, text, { messageThreadId: msg.messageThreadId });
+        return;
+    }
+    const key = getDraftKey(msg.chatId, draftId);
+    const session = draftSessions.get(key);
+    if (!session) {
+        await sendMessage(msg.chatId, text, { messageThreadId: msg.messageThreadId });
+        return;
+    }
+    if (session.mode === 'edit' && session.messageId) {
+        const chunks = formatTelegramMessage(text, TELEGRAM_MAX_MESSAGE_LENGTH);
+        if (chunks.length === 0) {
+            clearDraftSession(msg.chatId, draftId);
+            return;
+        }
+        const firstChunk = chunks[0];
+        const firstChunkMatches = session.lastChunk === firstChunk;
+        try {
+            if (!firstChunkMatches) {
+                await telegrafBot.telegram.editMessageText(msg.chatId, session.messageId, undefined, firstChunk, { parse_mode: TELEGRAM_PARSE_MODE });
+            }
+            for (let i = firstChunkMatches ? 1 : 1; i < chunks.length; i += 1) {
+                await sendMessage(msg.chatId, chunks[i], { messageThreadId: msg.messageThreadId });
+            }
+            clearDraftSession(msg.chatId, draftId);
+            return;
+        }
+        catch (err) {
+            if (isTelegramNotModifiedError(err)) {
+                for (let i = firstChunkMatches ? 1 : 1; i < chunks.length; i += 1) {
+                    await sendMessage(msg.chatId, chunks[i], { messageThreadId: msg.messageThreadId });
+                }
+                clearDraftSession(msg.chatId, draftId);
+                return;
+            }
+            logger.warn({ chatId: msg.chatId, err }, 'Failed to finalize streamed edit; sending new message');
+        }
+    }
+    await sendMessage(msg.chatId, text, { messageThreadId: msg.messageThreadId });
+    clearDraftSession(msg.chatId, draftId);
+}
+function enqueueMessage(msg) {
+    if (PREEMPT_ON_NEW_MESSAGE) {
+        const inFlight = inFlightRuns.get(msg.chatId);
+        if (inFlight && !inFlight.controller.signal.aborted) {
+            logger.warn({ chatId: msg.chatId }, 'Preempting in-flight agent run');
+            inFlight.controller.abort();
+        }
+    }
+    const existing = messageQueues.get(msg.chatId);
+    if (existing) {
+        existing.pendingMessage = msg;
+        if (!existing.inFlight) {
+            void drainQueue(msg.chatId);
+        }
+        setMessageQueueDepth(messageQueues.size);
+        return;
+    }
+    messageQueues.set(msg.chatId, { inFlight: false, pendingMessage: msg });
+    setMessageQueueDepth(messageQueues.size);
+    void drainQueue(msg.chatId);
+}
+async function drainQueue(chatId) {
+    const state = messageQueues.get(chatId);
+    if (!state || state.inFlight)
+        return;
+    state.inFlight = true;
+    try {
+        while (state.pendingMessage) {
+            const next = state.pendingMessage;
+            state.pendingMessage = undefined;
+            await processMessage(next);
+        }
+    }
+    catch (err) {
+        logger.error({ chatId, err }, 'Error draining message queue');
+    }
+    finally {
+        state.inFlight = false;
+        if (state.pendingMessage) {
+            void drainQueue(chatId);
+        }
+        else {
+            messageQueues.delete(chatId);
+        }
+        setMessageQueueDepth(messageQueues.size);
+    }
+}
+async function processMessage(msg) {
+    const group = registeredGroups[msg.chatId];
+    if (!group) {
+        logger.debug({ chatId: msg.chatId }, 'Message from unregistered Telegram chat');
+        return false;
+    }
+    recordMessage('telegram');
+    setLastMessageTime(msg.timestamp);
+    // Get all messages since last agent interaction so the session has full context
+    const chatState = getChatState(msg.chatId);
+    let missedMessages = getMessagesSinceCursor(msg.chatId, chatState?.last_agent_timestamp || null, chatState?.last_agent_message_id || null);
+    if (missedMessages.length === 0) {
+        logger.warn({ chatId: msg.chatId }, 'No missed messages found; falling back to current message');
+        missedMessages = [{
+                id: msg.messageId,
+                chat_jid: msg.chatId,
+                sender: msg.senderId,
+                sender_name: msg.senderName,
+                content: msg.content,
+                timestamp: msg.timestamp
+            }];
+    }
+    const lines = missedMessages.map(m => {
+        // Escape XML special characters in content
+        const escapeXml = (s) => s
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;');
+        const safeContent = clampInputMessage(m.content, INPUT_MESSAGE_MAX_CHARS);
+        return `<message sender="${escapeXml(m.sender_name)}" sender_id="${escapeXml(m.sender)}" time="${m.timestamp}">${escapeXml(safeContent)}</message>`;
+    });
+    const prompt = `<messages>
+${lines.join('\n')}
+</messages>`;
+    const lastMessage = missedMessages[missedMessages.length - 1];
+    if (lastMessage && shouldRunInBackground(lastMessage.content)) {
+        logger.info({ group: group.name }, 'Routing message to background task');
+        updateChatState(msg.chatId, lastMessage.timestamp, lastMessage.id);
+        await sendMessage(msg.chatId, BACKGROUND_ACK_MESSAGE, { messageThreadId: msg.messageThreadId });
+        void runBackgroundTask({
+            msg,
+            group,
+            prompt,
+            missedMessages
+        });
+        return true;
+    }
+    const traceBase = createTraceBase({
+        chatId: msg.chatId,
+        groupFolder: group.folder,
+        userId: msg.senderId,
+        inputText: prompt,
+        source: 'dotclaw'
+    });
+    logger.info({ group: group.name, messageCount: missedMessages.length }, 'Processing message');
+    await setTyping(msg.chatId);
+    const recallQuery = missedMessages.map(entry => entry.content).join('\n');
+    const draftSession = registerDraftSession(msg);
+    const draftId = draftSession?.draftId ?? null;
+    const streamingEnabled = Boolean(draftSession && draftId);
+    let output = null;
+    let context = null;
+    let errorMessage = null;
+    const progressNotifier = createProgressNotifier({
+        enabled: PROGRESS_ENABLED && !streamingEnabled,
+        initialDelayMs: PROGRESS_INITIAL_MS,
+        intervalMs: PROGRESS_INTERVAL_MS,
+        maxUpdates: PROGRESS_MAX_UPDATES,
+        messages: PROGRESS_MESSAGES,
+        send: async (text) => { await sendMessage(msg.chatId, text, { messageThreadId: msg.messageThreadId }); },
+        onError: (err) => logger.debug({ chatId: msg.chatId, err }, 'Failed to send progress update')
+    });
+    progressNotifier.start();
+    try {
+        const execution = await executeAgentRun({
+            group,
+            prompt,
+            chatJid: msg.chatId,
+            userId: msg.senderId,
+            userName: msg.senderName,
+            recallQuery: recallQuery || msg.content,
+            recallMaxResults: MEMORY_RECALL_MAX_RESULTS,
+            recallMaxTokens: MEMORY_RECALL_MAX_TOKENS,
+            sessionId: sessions[group.folder],
+            onSessionUpdate: (sessionId) => { sessions[group.folder] = sessionId; },
+            streaming: streamingEnabled && draftId
+                ? {
+                    enabled: true,
+                    draftId,
+                    minIntervalMs: TELEGRAM_STREAM_MIN_INTERVAL_MS,
+                    minChars: TELEGRAM_STREAM_MIN_CHARS
+                }
+                : undefined,
+            availableGroups: buildAvailableGroupsSnapshot()
+        });
+        output = execution.output;
+        context = execution.context;
+        if (output.status === 'error') {
+            errorMessage = output.error || 'Unknown error';
+        }
+    }
+    catch (err) {
+        if (err instanceof AgentExecutionError) {
+            context = err.context;
+            errorMessage = err.message;
+        }
+        else {
+            errorMessage = err instanceof Error ? err.message : String(err);
+        }
+        logger.error({ group: group.name, err }, 'Agent error');
+    }
+    finally {
+        progressNotifier.stop();
+    }
+    if (!output) {
+        const message = errorMessage || 'No output from agent';
+        if (context) {
+            recordAgentTelemetry({
+                traceBase,
+                output: null,
+                context,
+                metricsSource: 'telegram',
+                toolAuditSource: 'message',
+                errorMessage: message,
+                errorType: 'agent'
+            });
+        }
+        else {
+            recordError('agent');
+            writeTrace({
+                trace_id: traceBase.trace_id,
+                timestamp: traceBase.timestamp,
+                created_at: traceBase.created_at,
+                chat_id: traceBase.chat_id,
+                group_folder: traceBase.group_folder,
+                user_id: traceBase.user_id,
+                input_text: traceBase.input_text,
+                output_text: null,
+                model_id: 'unknown',
+                memory_recall: [],
+                error_code: message,
+                source: traceBase.source
+            });
+        }
+        const userMessage = humanizeError(errorMessage || 'Unknown error');
+        await sendMessage(msg.chatId, userMessage, { messageThreadId: msg.messageThreadId });
+        if (draftId) {
+            clearDraftSession(msg.chatId, draftId);
+        }
+        return false;
+    }
+    if (output.status === 'error') {
+        if (context) {
+            recordAgentTelemetry({
+                traceBase,
+                output,
+                context,
+                metricsSource: 'telegram',
+                toolAuditSource: 'message',
+                errorMessage: errorMessage || output.error || 'Unknown error',
+                errorType: 'agent'
+            });
+        }
+        logger.error({ group: group.name, error: output.error }, 'Container agent error');
+        const userMessage = humanizeError(errorMessage || output.error || 'Unknown error');
+        await sendMessage(msg.chatId, userMessage, { messageThreadId: msg.messageThreadId });
+        if (draftId) {
+            clearDraftSession(msg.chatId, draftId);
+        }
+        return false;
+    }
+    if (lastMessage) {
+        updateChatState(msg.chatId, lastMessage.timestamp, lastMessage.id);
+    }
+    if (output.result && output.result.trim()) {
+        let sentMessageId;
+        if (streamingEnabled && draftId) {
+            await finalizeStreamedMessage(msg, draftId, output.result);
+            // Note: streaming doesn't easily give us the message ID
+        }
+        else {
+            const sendResult = await sendMessage(msg.chatId, output.result, { messageThreadId: msg.messageThreadId });
+            sentMessageId = sendResult.messageId;
+        }
+        // Link the sent message to the trace for feedback tracking
+        if (sentMessageId) {
+            try {
+                linkMessageToTrace(sentMessageId, msg.chatId, traceBase.trace_id);
+            }
+            catch {
+                // Don't fail if linking fails
+            }
+        }
+    }
+    else if (output.tool_calls && output.tool_calls.length > 0) {
+        await sendMessage(msg.chatId, 'I hit my tool-call step limit before I could finish. If you want me to keep going, please narrow the scope or ask for a specific subtask.', { messageThreadId: msg.messageThreadId });
+        if (draftId) {
+            clearDraftSession(msg.chatId, draftId);
+        }
+    }
+    else {
+        logger.warn({ chatId: msg.chatId }, 'Agent returned empty/whitespace response');
+        if (draftId) {
+            clearDraftSession(msg.chatId, draftId);
+        }
+    }
+    if (context) {
+        recordAgentTelemetry({
+            traceBase,
+            output,
+            context,
+            metricsSource: 'telegram',
+            toolAuditSource: 'message'
+        });
+    }
+    return true;
+}
+async function runBackgroundTask(params) {
+    const { msg, group, prompt, missedMessages } = params;
+    const traceBase = createTraceBase({
+        chatId: msg.chatId,
+        groupFolder: group.folder,
+        userId: msg.senderId,
+        inputText: prompt,
+        source: 'dotclaw-background'
+    });
+    const recallQuery = missedMessages.map(entry => entry.content).join('\n');
+    const runId = `bg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const abortController = new AbortController();
+    if (PREEMPT_ON_NEW_MESSAGE) {
+        inFlightRuns.set(msg.chatId, { controller: abortController, runId });
+    }
+    let output = null;
+    let context = null;
+    let errorMessage = null;
+    try {
+        const execution = await executeAgentRun({
+            group,
+            prompt,
+            chatJid: msg.chatId,
+            userId: msg.senderId,
+            userName: msg.senderName,
+            recallQuery: recallQuery || msg.content,
+            recallMaxResults: MEMORY_RECALL_MAX_RESULTS,
+            recallMaxTokens: MEMORY_RECALL_MAX_TOKENS,
+            toolDeny: BACKGROUND_TOOL_DENY,
+            sessionId: runId,
+            persistSession: false,
+            useGroupLock: false,
+            abortSignal: abortController.signal,
+            isBackgroundTask: true,
+            availableGroups: buildAvailableGroupsSnapshot()
+        });
+        output = execution.output;
+        context = execution.context;
+        if (output.status === 'error') {
+            errorMessage = output.error || 'Unknown error';
+        }
+    }
+    catch (err) {
+        if (err instanceof AgentExecutionError) {
+            context = err.context;
+            errorMessage = err.message;
+        }
+        else {
+            errorMessage = err instanceof Error ? err.message : String(err);
+        }
+        if (abortController.signal.aborted || isPreemptedError(err)) {
+            if (context) {
+                recordAgentTelemetry({
+                    traceBase,
+                    output,
+                    context,
+                    metricsSource: 'telegram',
+                    toolAuditSource: 'background',
+                    errorMessage: 'preempted'
+                });
+            }
+            else {
+                writeTrace({
+                    trace_id: traceBase.trace_id,
+                    timestamp: traceBase.timestamp,
+                    created_at: traceBase.created_at,
+                    chat_id: traceBase.chat_id,
+                    group_folder: traceBase.group_folder,
+                    user_id: traceBase.user_id,
+                    input_text: traceBase.input_text,
+                    output_text: null,
+                    model_id: 'unknown',
+                    memory_recall: [],
+                    error_code: 'preempted',
+                    source: traceBase.source
+                });
+            }
+            logger.warn({ chatId: msg.chatId }, 'Background run preempted; skipping response');
+            return;
+        }
+        logger.error({ group: group.name, err }, 'Background agent error');
+    }
+    finally {
+        if (PREEMPT_ON_NEW_MESSAGE) {
+            const current = inFlightRuns.get(msg.chatId);
+            if (current?.runId === runId) {
+                inFlightRuns.delete(msg.chatId);
+            }
+        }
+    }
+    if (!output) {
+        if (context) {
+            recordAgentTelemetry({
+                traceBase,
+                output: null,
+                context,
+                metricsSource: 'telegram',
+                toolAuditSource: 'background',
+                errorMessage: errorMessage || 'No output from background agent',
+                errorType: 'agent'
+            });
+        }
+        else {
+            recordError('agent');
+            writeTrace({
+                trace_id: traceBase.trace_id,
+                timestamp: traceBase.timestamp,
+                created_at: traceBase.created_at,
+                chat_id: traceBase.chat_id,
+                group_folder: traceBase.group_folder,
+                user_id: traceBase.user_id,
+                input_text: traceBase.input_text,
+                output_text: null,
+                model_id: 'unknown',
+                memory_recall: [],
+                error_code: errorMessage || 'No output from background agent',
+                source: traceBase.source
+            });
+        }
+        return;
+    }
+    if (output.status === 'error') {
+        if (abortController.signal.aborted || isPreemptedError(output.error)) {
+            if (context) {
+                recordAgentTelemetry({
+                    traceBase,
+                    output,
+                    context,
+                    metricsSource: 'telegram',
+                    toolAuditSource: 'background',
+                    errorMessage: 'preempted'
+                });
+            }
+            logger.warn({ chatId: msg.chatId }, 'Background run preempted; skipping response');
+            return;
+        }
+        if (context) {
+            recordAgentTelemetry({
+                traceBase,
+                output,
+                context,
+                metricsSource: 'telegram',
+                toolAuditSource: 'background',
+                errorMessage: errorMessage || output.error || 'Unknown error',
+                errorType: 'agent'
+            });
+        }
+        logger.error({ group: group.name, error: output.error }, 'Background agent error');
+        const userMessage = humanizeError(errorMessage || output.error || 'Unknown error');
+        await sendMessage(msg.chatId, userMessage, { messageThreadId: msg.messageThreadId });
+        return;
+    }
+    if (output.result && output.result.trim()) {
+        const sendResult = await sendMessage(msg.chatId, output.result, { messageThreadId: msg.messageThreadId });
+        // Link the sent message to the trace for feedback tracking
+        if (sendResult.messageId) {
+            try {
+                linkMessageToTrace(sendResult.messageId, msg.chatId, traceBase.trace_id);
+            }
+            catch {
+                // Don't fail if linking fails
+            }
+        }
+    }
+    else if (output.tool_calls && output.tool_calls.length > 0) {
+        await sendMessage(msg.chatId, 'I hit my tool-call step limit before I could finish. If you want me to keep going, please narrow the scope or ask for a specific subtask.', { messageThreadId: msg.messageThreadId });
+    }
+    else {
+        await sendMessage(msg.chatId, "I wasn't able to generate a response this time. Please try again or rephrase your request.", { messageThreadId: msg.messageThreadId });
+    }
+    if (context) {
+        recordAgentTelemetry({
+            traceBase,
+            output,
+            context,
+            metricsSource: 'telegram',
+            toolAuditSource: 'background'
+        });
+    }
+}
+function startIpcWatcher() {
+    const ipcBaseDir = path.join(DATA_DIR, 'ipc');
+    fs.mkdirSync(ipcBaseDir, { recursive: true });
+    let processing = false;
+    let scheduled = false;
+    let pollingTimer = null;
+    const processIpcFiles = async () => {
+        if (processing)
+            return;
+        processing = true;
+        // Scan all group IPC directories (identity determined by directory)
+        let groupFolders;
+        try {
+            groupFolders = fs.readdirSync(ipcBaseDir).filter(f => {
+                const stat = fs.statSync(path.join(ipcBaseDir, f));
+                return stat.isDirectory() && f !== 'errors';
+            });
+        }
+        catch (err) {
+            logger.error({ err }, 'Error reading IPC base directory');
+            processing = false;
+            return;
+        }
+        for (const sourceGroup of groupFolders) {
+            const isMain = sourceGroup === MAIN_GROUP_FOLDER;
+            const messagesDir = path.join(ipcBaseDir, sourceGroup, 'messages');
+            const tasksDir = path.join(ipcBaseDir, sourceGroup, 'tasks');
+            const requestsDir = path.join(ipcBaseDir, sourceGroup, 'requests');
+            const responsesDir = path.join(ipcBaseDir, sourceGroup, 'responses');
+            // Process messages from this group's IPC directory
+            try {
+                if (fs.existsSync(messagesDir)) {
+                    const messageFiles = fs.readdirSync(messagesDir).filter(f => f.endsWith('.json'));
+                    for (const file of messageFiles) {
+                        const filePath = path.join(messagesDir, file);
+                        try {
+                            const data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+                            if ((data.type === 'message' || data.type === 'message_draft') && data.chatJid && data.text) {
+                                // Authorization: verify this group can send to this chatJid
+                                const targetGroup = registeredGroups[data.chatJid];
+                                if (isMain || (targetGroup && targetGroup.folder === sourceGroup)) {
+                                    if (data.type === 'message_draft') {
+                                        const draftId = Number.isFinite(data.draftId) ? Number(data.draftId) : NaN;
+                                        if (!Number.isFinite(draftId)) {
+                                            logger.warn({ chatJid: data.chatJid, sourceGroup }, 'IPC draft missing draftId');
+                                        }
+                                        else {
+                                            await sendDraftUpdate(data.chatJid, draftId, data.text);
+                                        }
+                                    }
+                                    else {
+                                        await sendMessage(data.chatJid, data.text);
+                                        logger.info({ chatJid: data.chatJid, sourceGroup }, 'IPC message sent');
+                                    }
+                                }
+                                else {
+                                    logger.warn({ chatJid: data.chatJid, sourceGroup }, 'Unauthorized IPC message attempt blocked');
+                                }
+                            }
+                            fs.unlinkSync(filePath);
+                        }
+                        catch (err) {
+                            logger.error({ file, sourceGroup, err }, 'Error processing IPC message');
+                            const errorDir = path.join(ipcBaseDir, 'errors');
+                            fs.mkdirSync(errorDir, { recursive: true });
+                            fs.renameSync(filePath, path.join(errorDir, `${sourceGroup}-${file}`));
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                logger.error({ err, sourceGroup }, 'Error reading IPC messages directory');
+            }
+            // Process tasks from this group's IPC directory
+            try {
+                if (fs.existsSync(tasksDir)) {
+                    const taskFiles = fs.readdirSync(tasksDir).filter(f => f.endsWith('.json'));
+                    for (const file of taskFiles) {
+                        const filePath = path.join(tasksDir, file);
+                        try {
+                            const data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+                            // Pass source group identity to processTaskIpc for authorization
+                            await processTaskIpc(data, sourceGroup, isMain);
+                            fs.unlinkSync(filePath);
+                        }
+                        catch (err) {
+                            logger.error({ file, sourceGroup, err }, 'Error processing IPC task');
+                            const errorDir = path.join(ipcBaseDir, 'errors');
+                            fs.mkdirSync(errorDir, { recursive: true });
+                            fs.renameSync(filePath, path.join(errorDir, `${sourceGroup}-${file}`));
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                logger.error({ err, sourceGroup }, 'Error reading IPC tasks directory');
+            }
+            // Process request/response IPC for synchronous operations (memory, etc.)
+            try {
+                if (fs.existsSync(requestsDir)) {
+                    fs.mkdirSync(responsesDir, { recursive: true });
+                    const requestFiles = fs.readdirSync(requestsDir).filter(f => f.endsWith('.json'));
+                    for (const file of requestFiles) {
+                        const filePath = path.join(requestsDir, file);
+                        try {
+                            const data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+                            const response = await processRequestIpc(data, sourceGroup, isMain);
+                            if (response?.id) {
+                                const responsePath = path.join(responsesDir, `${response.id}.json`);
+                                fs.writeFileSync(responsePath, JSON.stringify(response, null, 2));
+                            }
+                            fs.unlinkSync(filePath);
+                        }
+                        catch (err) {
+                            logger.error({ file, sourceGroup, err }, 'Error processing IPC request');
+                            const errorDir = path.join(ipcBaseDir, 'errors');
+                            fs.mkdirSync(errorDir, { recursive: true });
+                            fs.renameSync(filePath, path.join(errorDir, `${sourceGroup}-${file}`));
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                logger.error({ err, sourceGroup }, 'Error reading IPC requests directory');
+            }
+        }
+        processing = false;
+    };
+    const scheduleProcess = () => {
+        if (scheduled)
+            return;
+        scheduled = true;
+        setTimeout(async () => {
+            scheduled = false;
+            await processIpcFiles();
+        }, 100);
+    };
+    let watcherActive = false;
+    let watcher = null;
+    try {
+        watcher = fs.watch(ipcBaseDir, { recursive: true }, () => {
+            scheduleProcess();
+        });
+        watcher.on('error', (err) => {
+            logger.warn({ err }, 'IPC watcher error; falling back to polling');
+            watcher?.close();
+            if (!pollingTimer) {
+                const poll = () => {
+                    scheduleProcess();
+                    pollingTimer = setTimeout(poll, IPC_POLL_INTERVAL);
+                };
+                poll();
+            }
+        });
+        watcherActive = true;
+    }
+    catch (err) {
+        logger.warn({ err }, 'IPC watch unsupported; falling back to polling');
+    }
+    if (!watcherActive) {
+        const poll = () => {
+            scheduleProcess();
+            pollingTimer = setTimeout(poll, IPC_POLL_INTERVAL);
+        };
+        poll();
+    }
+    else {
+        scheduleProcess();
+    }
+    if (pollingTimer) {
+        logger.info('IPC watcher started (polling)');
+    }
+    else {
+        logger.info('IPC watcher started (fs.watch)');
+    }
+}
+async function runHeartbeatOnce() {
+    const entry = Object.entries(registeredGroups).find(([, group]) => group.folder === HEARTBEAT_GROUP_FOLDER);
+    if (!entry) {
+        logger.warn({ group: HEARTBEAT_GROUP_FOLDER }, 'Heartbeat group not registered');
+        return;
+    }
+    const [chatId, group] = entry;
+    const prompt = [
+        '[HEARTBEAT]',
+        'You are running automatically. Review scheduled tasks, pending reminders, and long-running work.',
+        'If you need to communicate, use mcp__dotclaw__send_message. Otherwise, take no user-visible action.'
+    ].join('\n');
+    const traceBase = createTraceBase({
+        chatId,
+        groupFolder: group.folder,
+        userId: null,
+        inputText: prompt,
+        source: 'dotclaw-heartbeat'
+    });
+    let output = null;
+    let context = null;
+    let errorMessage = null;
+    const recallMaxResults = Math.max(4, MEMORY_RECALL_MAX_RESULTS - 2);
+    const recallMaxTokens = Math.max(600, MEMORY_RECALL_MAX_TOKENS - 200);
+    try {
+        const execution = await executeAgentRun({
+            group,
+            prompt,
+            chatJid: chatId,
+            userId: null,
+            recallQuery: prompt,
+            recallMaxResults,
+            recallMaxTokens,
+            sessionId: sessions[group.folder],
+            onSessionUpdate: (sessionId) => { sessions[group.folder] = sessionId; },
+            isScheduledTask: true,
+            availableGroups: buildAvailableGroupsSnapshot()
+        });
+        output = execution.output;
+        context = execution.context;
+        if (output.status === 'error') {
+            errorMessage = output.error || 'Unknown error';
+        }
+    }
+    catch (err) {
+        if (err instanceof AgentExecutionError) {
+            context = err.context;
+            errorMessage = err.message;
+        }
+        else {
+            errorMessage = err instanceof Error ? err.message : String(err);
+        }
+        logger.error({ err }, 'Heartbeat run failed');
+    }
+    if (context) {
+        recordAgentTelemetry({
+            traceBase,
+            output,
+            context,
+            toolAuditSource: 'heartbeat',
+            errorMessage: errorMessage ?? undefined
+        });
+    }
+    else if (errorMessage) {
+        writeTrace({
+            trace_id: traceBase.trace_id,
+            timestamp: traceBase.timestamp,
+            created_at: traceBase.created_at,
+            chat_id: traceBase.chat_id,
+            group_folder: traceBase.group_folder,
+            user_id: traceBase.user_id,
+            input_text: traceBase.input_text,
+            output_text: null,
+            model_id: 'unknown',
+            memory_recall: [],
+            error_code: errorMessage,
+            source: traceBase.source
+        });
+    }
+}
+function startHeartbeatLoop() {
+    if (!HEARTBEAT_ENABLED)
+        return;
+    const loop = async () => {
+        try {
+            await runHeartbeatOnce();
+        }
+        catch (err) {
+            logger.error({ err }, 'Heartbeat run failed');
+        }
+        setTimeout(loop, HEARTBEAT_INTERVAL_MS);
+    };
+    loop();
+}
+async function processTaskIpc(data, sourceGroup, isMain) {
+    const { CronExpressionParser } = await import('cron-parser');
+    switch (data.type) {
+        case 'schedule_task':
+            if (data.prompt && data.schedule_type && data.schedule_value && data.groupFolder) {
+                // Authorization: non-main groups can only schedule for themselves
+                const targetGroup = data.groupFolder;
+                if (!isMain && targetGroup !== sourceGroup) {
+                    logger.warn({ sourceGroup, targetGroup }, 'Unauthorized schedule_task attempt blocked');
+                    break;
+                }
+                // Resolve the correct chat ID for the target group (don't trust IPC payload)
+                const targetChatId = Object.entries(registeredGroups).find(([, group]) => group.folder === targetGroup)?.[0];
+                if (!targetChatId) {
+                    logger.warn({ targetGroup }, 'Cannot schedule task: target group not registered');
+                    break;
+                }
+                const scheduleType = data.schedule_type;
+                let nextRun = null;
+                if (scheduleType === 'cron') {
+                    try {
+                        const interval = CronExpressionParser.parse(data.schedule_value, { tz: TIMEZONE });
+                        nextRun = interval.next().toISOString();
+                    }
+                    catch {
+                        logger.warn({ scheduleValue: data.schedule_value }, 'Invalid cron expression');
+                        break;
+                    }
+                }
+                else if (scheduleType === 'interval') {
+                    const ms = parseInt(data.schedule_value, 10);
+                    if (isNaN(ms) || ms <= 0) {
+                        logger.warn({ scheduleValue: data.schedule_value }, 'Invalid interval');
+                        break;
+                    }
+                    nextRun = new Date(Date.now() + ms).toISOString();
+                }
+                else if (scheduleType === 'once') {
+                    const scheduled = new Date(data.schedule_value);
+                    if (isNaN(scheduled.getTime())) {
+                        logger.warn({ scheduleValue: data.schedule_value }, 'Invalid timestamp');
+                        break;
+                    }
+                    nextRun = scheduled.toISOString();
+                }
+                const taskId = `task-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+                const contextMode = (data.context_mode === 'group' || data.context_mode === 'isolated')
+                    ? data.context_mode
+                    : 'isolated';
+                createTask({
+                    id: taskId,
+                    group_folder: targetGroup,
+                    chat_jid: targetChatId,
+                    prompt: data.prompt,
+                    schedule_type: scheduleType,
+                    schedule_value: data.schedule_value,
+                    context_mode: contextMode,
+                    next_run: nextRun,
+                    status: 'active',
+                    created_at: new Date().toISOString()
+                });
+                logger.info({ taskId, sourceGroup, targetGroup, contextMode }, 'Task created via IPC');
+            }
+            break;
+        case 'pause_task':
+            if (data.taskId) {
+                const task = getTaskById(data.taskId);
+                if (task && (isMain || task.group_folder === sourceGroup)) {
+                    updateTask(data.taskId, { status: 'paused' });
+                    logger.info({ taskId: data.taskId, sourceGroup }, 'Task paused via IPC');
+                }
+                else {
+                    logger.warn({ taskId: data.taskId, sourceGroup }, 'Unauthorized task pause attempt');
+                }
+            }
+            break;
+        case 'resume_task':
+            if (data.taskId) {
+                const task = getTaskById(data.taskId);
+                if (task && (isMain || task.group_folder === sourceGroup)) {
+                    updateTask(data.taskId, { status: 'active' });
+                    logger.info({ taskId: data.taskId, sourceGroup }, 'Task resumed via IPC');
+                }
+                else {
+                    logger.warn({ taskId: data.taskId, sourceGroup }, 'Unauthorized task resume attempt');
+                }
+            }
+            break;
+        case 'cancel_task':
+            if (data.taskId) {
+                const task = getTaskById(data.taskId);
+                if (task && (isMain || task.group_folder === sourceGroup)) {
+                    deleteTask(data.taskId);
+                    logger.info({ taskId: data.taskId, sourceGroup }, 'Task cancelled via IPC');
+                }
+                else {
+                    logger.warn({ taskId: data.taskId, sourceGroup }, 'Unauthorized task cancel attempt');
+                }
+            }
+            break;
+        case 'update_task':
+            if (data.taskId) {
+                const task = getTaskById(data.taskId);
+                if (!task || (!isMain && task.group_folder !== sourceGroup)) {
+                    logger.warn({ taskId: data.taskId, sourceGroup }, 'Unauthorized task update attempt');
+                    break;
+                }
+                const updates = {};
+                if (typeof data.prompt === 'string')
+                    updates.prompt = data.prompt;
+                if (typeof data.context_mode === 'string')
+                    updates.context_mode = data.context_mode;
+                if (typeof data.status === 'string')
+                    updates.status = data.status;
+                if (typeof data.state_json === 'string')
+                    updates.state_json = data.state_json;
+                if (typeof data.schedule_type === 'string' && typeof data.schedule_value === 'string') {
+                    updates.schedule_type = data.schedule_type;
+                    updates.schedule_value = data.schedule_value;
+                    let nextRun = null;
+                    if (updates.schedule_type === 'cron') {
+                        try {
+                            const interval = CronExpressionParser.parse(updates.schedule_value, { tz: TIMEZONE });
+                            nextRun = interval.next().toISOString();
+                        }
+                        catch {
+                            logger.warn({ scheduleValue: updates.schedule_value }, 'Invalid cron expression for update_task');
+                        }
+                    }
+                    else if (updates.schedule_type === 'interval') {
+                        const ms = parseInt(updates.schedule_value, 10);
+                        if (!isNaN(ms) && ms > 0) {
+                            nextRun = new Date(Date.now() + ms).toISOString();
+                        }
+                    }
+                    else if (updates.schedule_type === 'once') {
+                        const scheduled = new Date(updates.schedule_value);
+                        if (!isNaN(scheduled.getTime())) {
+                            nextRun = scheduled.toISOString();
+                        }
+                    }
+                    if (nextRun) {
+                        updates.next_run = nextRun;
+                    }
+                }
+                updateTask(data.taskId, updates);
+                logger.info({ taskId: data.taskId, sourceGroup }, 'Task updated via IPC');
+            }
+            break;
+        case 'register_group':
+            // Only main group can register new groups
+            if (!isMain) {
+                logger.warn({ sourceGroup }, 'Unauthorized register_group attempt blocked');
+                break;
+            }
+            if (data.jid && data.name && data.folder) {
+                registerGroup(data.jid, {
+                    name: data.name,
+                    folder: data.folder,
+                    trigger: data.trigger,
+                    added_at: new Date().toISOString(),
+                    containerConfig: data.containerConfig
+                });
+            }
+            else {
+                logger.warn({ data }, 'Invalid register_group request - missing required fields');
+            }
+            break;
+        case 'remove_group':
+            if (!isMain) {
+                logger.warn({ sourceGroup }, 'Unauthorized remove_group attempt blocked');
+                break;
+            }
+            if (!data.identifier || typeof data.identifier !== 'string') {
+                logger.warn({ data }, 'Invalid remove_group request - missing identifier');
+                break;
+            }
+            {
+                const result = unregisterGroup(data.identifier);
+                if (!result.ok) {
+                    logger.warn({ identifier: data.identifier, error: result.error }, 'Failed to remove group');
+                }
+            }
+            break;
+        case 'set_model':
+            if (!isMain) {
+                logger.warn({ sourceGroup }, 'Unauthorized set_model attempt blocked');
+                break;
+            }
+            if (!data.model || typeof data.model !== 'string') {
+                logger.warn({ data }, 'Invalid set_model request - missing model');
+                break;
+            }
+            {
+                const defaultModel = runtime.host.defaultModel;
+                const config = loadModelRegistry(defaultModel);
+                const nextModel = data.model.trim();
+                if (config.allowlist && config.allowlist.length > 0 && !config.allowlist.includes(nextModel)) {
+                    logger.warn({ model: nextModel }, 'Model not in allowlist; refusing set_model');
+                    break;
+                }
+                const scope = typeof data.scope === 'string' ? data.scope : 'global';
+                const targetId = typeof data.target_id === 'string' ? data.target_id : undefined;
+                if (scope === 'user' && !targetId) {
+                    logger.warn({ data }, 'set_model missing target_id for user scope');
+                    break;
+                }
+                if (scope === 'group' && !targetId) {
+                    logger.warn({ data }, 'set_model missing target_id for group scope');
+                    break;
+                }
+                const nextConfig = { ...config };
+                if (scope === 'global') {
+                    nextConfig.model = nextModel;
+                }
+                else if (scope === 'group') {
+                    nextConfig.per_group = nextConfig.per_group || {};
+                    nextConfig.per_group[targetId] = { model: nextModel };
+                }
+                else if (scope === 'user') {
+                    nextConfig.per_user = nextConfig.per_user || {};
+                    nextConfig.per_user[targetId] = { model: nextModel };
+                }
+                nextConfig.updated_at = new Date().toISOString();
+                saveModelRegistry(nextConfig);
+                logger.info({ model: nextModel, scope, targetId }, 'Model updated via IPC');
+            }
+            break;
+        default:
+            logger.warn({ type: data.type }, 'Unknown IPC task type');
+    }
+}
+async function processRequestIpc(data, sourceGroup, isMain) {
+    const requestId = typeof data.id === 'string' ? data.id : undefined;
+    const payload = data.payload || {};
+    const resolveGroupFolder = () => {
+        const target = typeof payload.target_group === 'string' ? payload.target_group : null;
+        if (target && isMain)
+            return target;
+        return sourceGroup;
+    };
+    try {
+        switch (data.type) {
+            case 'memory_upsert': {
+                const items = coerceMemoryItems(payload.items);
+                const groupFolder = resolveGroupFolder();
+                const source = typeof payload.source === 'string' ? payload.source : 'agent';
+                const results = upsertMemoryItems(groupFolder, items, source);
+                return { id: requestId, ok: true, result: { count: results.length } };
+            }
+            case 'memory_forget': {
+                const groupFolder = resolveGroupFolder();
+                const ids = Array.isArray(payload.ids) ? payload.ids : undefined;
+                const content = typeof payload.content === 'string' ? payload.content : undefined;
+                const scope = isMemoryScope(payload.scope) ? payload.scope : undefined;
+                const userId = typeof payload.userId === 'string' ? payload.userId : undefined;
+                const count = forgetMemories({
+                    groupFolder,
+                    ids,
+                    content,
+                    scope,
+                    userId
+                });
+                return { id: requestId, ok: true, result: { count } };
+            }
+            case 'memory_list': {
+                const groupFolder = resolveGroupFolder();
+                const scope = isMemoryScope(payload.scope) ? payload.scope : undefined;
+                const type = isMemoryType(payload.type) ? payload.type : undefined;
+                const userId = typeof payload.userId === 'string' ? payload.userId : undefined;
+                const limit = typeof payload.limit === 'number' ? payload.limit : undefined;
+                const items = listMemories({
+                    groupFolder,
+                    scope,
+                    type,
+                    userId,
+                    limit
+                });
+                return { id: requestId, ok: true, result: { items } };
+            }
+            case 'memory_search': {
+                const groupFolder = resolveGroupFolder();
+                const query = typeof payload.query === 'string' ? payload.query : '';
+                const userId = typeof payload.userId === 'string' ? payload.userId : undefined;
+                const limit = typeof payload.limit === 'number' ? payload.limit : undefined;
+                const results = searchMemories({
+                    groupFolder,
+                    userId,
+                    query,
+                    limit
+                });
+                return { id: requestId, ok: true, result: { items: results } };
+            }
+            case 'memory_stats': {
+                const groupFolder = resolveGroupFolder();
+                const userId = typeof payload.userId === 'string' ? payload.userId : undefined;
+                const stats = getMemoryStats({ groupFolder, userId });
+                return { id: requestId, ok: true, result: { stats } };
+            }
+            case 'list_groups': {
+                if (!isMain) {
+                    return { id: requestId, ok: false, error: 'Only the main group can list groups.' };
+                }
+                const groups = listRegisteredGroups();
+                return { id: requestId, ok: true, result: { groups } };
+            }
+            default:
+                return { id: requestId, ok: false, error: `Unknown request type: ${data.type}` };
+        }
+    }
+    catch (err) {
+        return { id: requestId, ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+function formatGroups(groups) {
+    if (groups.length === 0)
+        return 'No registered groups.';
+    const lines = groups.map(group => {
+        const trigger = group.trigger ? ` (trigger: ${group.trigger})` : '';
+        return `- ${group.name} [${group.folder}] chat=${group.chat_id}${trigger}`;
+    });
+    return ['Registered groups:', ...lines].join('\n');
+}
+function applyModelOverride(params) {
+    const defaultModel = runtime.host.defaultModel;
+    const config = loadModelRegistry(defaultModel);
+    const nextModel = params.model.trim();
+    if (config.allowlist && config.allowlist.length > 0 && !config.allowlist.includes(nextModel)) {
+        return { ok: false, error: 'Model not in allowlist' };
+    }
+    const scope = params.scope || 'global';
+    const targetId = params.targetId;
+    if (scope === 'user' && !targetId) {
+        return { ok: false, error: 'Missing target_id for user scope' };
+    }
+    if (scope === 'group' && !targetId) {
+        return { ok: false, error: 'Missing target_id for group scope' };
+    }
+    const nextConfig = { ...config };
+    if (scope === 'global') {
+        nextConfig.model = nextModel;
+    }
+    else if (scope === 'group') {
+        nextConfig.per_group = nextConfig.per_group || {};
+        nextConfig.per_group[targetId] = { model: nextModel };
+    }
+    else if (scope === 'user') {
+        nextConfig.per_user = nextConfig.per_user || {};
+        nextConfig.per_user[targetId] = { model: nextModel };
+    }
+    nextConfig.updated_at = new Date().toISOString();
+    saveModelRegistry(nextConfig);
+    return { ok: true };
+}
+async function handleAdminCommand(params) {
+    const parsed = parseAdminCommand(params.content, params.botUsername);
+    if (!parsed)
+        return false;
+    const reply = (text) => sendMessage(params.chatId, text, { messageThreadId: params.messageThreadId });
+    const group = registeredGroups[params.chatId];
+    if (!group) {
+        await reply('This chat is not registered with DotClaw.');
+        return true;
+    }
+    const isMain = group.folder === MAIN_GROUP_FOLDER;
+    const command = parsed.command;
+    const args = parsed.args;
+    const requireMain = (name) => {
+        if (isMain)
+            return false;
+        reply(`${name} is only available in the main group.`).catch(() => undefined);
+        return true;
+    };
+    if (command === 'help') {
+        await reply([
+            'DotClaw admin commands:',
+            '- `/dotclaw help`',
+            '- `/dotclaw groups` (main only)',
+            '- `/dotclaw add-group <chat_id> <name> [folder]` (main only)',
+            '- `/dotclaw remove-group <chat_id|name|folder>` (main only)',
+            '- `/dotclaw set-model <model> [global|group|user] [target_id]` (main only)',
+            '- `/dotclaw remember <fact>` (main only)',
+            '- `/dotclaw style <concise|balanced|detailed>`',
+            '- `/dotclaw tools <conservative|balanced|proactive>`',
+            '- `/dotclaw caution <low|balanced|high>`',
+            '- `/dotclaw memory <strict|balanced|loose>`'
+        ].join('\n'));
+        return true;
+    }
+    if (command === 'groups') {
+        if (requireMain('Listing groups'))
+            return true;
+        await reply(formatGroups(listRegisteredGroups()));
+        return true;
+    }
+    if (command === 'add-group') {
+        if (requireMain('Adding groups'))
+            return true;
+        if (args.length < 1) {
+            await reply('Usage: /dotclaw add-group <chat_id> <name> [folder]');
+            return true;
+        }
+        const jid = args[0];
+        if (registeredGroups[jid]) {
+            await reply('That chat id is already registered.');
+            return true;
+        }
+        const name = args[1] || `group-${jid}`;
+        const folder = args[2] || name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+        if (!isSafeGroupFolder(folder, GROUPS_DIR)) {
+            await reply('Invalid folder name. Use lowercase letters, numbers, and dashes only.');
+            return true;
+        }
+        registerGroup(jid, {
+            name,
+            folder: folder || `group-${jid}`,
+            added_at: new Date().toISOString()
+        });
+        await reply(`Registered group "${name}" with folder "${folder}".`);
+        return true;
+    }
+    if (command === 'remove-group') {
+        if (requireMain('Removing groups'))
+            return true;
+        if (args.length < 1) {
+            await reply('Usage: /dotclaw remove-group <chat_id|name|folder>');
+            return true;
+        }
+        const result = unregisterGroup(args.join(' '));
+        if (!result.ok) {
+            await reply(`Failed to remove group: ${result.error || 'unknown error'}`);
+            return true;
+        }
+        await reply(`Removed group "${result.group?.name}" (${result.group?.folder}).`);
+        return true;
+    }
+    if (command === 'set-model') {
+        if (requireMain('Setting models'))
+            return true;
+        if (args.length < 1) {
+            await reply('Usage: /dotclaw set-model <model> [global|group|user] [target_id]');
+            return true;
+        }
+        const model = args[0];
+        const scopeCandidate = (args[1] || '').toLowerCase();
+        const scope = (scopeCandidate === 'global' || scopeCandidate === 'group' || scopeCandidate === 'user')
+            ? scopeCandidate
+            : 'global';
+        const targetId = args[2] || (scope === 'group' ? group.folder : scope === 'user' ? params.senderId : undefined);
+        const result = applyModelOverride({ model, scope, targetId });
+        if (!result.ok) {
+            await reply(`Failed to set model: ${result.error || 'unknown error'}`);
+            return true;
+        }
+        await reply(`Model set to ${model} (${scope}${targetId ? `:${targetId}` : ''}).`);
+        return true;
+    }
+    if (command === 'remember') {
+        if (requireMain('Remembering facts'))
+            return true;
+        const fact = args.join(' ').trim();
+        if (!fact) {
+            await reply('Usage: /dotclaw remember <fact>');
+            return true;
+        }
+        const items = [{
+                scope: 'global',
+                type: 'fact',
+                content: fact,
+                importance: 0.7,
+                confidence: 0.8,
+                tags: ['manual']
+            }];
+        upsertMemoryItems('global', items, 'admin-command');
+        await reply('Saved to global memory.');
+        return true;
+    }
+    if (command === 'style') {
+        const style = (args[0] || '').toLowerCase();
+        if (!['concise', 'balanced', 'detailed'].includes(style)) {
+            await reply('Usage: /dotclaw style <concise|balanced|detailed>');
+            return true;
+        }
+        const items = [{
+                scope: 'user',
+                subject_id: params.senderId,
+                type: 'preference',
+                conflict_key: 'response_style',
+                content: `Prefers ${style} responses.`,
+                importance: 0.7,
+                confidence: 0.85,
+                tags: [`response_style:${style}`],
+                metadata: { response_style: style }
+            }];
+        upsertMemoryItems(group.folder, items, 'admin-command');
+        await reply(`Response style set to ${style}.`);
+        return true;
+    }
+    if (command === 'tools') {
+        const level = (args[0] || '').toLowerCase();
+        const bias = level === 'proactive' ? 0.7 : level === 'balanced' ? 0.5 : level === 'conservative' ? 0.3 : null;
+        if (bias === null) {
+            await reply('Usage: /dotclaw tools <conservative|balanced|proactive>');
+            return true;
+        }
+        const items = [{
+                scope: 'user',
+                subject_id: params.senderId,
+                type: 'preference',
+                conflict_key: 'tool_calling_bias',
+                content: `Prefers ${level} tool usage.`,
+                importance: 0.65,
+                confidence: 0.8,
+                tags: [`tool_calling_bias:${bias}`],
+                metadata: { tool_calling_bias: bias, bias }
+            }];
+        upsertMemoryItems(group.folder, items, 'admin-command');
+        await reply(`Tool usage bias set to ${level}.`);
+        return true;
+    }
+    if (command === 'caution') {
+        const level = (args[0] || '').toLowerCase();
+        const bias = level === 'high' ? 0.7 : level === 'balanced' ? 0.5 : level === 'low' ? 0.35 : null;
+        if (bias === null) {
+            await reply('Usage: /dotclaw caution <low|balanced|high>');
+            return true;
+        }
+        const items = [{
+                scope: 'user',
+                subject_id: params.senderId,
+                type: 'preference',
+                conflict_key: 'caution_bias',
+                content: `Prefers ${level} caution in responses.`,
+                importance: 0.65,
+                confidence: 0.8,
+                tags: [`caution_bias:${bias}`],
+                metadata: { caution_bias: bias, bias }
+            }];
+        upsertMemoryItems(group.folder, items, 'admin-command');
+        await reply(`Caution bias set to ${level}.`);
+        return true;
+    }
+    if (command === 'memory') {
+        const level = (args[0] || '').toLowerCase();
+        const threshold = level === 'strict' ? 0.7 : level === 'balanced' ? 0.55 : level === 'loose' ? 0.45 : null;
+        if (threshold === null) {
+            await reply('Usage: /dotclaw memory <strict|balanced|loose>');
+            return true;
+        }
+        const items = [{
+                scope: 'user',
+                subject_id: params.senderId,
+                type: 'preference',
+                conflict_key: 'memory_importance_threshold',
+                content: `Prefers memory strictness ${level}.`,
+                importance: 0.6,
+                confidence: 0.8,
+                tags: [`memory_importance_threshold:${threshold}`],
+                metadata: { memory_importance_threshold: threshold, threshold }
+            }];
+        upsertMemoryItems(group.folder, items, 'admin-command');
+        await reply(`Memory strictness set to ${level}.`);
+        return true;
+    }
+    await reply('Unknown command. Use `/dotclaw help` for options.');
+    return true;
+}
+function setupTelegramHandlers() {
+    // Handle message reactions (👍/👎 for feedback)
+    telegrafBot.on('message_reaction', async (ctx) => {
+        try {
+            const update = ctx.update;
+            const reaction = update.message_reaction;
+            if (!reaction)
+                return;
+            const emoji = reaction.new_reaction?.[0]?.emoji;
+            if (!emoji || (emoji !== '👍' && emoji !== '👎'))
+                return;
+            const chatId = String(reaction.chat.id);
+            const messageId = String(reaction.message_id);
+            const userId = reaction.user?.id ? String(reaction.user.id) : undefined;
+            // Look up the trace ID for this message
+            const traceId = getTraceIdForMessage(messageId, chatId);
+            if (!traceId) {
+                logger.debug({ chatId, messageId }, 'No trace found for reacted message');
+                return;
+            }
+            // Record the feedback
+            const feedbackType = emoji === '👍' ? 'positive' : 'negative';
+            recordUserFeedback({
+                trace_id: traceId,
+                message_id: messageId,
+                chat_jid: chatId,
+                feedback_type: feedbackType,
+                user_id: userId
+            });
+            logger.info({ chatId, messageId, feedbackType, traceId }, 'User feedback recorded');
+        }
+        catch (err) {
+            logger.debug({ err }, 'Error handling message reaction');
+        }
+    });
+    // Handle all text messages
+    telegrafBot.on('message', async (ctx) => {
+        if (!ctx.message || !('text' in ctx.message))
+            return;
+        const chatId = String(ctx.chat.id);
+        const chatType = ctx.chat.type;
+        const isGroup = chatType === 'group' || chatType === 'supergroup';
+        const isPrivate = chatType === 'private';
+        const senderId = String(ctx.from?.id || ctx.chat.id);
+        const senderName = ctx.from?.first_name || ctx.from?.username || 'User';
+        const content = ctx.message.text;
+        const timestamp = new Date(ctx.message.date * 1000).toISOString();
+        const messageId = String(ctx.message.message_id);
+        const rawThreadId = ctx.message.message_thread_id;
+        const messageThreadId = Number.isFinite(rawThreadId) ? Number(rawThreadId) : undefined;
+        logger.info({ chatId, isGroup, senderName }, `Telegram message: ${content.substring(0, 50)}...`);
+        try {
+            // Store message in database
+            storeMessage(String(ctx.message.message_id), chatId, senderId, senderName, content, timestamp, false);
+        }
+        catch (error) {
+            logger.error({ error, chatId }, 'Failed to persist Telegram message');
+        }
+        const botUsername = ctx.me;
+        const botId = ctx.botInfo?.id;
+        const adminHandled = await handleAdminCommand({
+            chatId,
+            senderId,
+            senderName,
+            content,
+            botUsername,
+            messageThreadId
+        });
+        if (adminHandled) {
+            return;
+        }
+        const mentioned = isBotMentioned(content, ctx.message.entities, botUsername, botId);
+        const replied = isBotReplied(ctx.message, botId);
+        const group = registeredGroups[chatId];
+        const triggerRegex = isGroup && group?.trigger ? buildTriggerRegex(group.trigger) : null;
+        const triggered = Boolean(triggerRegex && triggerRegex.test(content));
+        const shouldProcess = isPrivate || mentioned || replied || triggered;
+        if (!shouldProcess) {
+            return;
+        }
+        // Rate limiting check
+        const rateCheck = checkRateLimit(senderId);
+        if (!rateCheck.allowed) {
+            const retryAfterSec = Math.ceil((rateCheck.retryAfterMs || 60000) / 1000);
+            logger.warn({ senderId, retryAfterSec }, 'Rate limit exceeded');
+            await sendMessage(chatId, `You're sending messages too quickly. Please wait ${retryAfterSec} seconds and try again.`, { messageThreadId });
+            return;
+        }
+        enqueueMessage({
+            chatId,
+            messageId,
+            senderId,
+            senderName,
+            content,
+            timestamp,
+            isGroup,
+            chatType,
+            messageThreadId
+        });
+    });
+}
+function ensureDockerRunning() {
+    try {
+        execSync('docker info', { stdio: 'pipe', timeout: 10000 });
+        logger.debug('Docker daemon is running');
+    }
+    catch {
+        logger.error('Docker daemon is not running');
+        console.error('\n╔════════════════════════════════════════════════════════════════╗');
+        console.error('║  FATAL: Docker is not running                                  ║');
+        console.error('║                                                                ║');
+        console.error('║  Agents cannot run without Docker. To fix:                     ║');
+        console.error('║  macOS: Start Docker Desktop                                   ║');
+        console.error('║  Linux: sudo systemctl start docker                            ║');
+        console.error('║                                                                ║');
+        console.error('║  Install from: https://docker.com/products/docker-desktop      ║');
+        console.error('╚════════════════════════════════════════════════════════════════╝\n');
+        throw new Error('Docker is required but not running');
+    }
+}
+async function main() {
+    // Ensure directory structure exists before anything else
+    const { ensureDirectoryStructure } = await import('./paths.js');
+    ensureDirectoryStructure();
+    try {
+        const envStat = fs.existsSync(ENV_PATH) ? fs.statSync(ENV_PATH) : null;
+        if (!envStat || envStat.size === 0) {
+            logger.warn({ envPath: ENV_PATH }, '.env is missing or empty; set TELEGRAM_BOT_TOKEN and OPENROUTER_API_KEY');
+        }
+    }
+    catch (err) {
+        logger.warn({ envPath: ENV_PATH, err }, 'Failed to check .env file');
+    }
+    // Validate Telegram token
+    if (!process.env.TELEGRAM_BOT_TOKEN) {
+        throw new Error('TELEGRAM_BOT_TOKEN environment variable is required.\n' +
+            'Create a bot with @BotFather and add the token to your .env file at: ' +
+            ENV_PATH);
+    }
+    ensureDockerRunning();
+    initDatabase();
+    initMemoryStore();
+    startEmbeddingWorker();
+    const expiredMemories = cleanupExpiredMemories();
+    if (expiredMemories > 0) {
+        logger.info({ expiredMemories }, 'Expired memories cleaned up');
+    }
+    logger.info('Database initialized');
+    startMetricsServer();
+    loadState();
+    if (CONTAINER_MODE === 'daemon' && WARM_START_ENABLED) {
+        const groups = Object.values(registeredGroups);
+        for (const group of groups) {
+            try {
+                warmGroupContainer(group, group.folder === MAIN_GROUP_FOLDER);
+                logger.info({ group: group.folder }, 'Warmed daemon container');
+            }
+            catch (err) {
+                logger.warn({ group: group.folder, err }, 'Failed to warm daemon container');
+            }
+        }
+    }
+    // Set up Telegram message handlers
+    setupTelegramHandlers();
+    // Start dashboard
+    startDashboard();
+    // Start Telegram bot
+    try {
+        telegrafBot.launch();
+        setTelegramConnected(true);
+        logger.info('Telegram bot started');
+        // Graceful shutdown
+        process.once('SIGINT', () => {
+            logger.info('Shutting down Telegram bot');
+            setTelegramConnected(false);
+            telegrafBot.stop('SIGINT');
+        });
+        process.once('SIGTERM', () => {
+            logger.info('Shutting down Telegram bot');
+            setTelegramConnected(false);
+            telegrafBot.stop('SIGTERM');
+        });
+        // Start scheduler and IPC watcher
+        // Wrapper that matches the scheduler's expected interface (Promise<void>)
+        const sendMessageForScheduler = async (jid, text) => {
+            await sendMessage(jid, text);
+        };
+        startSchedulerLoop({
+            sendMessage: sendMessageForScheduler,
+            registeredGroups: () => registeredGroups,
+            getSessions: () => sessions,
+            setSession: (groupFolder, sessionId) => {
+                sessions[groupFolder] = sessionId;
+                setGroupSession(groupFolder, sessionId);
+            }
+        });
+        startIpcWatcher();
+        startMaintenanceLoop();
+        startHeartbeatLoop();
+        startDaemonHealthCheckLoop(() => registeredGroups, MAIN_GROUP_FOLDER);
+        logger.info('DotClaw running on Telegram (responds to DMs and group mentions/replies)');
+    }
+    catch (error) {
+        logger.error({ error }, 'Failed to start Telegram bot');
+        process.exit(1);
+    }
+}
+main().catch(err => {
+    logger.error({ err }, 'Failed to start DotClaw');
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map