@dotsetlabs/dotclaw 1.2.0 → 1.4.0

package/dist/index.js

@@ -6,7 +6,7 @@ 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 { initDatabase, storeMessage, upsertChat, getMessagesSinceCursor, getChatState, updateChatState, createTask, updateTask, deleteTask, getTaskById, getAllGroupSessions, setGroupSession, deleteGroupSession, pauseTasksForGroup, getBackgroundJobQueuePosition, getBackgroundJobQueueDepth, linkMessageToTrace, getTraceIdForMessage, recordUserFeedback } from './db.js';
 import { startSchedulerLoop, runTaskNow } from './task-scheduler.js';
 import { startBackgroundJobLoop, spawnBackgroundJob, getBackgroundJobStatus, listBackgroundJobsForGroup, cancelBackgroundJob, recordBackgroundJobUpdate } from './background-jobs.js';
 import { loadJson, saveJson, isSafeGroupFolder } from './utils.js';
@@ -14,10 +14,10 @@ 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 { createProgressManager, DEFAULT_PROGRESS_MESSAGES, DEFAULT_PROGRESS_STAGES, formatProgressWithPlan, formatPlanStepList } from './progress.js';
 import { parseAdminCommand } from './admin-commands.js';
 import { loadModelRegistry, saveModelRegistry } from './model-registry.js';
-import { startMetricsServer, recordMessage, recordError } from './metrics.js';
+import { startMetricsServer, recordMessage, recordError, recordRoutingDecision, recordStageLatency } from './metrics.js';
 import { startMaintenanceLoop } from './maintenance.js';
 import { warmGroupContainer, startDaemonHealthCheckLoop } from './container-runner.js';
 import { loadRuntimeConfig } from './runtime-config.js';
@@ -25,6 +25,9 @@ import { createTraceBase, executeAgentRun, recordAgentTelemetry, AgentExecutionE
 import { logger } from './logger.js';
 import { startDashboard, setTelegramConnected, setLastMessageTime, setMessageQueueDepth } from './dashboard.js';
 import { humanizeError } from './error-messages.js';
+import { classifyBackgroundJob } from './background-job-classifier.js';
+import { routeRequest, routePrompt } from './request-router.js';
+import { probePlanner } from './planner-probe.js';
 const runtime = loadRuntimeConfig();
 function buildTriggerRegex(pattern) {
     if (!pattern)
@@ -145,16 +148,17 @@ 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_JOBS_ENABLED = runtime.host.backgroundJobs.enabled;
+const AUTO_SPAWN_CONFIG = runtime.host.backgroundJobs.autoSpawn;
+const AUTO_SPAWN_ENABLED = BACKGROUND_JOBS_ENABLED && AUTO_SPAWN_CONFIG.enabled;
+const AUTO_SPAWN_FOREGROUND_TIMEOUT_MS = AUTO_SPAWN_CONFIG.foregroundTimeoutMs;
+const AUTO_SPAWN_ON_TIMEOUT = AUTO_SPAWN_CONFIG.onTimeout;
+const AUTO_SPAWN_ON_TOOL_LIMIT = AUTO_SPAWN_CONFIG.onToolLimit;
+const AUTO_SPAWN_CLASSIFIER_ENABLED = AUTO_SPAWN_CONFIG.classifier.enabled;
+const TOOL_CALL_FALLBACK_PATTERN = /tool calls? but did not get a final response/i;
 // 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
@@ -167,6 +171,64 @@ let registeredGroups = {};
 const TELEGRAM_MAX_MESSAGE_LENGTH = 4000;
 const TELEGRAM_SEND_DELAY_MS = 250;
 const messageQueues = new Map();
+const activeRuns = new Map();
+function isCancelMessage(content) {
+    if (!content)
+        return false;
+    const normalized = content.trim().toLowerCase();
+    return normalized === 'cancel'
+        || normalized === 'stop'
+        || normalized === 'abort'
+        || normalized === 'cancel request'
+        || normalized === 'stop request';
+}
+function inferProgressStage(params) {
+    const content = params.content.toLowerCase();
+    const tools = params.plannerTools.map(tool => tool.toLowerCase());
+    const hasWebTool = tools.some(tool => tool.includes('web') || tool.includes('search') || tool.includes('fetch'));
+    const hasCodeTool = tools.some(tool => tool.includes('bash') || tool.includes('edit') || tool.includes('write') || tool.includes('git'));
+    if (params.enablePlanner)
+        return 'planning';
+    if (hasWebTool || /research|search|browse|web|site|docs/.test(content))
+        return 'searching';
+    if (hasCodeTool || /build|code|implement|refactor|fix|debug/.test(content))
+        return 'coding';
+    return 'drafting';
+}
+function estimateForegroundMs(params) {
+    if (typeof params.routing.estimatedMinutes === 'number' && Number.isFinite(params.routing.estimatedMinutes)) {
+        return Math.max(1000, params.routing.estimatedMinutes * 60_000);
+    }
+    const baseChars = params.content.length;
+    if (baseChars === 0)
+        return null;
+    const stepFactor = params.plannerSteps.length > 0 ? params.plannerSteps.length * 6000 : 0;
+    const toolFactor = params.plannerTools.length > 0 ? params.plannerTools.length * 8000 : 0;
+    const lengthFactor = Math.min(60_000, Math.max(3000, Math.round(baseChars / 3)));
+    const profileFactor = params.routing.profile === 'deep' ? 1.4 : 1;
+    return Math.round((lengthFactor + stepFactor + toolFactor) * profileFactor);
+}
+function inferPlanStepIndex(stage, totalSteps) {
+    if (!Number.isFinite(totalSteps) || totalSteps <= 0)
+        return null;
+    const normalized = stage.trim().toLowerCase();
+    if (!normalized)
+        return 1;
+    switch (normalized) {
+        case 'planning':
+            return 1;
+        case 'searching':
+            return Math.min(2, totalSteps);
+        case 'coding':
+            return Math.min(Math.max(2, Math.ceil(totalSteps * 0.6)), totalSteps);
+        case 'drafting':
+            return Math.min(Math.max(2, Math.ceil(totalSteps * 0.8)), totalSteps);
+        case 'finalizing':
+            return totalSteps;
+        default:
+            return 1;
+    }
+}
 const draftSessions = new Map();
 function parseTelegramStreamMode(value) {
     const normalized = value.trim().toLowerCase();
@@ -557,6 +619,17 @@ async function finalizeStreamedMessage(msg, draftId, text) {
     clearDraftSession(msg.chatId, draftId);
 }
 function enqueueMessage(msg) {
+    if (isCancelMessage(msg.content)) {
+        const controller = activeRuns.get(msg.chatId);
+        if (controller) {
+            controller.abort();
+            activeRuns.delete(msg.chatId);
+            void sendMessage(msg.chatId, 'Canceled the current request.', { messageThreadId: msg.messageThreadId });
+            return;
+        }
+        void sendMessage(msg.chatId, 'There is no active request to cancel.', { messageThreadId: msg.messageThreadId });
+        return;
+    }
     const existing = messageQueues.get(msg.chatId);
     if (existing) {
         existing.pendingMessage = msg;
@@ -632,6 +705,20 @@ async function processMessage(msg) {
 ${lines.join('\n')}
 </messages>`;
     const lastMessage = missedMessages[missedMessages.length - 1];
+    const routingStartedAt = Date.now();
+    const routingDecision = routeRequest({
+        prompt,
+        lastMessage
+    });
+    recordRoutingDecision(routingDecision.profile);
+    const routerMs = Date.now() - routingStartedAt;
+    recordStageLatency('router', routerMs, 'telegram');
+    logger.info({
+        chatId: msg.chatId,
+        profile: routingDecision.profile,
+        reason: routingDecision.reason,
+        shouldBackground: routingDecision.shouldBackground
+    }, 'Routing decision');
     const traceBase = createTraceBase({
         chatId: msg.chatId,
         groupFolder: group.folder,
@@ -648,17 +735,224 @@ ${lines.join('\n')}
     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,
+    const isTimeoutError = (value) => {
+        if (!value)
+            return false;
+        return /timed out|timeout/i.test(value);
+    };
+    const shouldPlannerProbe = () => {
+        const config = runtime.host.routing.plannerProbe;
+        if (!config.enabled)
+            return false;
+        if (routingDecision.profile === 'fast' || routingDecision.shouldBackground)
+            return false;
+        const contentLength = lastMessage?.content?.length || 0;
+        return contentLength >= config.minChars;
+    };
+    const maybeAutoSpawn = async (reason, detail, overrides) => {
+        if (!BACKGROUND_JOBS_ENABLED)
+            return false;
+        if (reason !== 'router' && !AUTO_SPAWN_ENABLED)
+            return false;
+        if (reason === 'timeout' && !AUTO_SPAWN_ON_TIMEOUT)
+            return false;
+        if (reason === 'tool_limit' && !AUTO_SPAWN_ON_TOOL_LIMIT)
+            return false;
+        const tags = ['auto-spawn', reason, `profile:${routingDecision.profile}`];
+        if (overrides?.tags && overrides.tags.length > 0) {
+            tags.push(...overrides.tags);
+        }
+        if (routingDecision.estimatedMinutes) {
+            tags.push(`eta:${routingDecision.estimatedMinutes}`);
+        }
+        const estimatedMs = typeof routingDecision.estimatedMinutes === 'number'
+            ? routingDecision.estimatedMinutes * 60_000
+            : null;
+        const computedTimeoutMs = estimatedMs
+            ? Math.min(runtime.host.backgroundJobs.maxRuntimeMs, Math.max(5 * 60_000, Math.round(estimatedMs * 2)))
+            : undefined;
+        const result = spawnBackgroundJob({
+            prompt,
+            groupFolder: group.folder,
+            chatJid: msg.chatId,
+            contextMode: 'group',
+            tags,
+            parentTraceId: traceBase.trace_id,
+            parentMessageId: msg.messageId,
+            modelOverride: overrides?.modelOverride ?? routingDecision.modelOverride,
+            maxToolSteps: overrides?.maxToolSteps ?? routingDecision.maxToolSteps,
+            toolAllow: routingDecision.toolAllow,
+            toolDeny: routingDecision.toolDeny,
+            timeoutMs: overrides?.timeoutMs ?? computedTimeoutMs
+        });
+        if (!result.ok || !result.jobId) {
+            logger.warn({ chatId: msg.chatId, reason, error: result.error }, 'Auto-spawn background job failed');
+            return false;
+        }
+        const queuePosition = getBackgroundJobQueuePosition({ jobId: result.jobId, groupFolder: group.folder });
+        const eta = routingDecision.estimatedMinutes ? `${routingDecision.estimatedMinutes} min` : null;
+        const detailLine = detail ? `\n\nReason: ${detail}` : '';
+        const queueLine = queuePosition ? `\n\nQueue position: ${queuePosition.position} of ${queuePosition.total}` : '';
+        const etaLine = eta ? `\n\nEstimated time: ${eta}` : '';
+        const planPreview = plannerProbeSteps.length > 0
+            ? formatPlanStepList({ steps: plannerProbeSteps, currentStep: 1, maxSteps: 4 })
+            : '';
+        const planLine = planPreview ? `\n\nPlanned steps:\n${planPreview}` : '';
+        await sendMessage(msg.chatId, `Queued this as background job ${result.jobId}. I'll report back when it's done. You can keep chatting while it runs.${queueLine}${etaLine}${detailLine}${planLine}`, { messageThreadId: msg.messageThreadId });
+        if (lastMessage) {
+            updateChatState(msg.chatId, lastMessage.timestamp, lastMessage.id);
+        }
+        if (draftId) {
+            clearDraftSession(msg.chatId, draftId);
+        }
+        return true;
+    };
+    let plannerProbeTools = [];
+    let plannerProbeSteps = [];
+    let plannerProbeMs = null;
+    if (shouldPlannerProbe() && lastMessage) {
+        const probeStarted = Date.now();
+        const probeResult = await probePlanner({
+            lastMessage,
+            recentMessages: missedMessages
+        });
+        plannerProbeMs = Date.now() - probeStarted;
+        recordStageLatency('planner_probe', plannerProbeMs, 'telegram');
+        if (probeResult.steps.length > 0)
+            plannerProbeSteps = probeResult.steps;
+        if (probeResult.tools.length > 0)
+            plannerProbeTools = probeResult.tools;
+        logger.info({
+            chatId: msg.chatId,
+            shouldBackground: probeResult.shouldBackground,
+            steps: probeResult.steps.length,
+            tools: probeResult.tools.length,
+            latencyMs: probeResult.latencyMs,
+            model: probeResult.model,
+            error: probeResult.error
+        }, 'Planner probe decision');
+        if (probeResult.shouldBackground) {
+            const autoSpawned = await maybeAutoSpawn('planner', 'planner probe predicted multi-step work');
+            if (autoSpawned)
+                return true;
+        }
+    }
+    if (routingDecision.shouldBackground) {
+        const autoSpawned = await maybeAutoSpawn('router', routingDecision.reason);
+        if (autoSpawned) {
+            return true;
+        }
+    }
+    let classifierMs = null;
+    if (AUTO_SPAWN_ENABLED && AUTO_SPAWN_CLASSIFIER_ENABLED && lastMessage && routingDecision.shouldRunClassifier) {
+        try {
+            const queueDepth = getBackgroundJobQueueDepth({ groupFolder: group.folder });
+            const classifierResult = await classifyBackgroundJob({
+                lastMessage,
+                recentMessages: missedMessages,
+                isGroup: msg.isGroup,
+                chatType: msg.chatType,
+                queueDepth,
+                metricsSource: 'telegram'
+            });
+            if (classifierResult.latencyMs) {
+                classifierMs = classifierResult.latencyMs;
+                recordStageLatency('classifier', classifierResult.latencyMs, 'telegram');
+            }
+            logger.info({
+                chatId: msg.chatId,
+                decision: classifierResult.shouldBackground,
+                confidence: classifierResult.confidence,
+                latencyMs: classifierResult.latencyMs,
+                model: classifierResult.model,
+                reason: classifierResult.reason,
+                error: classifierResult.error
+            }, 'Background job classifier decision');
+            if (classifierResult.shouldBackground) {
+                const estimated = classifierResult.estimatedMinutes;
+                if (typeof estimated === 'number' && Number.isFinite(estimated) && estimated > 0) {
+                    routingDecision.estimatedMinutes = Math.round(estimated);
+                }
+                const autoSpawned = await maybeAutoSpawn('classifier', classifierResult.reason);
+                if (autoSpawned) {
+                    return true;
+                }
+            }
+        }
+        catch (err) {
+            logger.warn({ chatId: msg.chatId, err }, 'Background job classifier failed');
+        }
+    }
+    const predictedStage = inferProgressStage({
+        content: lastMessage?.content || prompt,
+        plannerTools: plannerProbeTools,
+        plannerSteps: plannerProbeSteps,
+        enablePlanner: routingDecision.enablePlanner
+    });
+    const predictedMs = estimateForegroundMs({
+        content: lastMessage?.content || prompt,
+        routing: routingDecision,
+        plannerSteps: plannerProbeSteps,
+        plannerTools: plannerProbeTools
+    });
+    const planStepIndex = inferPlanStepIndex(predictedStage, plannerProbeSteps.length);
+    const progressManager = createProgressManager({
+        enabled: routingDecision.progress.enabled && !streamingEnabled,
+        initialDelayMs: routingDecision.progress.initialMs,
+        intervalMs: routingDecision.progress.intervalMs,
+        maxUpdates: routingDecision.progress.maxUpdates,
+        messages: routingDecision.progress.messages.length > 0
+            ? routingDecision.progress.messages
+            : DEFAULT_PROGRESS_MESSAGES,
+        stageMessages: DEFAULT_PROGRESS_STAGES,
+        stageThrottleMs: 20_000,
         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();
+    progressManager.start();
+    let sentPlan = false;
+    if (predictedMs && predictedMs >= 10_000 && routingDecision.progress.enabled && !streamingEnabled) {
+        if (plannerProbeSteps.length > 0) {
+            const planMessage = formatProgressWithPlan({
+                steps: plannerProbeSteps,
+                currentStep: planStepIndex ?? 1,
+                stage: predictedStage
+            });
+            progressManager.notify(planMessage);
+            sentPlan = true;
+        }
+        else {
+            progressManager.notify(DEFAULT_PROGRESS_STAGES.ack);
+        }
+    }
+    if (!(sentPlan && predictedStage === 'planning')) {
+        progressManager.setStage(predictedStage);
+    }
+    if (predictedStage === 'planning') {
+        const followUpStage = inferProgressStage({
+            content: lastMessage?.content || prompt,
+            plannerTools: plannerProbeTools,
+            plannerSteps: plannerProbeSteps,
+            enablePlanner: false
+        });
+        if (followUpStage !== 'planning') {
+            const delay = Math.min(15_000, Math.max(5_000, Math.floor(routingDecision.progress.initialMs / 2)));
+            setTimeout(() => progressManager.setStage(followUpStage), delay);
+        }
+    }
+    const abortController = new AbortController();
+    activeRuns.set(msg.chatId, abortController);
     try {
+        const recallMaxResults = routingDecision.enableMemoryRecall
+            ? (Number.isFinite(routingDecision.recallMaxResults)
+                ? Math.max(0, Math.floor(routingDecision.recallMaxResults))
+                : MEMORY_RECALL_MAX_RESULTS)
+            : 0;
+        const recallMaxTokens = routingDecision.enableMemoryRecall
+            ? (Number.isFinite(routingDecision.recallMaxTokens)
+                ? Math.max(0, Math.floor(routingDecision.recallMaxTokens))
+                : MEMORY_RECALL_MAX_TOKENS)
+            : 0;
         const execution = await executeAgentRun({
             group,
             prompt,
@@ -666,8 +960,10 @@ ${lines.join('\n')}
             userId: msg.senderId,
             userName: msg.senderName,
             recallQuery: recallQuery || msg.content,
-            recallMaxResults: MEMORY_RECALL_MAX_RESULTS,
-            recallMaxTokens: MEMORY_RECALL_MAX_TOKENS,
+            recallMaxResults,
+            recallMaxTokens,
+            toolAllow: routingDecision.toolAllow,
+            toolDeny: routingDecision.toolDeny,
             sessionId: sessions[group.folder],
             onSessionUpdate: (sessionId) => { sessions[group.folder] = sessionId; },
             streaming: streamingEnabled && draftId
@@ -678,10 +974,22 @@ ${lines.join('\n')}
                     minChars: TELEGRAM_STREAM_MIN_CHARS
                 }
                 : undefined,
-            availableGroups: buildAvailableGroupsSnapshot()
+            availableGroups: buildAvailableGroupsSnapshot(),
+            modelOverride: routingDecision.modelOverride,
+            modelMaxOutputTokens: routingDecision.maxOutputTokens,
+            maxToolSteps: routingDecision.maxToolSteps,
+            disablePlanner: !routingDecision.enablePlanner,
+            disableResponseValidation: !routingDecision.enableResponseValidation,
+            responseValidationMaxRetries: routingDecision.responseValidationMaxRetries,
+            disableMemoryExtraction: !routingDecision.enableMemoryExtraction,
+            abortSignal: abortController.signal,
+            timeoutMs: AUTO_SPAWN_ENABLED && AUTO_SPAWN_FOREGROUND_TIMEOUT_MS > 0
+                ? AUTO_SPAWN_FOREGROUND_TIMEOUT_MS
+                : undefined
         });
         output = execution.output;
         context = execution.context;
+        progressManager.setStage('finalizing');
         if (output.status === 'error') {
             errorMessage = output.error || 'Unknown error';
         }
@@ -697,8 +1005,15 @@ ${lines.join('\n')}
         logger.error({ group: group.name, err }, 'Agent error');
     }
     finally {
-        progressNotifier.stop();
-    }
+        progressManager.stop();
+        activeRuns.delete(msg.chatId);
+    }
+    const extraTimings = {};
+    extraTimings.router_ms = routerMs;
+    if (classifierMs !== null)
+        extraTimings.classifier_ms = classifierMs;
+    if (plannerProbeMs !== null)
+        extraTimings.planner_probe_ms = plannerProbeMs;
     if (!output) {
         const message = errorMessage || 'No output from agent';
         if (context) {
@@ -709,7 +1024,8 @@ ${lines.join('\n')}
                 metricsSource: 'telegram',
                 toolAuditSource: 'message',
                 errorMessage: message,
-                errorType: 'agent'
+                errorType: 'agent',
+                extraTimings
             });
         }
         else {
@@ -729,6 +1045,12 @@ ${lines.join('\n')}
                 source: traceBase.source
             });
         }
+        if (isTimeoutError(message)) {
+            const autoSpawned = await maybeAutoSpawn('timeout', message);
+            if (autoSpawned) {
+                return true;
+            }
+        }
         const userMessage = humanizeError(errorMessage || 'Unknown error');
         await sendMessage(msg.chatId, userMessage, { messageThreadId: msg.messageThreadId });
         if (draftId) {
@@ -745,11 +1067,19 @@ ${lines.join('\n')}
                 metricsSource: 'telegram',
                 toolAuditSource: 'message',
                 errorMessage: errorMessage || output.error || 'Unknown error',
-                errorType: 'agent'
+                errorType: 'agent',
+                extraTimings
             });
         }
         logger.error({ group: group.name, error: output.error }, 'Container agent error');
-        const userMessage = humanizeError(errorMessage || output.error || 'Unknown error');
+        const errorText = errorMessage || output.error || 'Unknown error';
+        if (isTimeoutError(errorText)) {
+            const autoSpawned = await maybeAutoSpawn('timeout', errorText);
+            if (autoSpawned) {
+                return true;
+            }
+        }
+        const userMessage = humanizeError(errorText);
         await sendMessage(msg.chatId, userMessage, { messageThreadId: msg.messageThreadId });
         if (draftId) {
             clearDraftSession(msg.chatId, draftId);
@@ -780,6 +1110,23 @@ ${lines.join('\n')}
         }
     }
     else if (output.tool_calls && output.tool_calls.length > 0) {
+        const toolLimitHit = !output.result || !output.result.trim() || TOOL_CALL_FALLBACK_PATTERN.test(output.result);
+        if (toolLimitHit) {
+            const autoSpawned = await maybeAutoSpawn('tool_limit', 'Tool-call step limit reached');
+            if (autoSpawned) {
+                if (context) {
+                    recordAgentTelemetry({
+                        traceBase,
+                        output,
+                        context,
+                        metricsSource: 'telegram',
+                        toolAuditSource: 'message',
+                        extraTimings
+                    });
+                }
+                return true;
+            }
+        }
         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);
@@ -797,7 +1144,8 @@ ${lines.join('\n')}
             output,
             context,
             metricsSource: 'telegram',
-            toolAuditSource: 'message'
+            toolAuditSource: 'message',
+            extraTimings
         });
     }
     return true;
@@ -997,11 +1345,22 @@ async function runHeartbeatOnce() {
         inputText: prompt,
         source: 'dotclaw-heartbeat'
     });
+    const routingStartedAt = Date.now();
+    const routingDecision = routePrompt(prompt);
+    recordRoutingDecision(routingDecision.profile);
+    const routerMs = Date.now() - routingStartedAt;
+    recordStageLatency('router', routerMs, 'scheduler');
     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);
+    const baseRecallResults = Number.isFinite(routingDecision.recallMaxResults)
+        ? Math.max(0, Math.floor(routingDecision.recallMaxResults))
+        : MEMORY_RECALL_MAX_RESULTS;
+    const baseRecallTokens = Number.isFinite(routingDecision.recallMaxTokens)
+        ? Math.max(0, Math.floor(routingDecision.recallMaxTokens))
+        : MEMORY_RECALL_MAX_TOKENS;
+    const recallMaxResults = routingDecision.enableMemoryRecall ? Math.max(4, baseRecallResults - 2) : 0;
+    const recallMaxTokens = routingDecision.enableMemoryRecall ? Math.max(600, baseRecallTokens - 200) : 0;
     try {
         const execution = await executeAgentRun({
             group,
@@ -1014,7 +1373,14 @@ async function runHeartbeatOnce() {
             sessionId: sessions[group.folder],
             onSessionUpdate: (sessionId) => { sessions[group.folder] = sessionId; },
             isScheduledTask: true,
-            availableGroups: buildAvailableGroupsSnapshot()
+            availableGroups: buildAvailableGroupsSnapshot(),
+            modelOverride: routingDecision.modelOverride,
+            modelMaxOutputTokens: routingDecision.maxOutputTokens,
+            maxToolSteps: routingDecision.maxToolSteps,
+            disablePlanner: !routingDecision.enablePlanner,
+            disableResponseValidation: !routingDecision.enableResponseValidation,
+            responseValidationMaxRetries: routingDecision.responseValidationMaxRetries,
+            disableMemoryExtraction: !routingDecision.enableMemoryExtraction
         });
         output = execution.output;
         context = execution.context;
@@ -1038,7 +1404,8 @@ async function runHeartbeatOnce() {
             output,
             context,
             toolAuditSource: 'heartbeat',
-            errorMessage: errorMessage ?? undefined
+            errorMessage: errorMessage ?? undefined,
+            extraTimings: { router_ms: routerMs }
         });
     }
     else if (errorMessage) {
@@ -1817,6 +2184,11 @@ function setupTelegramHandlers() {
         const isPrivate = chatType === 'private';
         const senderId = String(ctx.from?.id || ctx.chat.id);
         const senderName = ctx.from?.first_name || ctx.from?.username || 'User';
+        const chatName = ('title' in ctx.chat && ctx.chat.title)
+            || ('username' in ctx.chat && ctx.chat.username)
+            || ctx.from?.first_name
+            || ctx.from?.username
+            || senderName;
         const content = ctx.message.text;
         const timestamp = new Date(ctx.message.date * 1000).toISOString();
         const messageId = String(ctx.message.message_id);
@@ -1825,6 +2197,7 @@ function setupTelegramHandlers() {
         logger.info({ chatId, isGroup, senderName }, `Telegram message: ${content.substring(0, 50)}...`);
         try {
             // Store message in database
+            upsertChat({ chatId, name: chatName, lastMessageTime: timestamp });
             storeMessage(String(ctx.message.message_id), chatId, senderId, senderName, content, timestamp, false);
         }
         catch (error) {