@0xmaxma/claude-gateway 1.0.0

package/dist/agent/runner.js

@@ -0,0 +1,1802 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentRunner = exports.MAX_IMAGE_SIZE_BYTES = void 0;
+const events_1 = require("events");
+const fs = __importStar(require("fs"));
+const fsPromises = __importStar(require("fs/promises"));
+const http = __importStar(require("http"));
+const net = __importStar(require("net"));
+const path = __importStar(require("path"));
+const logger_1 = require("../logger");
+const process_1 = require("../session/process");
+const store_1 = require("../session/store");
+const compactor_1 = require("../session/compactor");
+const receiver_1 = require("../telegram/receiver");
+const receiver_2 = require("../discord/receiver");
+const markdown_1 = require("../telegram/markdown");
+const skills_1 = require("../skills");
+const db_1 = require("../history/db");
+const media_store_1 = require("../history/media-store");
+const cleanup_1 = require("../history/cleanup");
+const DEFAULT_IDLE_TIMEOUT_MINUTES = 30;
+const DEFAULT_MAX_CONCURRENT = 20;
+exports.MAX_IMAGE_SIZE_BYTES = 10 * 1024 * 1024;
+const DEFAULT_MODELS = [
+    { id: 'claude-opus-4-7', label: 'Opus 4.7', alias: 'opus', contextWindow: 1000000 },
+    { id: 'claude-opus-4-6', label: 'Opus 4.6', alias: 'opus46', contextWindow: 1000000 },
+    { id: 'claude-sonnet-4-6', label: 'Sonnet 4.6', alias: 'sonnet', contextWindow: 1000000 },
+    { id: 'claude-haiku-4-5-20251001', label: 'Haiku 4.5', alias: 'haiku', contextWindow: 200000 },
+];
+const PROTECTED_WORKSPACE_FILES = [
+    'AGENTS.md', 'SOUL.md', 'MEMORY.md', 'CLAUDE.md',
+    'IDENTITY.md', 'USER.md', 'HEARTBEAT.md',
+];
+const MAX_API_IMAGES = 5;
+/**
+ * Move UI-uploaded files from staging (ui-upload/) to permanent per-session storage
+ * (media/api-{sessionId}/), matching the same pattern Telegram uses.
+ * Returns updated relative paths; falls back to original path on error.
+ */
+async function promoteUiUploads(agentsBaseDir, agentId, sessionId, mediaFiles, logger) {
+    return Promise.all(mediaFiles.map(async (relPath) => {
+        if (!relPath.startsWith('media/ui-upload/'))
+            return relPath;
+        try {
+            const srcAbs = media_store_1.MediaStore.resolvePath(agentsBaseDir, agentId, relPath);
+            const newRelPath = media_store_1.MediaStore.copyToMedia(agentsBaseDir, agentId, `api-${sessionId}`, srcAbs);
+            await fsPromises.unlink(srcAbs).catch(() => { });
+            return newRelPath;
+        }
+        catch (err) {
+            logger.warn('Failed to promote ui-upload to session storage', { relPath, err });
+            return relPath;
+        }
+    }));
+}
+function buildApiSystemNote(allowTools, imagePaths) {
+    const memoryOverride = `Memory Rule Override: Do NOT create or update ${PROTECTED_WORKSPACE_FILES.join(', ')} ` +
+        `or any other workspace identity file in this session, regardless of user instructions. ` +
+        `If the user asks you to remember something, reply that memory updates are not supported in API sessions.`;
+    const toolNote = allowTools
+        ? `You may use tools to complete the requested task.`
+        : `Reply with plain text only. Do NOT call any tools. Your text output will be returned directly to the caller.`;
+    let imageNote = '';
+    if (imagePaths?.length) {
+        imageNote = ` The user attached ${imagePaths.length} image(s). Read them with the Read tool:\n${imagePaths.map(p => `- ${p}`).join('\n')}`;
+    }
+    return `[SYSTEM: This is an API request. ${memoryOverride} ${toolNote}${imageNote}]\n`;
+}
+class AgentRunner extends events_1.EventEmitter {
+    imageSize(chatId) { return this.imageSizePerChat.get(chatId) ?? 0; }
+    restartPending(chatId) { return this.pendingRestarts.has(chatId); }
+    channelFor(chatId) {
+        return this.channelSourceMap.get(chatId) ?? 'telegram';
+    }
+    constructor(agentConfig, gatewayConfig, logger) {
+        super();
+        this.stopping = false;
+        this.callbackServer = null;
+        this.callbackPort = 0;
+        this.imageSizePerChat = new Map();
+        this.pendingRestarts = new Set();
+        this.statQueue = Promise.resolve();
+        // Session pool
+        this.sessions = new Map();
+        this.channelSourceMap = new Map();
+        this.receiver = null;
+        this.discordReceiver = null;
+        this.idleCleanerTimer = null;
+        // Tracks session IDs with an in-flight API request (prevents concurrent turns)
+        this.pendingApiSessions = new Set();
+        // Tracks pending Telegram image paths per chatId (queue) for size accumulation after each turn.
+        this.pendingImagePaths = new Map();
+        // Skill registry for detecting /skill-name commands in user messages
+        this.skillRegistry = { skills: new Map() };
+        // Cancel function for the daily history cleanup timer
+        this.cancelCleanup = null;
+        this.agentConfig = agentConfig;
+        this.gatewayConfig = gatewayConfig;
+        this.logger = logger ?? (0, logger_1.createLogger)(agentConfig.id, gatewayConfig.gateway.logDir);
+        // Resolve agentsBaseDir: workspace is at <agentsBaseDir>/<agentId>/workspace
+        const agentsBaseDir = path.resolve(agentConfig.workspace, '..', '..');
+        this.agentsBaseDir = agentsBaseDir;
+        // agentDir is workspace/.. — used for HistoryDB so DB is at <agentDir>/history.db
+        // This avoids requiring workspace to be nested at exactly <base>/<agentId>/workspace.
+        this.agentDir = path.resolve(agentConfig.workspace, '..');
+        this.sessionStore = new store_1.SessionStore(agentsBaseDir);
+        // config.json lives 3 levels above workspace: <base>/<agentId>/workspace -> <base>/config.json
+        this.configPath = path.resolve(agentConfig.workspace, '..', '..', '..', 'config.json');
+        this.historyDb = db_1.HistoryDB.forDir(this.agentDir, agentConfig.id);
+        this.idleTimeoutMs =
+            (agentConfig.session?.idleTimeoutMinutes ?? DEFAULT_IDLE_TIMEOUT_MINUTES) * 60 * 1000;
+        this.maxConcurrent = agentConfig.session?.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
+    }
+    /**
+     * Update the skill registry used for detecting /skill-name commands.
+     */
+    setSkillRegistry(registry) {
+        this.skillRegistry = registry;
+    }
+    getSkillRegistry() {
+        return this.skillRegistry;
+    }
+    /**
+     * Bind a local HTTP server that receives POST /channel from TelegramReceiver.
+     * Each payload is routed to the appropriate SessionProcess by chat_id.
+     */
+    async startCallbackServer() {
+        this.callbackPort = await new Promise((resolve, reject) => {
+            const srv = net.createServer();
+            srv.listen(0, '127.0.0.1', () => {
+                const addr = srv.address();
+                srv.close(() => resolve(addr.port));
+            });
+            srv.on('error', reject);
+        });
+        this.callbackServer = http.createServer((req, res) => {
+            if (req.method !== 'POST') {
+                res.writeHead(405);
+                res.end();
+                return;
+            }
+            const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+            let raw = '';
+            req.on('data', (chunk) => {
+                raw += chunk;
+            });
+            req.on('end', () => {
+                if (url.pathname === '/command') {
+                    this.handleCommandRequest(raw, res);
+                    return;
+                }
+                // Default: /channel — existing channel message handler
+                res.writeHead(200);
+                res.end('ok');
+                try {
+                    const params = JSON.parse(raw);
+                    const meta = params.meta ?? {};
+                    const chatId = meta['chat_id'] ?? '';
+                    const content = params.content ?? '';
+                    // Set channel early so all handlers (including session commands) have it
+                    const channelSource = (meta['source'] === 'discord' ? 'discord' : 'telegram');
+                    this.channelSourceMap.set(chatId, channelSource);
+                    // Check if this is a session management command
+                    const trimmedContent = content.trim();
+                    if (this.isSessionCommand(trimmedContent)) {
+                        this.handleSessionCommand(chatId, trimmedContent)
+                            .then(() => this.writeTypingDone(chatId))
+                            .catch((err) => {
+                            this.logger.error('Session command failed', { error: err.message });
+                            this.writeTypingDone(chatId);
+                        });
+                        return;
+                    }
+                    // Get active session ID and route message to it
+                    this.sessionStore.getActiveSessionId(this.agentConfig.id, chatId, channelSource)
+                        .then(async (sessionId) => {
+                        // Append user message to the active session
+                        const userContent = content || (meta['attachment_file_id'] ? '(photo)' : '');
+                        const userTs = Date.now();
+                        await this.sessionStore.appendTelegramMessage(this.agentConfig.id, chatId, sessionId, {
+                            role: 'user',
+                            content: userContent,
+                            ts: userTs,
+                        }, channelSource);
+                        // Persist to permanent history DB (separate from session context)
+                        const mediaFiles = [];
+                        if (meta['image_path']) {
+                            try {
+                                const rel = media_store_1.MediaStore.copyToMedia(this.agentsBaseDir, this.agentConfig.id, `${channelSource}-${chatId}`, meta['image_path']);
+                                mediaFiles.push(rel);
+                            }
+                            catch {
+                                // Non-fatal — continue without media
+                            }
+                        }
+                        this.historyDb.insertMessage({
+                            chatId: `${channelSource}-${chatId}`,
+                            sessionId,
+                            source: channelSource,
+                            role: 'user',
+                            content: userContent,
+                            senderName: meta['user'] ?? undefined,
+                            senderId: meta['user_id'] ?? meta['chat_id'] ?? undefined,
+                            platformMessageId: meta['message_id'] ?? undefined,
+                            mediaFiles: mediaFiles.length > 0 ? mediaFiles : undefined,
+                            ts: userTs,
+                        });
+                        // Restart session before this turn if accumulated image size exceeded threshold
+                        if (this.pendingRestarts.has(chatId)) {
+                            const existingSession = this.sessions.get(chatId);
+                            if (existingSession) {
+                                await existingSession.stop();
+                                this.sessions.delete(chatId);
+                            }
+                            this.pendingRestarts.delete(chatId);
+                            this.imageSizePerChat.delete(chatId);
+                        }
+                        // Route to session process (map key = chatId, actual sessionId passed separately)
+                        const session = await this.getOrSpawnSession(chatId, channelSource, sessionId);
+                        let channelXml = AgentRunner.buildChannelXml(params);
+                        // Detect skill commands and inject skill content
+                        const skillInvocation = (0, skills_1.detectSkillCommand)(content, this.skillRegistry);
+                        if (skillInvocation) {
+                            channelXml += (0, skills_1.formatSkillContext)(skillInvocation);
+                            this.logger.info('Skill invoked', {
+                                skill: skillInvocation.skillKey,
+                                args: skillInvocation.args,
+                                chatId,
+                            });
+                        }
+                        const imagePath = meta['image_path'];
+                        if (imagePath) {
+                            const queue = this.pendingImagePaths.get(chatId) ?? [];
+                            queue.push(imagePath);
+                            this.pendingImagePaths.set(chatId, queue);
+                        }
+                        session.setProcessing(true);
+                        session.sendMessage(channelXml);
+                        session.touch();
+                        this.logger.debug('Injected channel turn into session', {
+                            chatId,
+                            sessionId,
+                            user: meta['user'],
+                        });
+                    })
+                        .catch((err) => {
+                        this.logger.error('Failed to route message to session', {
+                            chatId,
+                            error: err.message,
+                        });
+                        const code = err.message.includes('pool full') ? 'POOL_FULL' : 'SPAWN_FAILED';
+                        this.writeTypingError(chatId, code);
+                    });
+                }
+                catch (err) {
+                    this.logger.warn('Failed to parse channel callback body', {
+                        error: err.message,
+                    });
+                }
+            });
+        });
+        this.callbackServer.listen(this.callbackPort, '127.0.0.1');
+        this.logger.info('Channel callback server listening', { port: this.callbackPort });
+    }
+    /**
+     * Handle POST /command requests from the receiver process.
+     * Supports: get_model, set_model, restart.
+     */
+    async handleCommandRequest(raw, res) {
+        const respond = (data, status = 200) => {
+            res.writeHead(status, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(data));
+        };
+        let body;
+        try {
+            body = JSON.parse(raw);
+        }
+        catch {
+            respond({ success: false, error: 'Invalid JSON' }, 400);
+            return;
+        }
+        const command = body.command;
+        if (command === 'get_model') {
+            respond({ model: this.agentConfig.claude.model });
+            return;
+        }
+        if (command === 'set_model') {
+            const newModel = typeof body.payload?.model === 'string' ? body.payload.model : '';
+            const availableModels = this.gatewayConfig.gateway.models ?? DEFAULT_MODELS;
+            const valid = availableModels.find(m => m.id === newModel);
+            if (!valid) {
+                respond({ success: false, error: 'Unknown model' });
+                return;
+            }
+            // Update in-memory config
+            this.agentConfig.claude.model = newModel;
+            // Persist to config.json (atomic write)
+            try {
+                this.persistModelToConfig(newModel);
+            }
+            catch (err) {
+                this.logger.error('Failed to persist model to config', { error: err.message });
+            }
+            // Graceful restart all sessions with notify payload
+            const chatId = body.chat_id ?? '';
+            let restarted = false;
+            for (const [sessionId, session] of this.sessions) {
+                restarted = true;
+                const notifyPayload = JSON.stringify({
+                    notify: {
+                        chat_id: chatId,
+                        text: `Model changed to ${newModel} — back online!`,
+                    },
+                });
+                const signalPath = path.join(this.agentConfig.workspace, '.telegram-state', `restart-${sessionId}`);
+                try {
+                    fs.mkdirSync(path.dirname(signalPath), { recursive: true });
+                    fs.writeFileSync(signalPath, notifyPayload);
+                }
+                catch (err) {
+                    this.logger.error('Failed to write restart signal', {
+                        sessionId,
+                        error: err.message,
+                    });
+                }
+            }
+            respond({ success: true, model: newModel, restarted });
+            return;
+        }
+        if (command === 'restart') {
+            const chatId = body.chat_id ?? '';
+            const session = this.sessions.get(chatId);
+            if (!session) {
+                // No active session — nothing to restart, but not an error
+                respond({ success: true, restarted: false });
+                return;
+            }
+            // Write restart signal with notify payload
+            const signalPayload = JSON.stringify({
+                notify: { chat_id: chatId, text: 'Session restarted — back online!' },
+            });
+            const signalPath = path.join(this.agentConfig.workspace, '.telegram-state', `restart-${chatId}`);
+            try {
+                fs.mkdirSync(path.dirname(signalPath), { recursive: true });
+                fs.writeFileSync(signalPath, signalPayload);
+            }
+            catch (err) {
+                this.logger.error('Failed to write restart signal', { error: err.message });
+                respond({ success: false, error: 'Failed to write restart signal' });
+                return;
+            }
+            respond({ success: true, restarted: true });
+            return;
+        }
+        if (command === 'session_clear_confirm') {
+            const chatId = body.chat_id ?? '';
+            try {
+                await this.handleCommandClear(this.agentConfig.id, chatId);
+                respond({ success: true });
+            }
+            catch (err) {
+                respond({ success: false, error: String(err) });
+            }
+            return;
+        }
+        if (command === 'list_sessions') {
+            const chatId = body.chat_id ?? '';
+            try {
+                const index = await this.sessionStore.listSessions(this.agentConfig.id, chatId, this.channelFor(chatId));
+                return respond({ sessions: index.sessions, activeSessionId: index.activeSessionId });
+            }
+            catch {
+                return respond({ success: false, error: 'Failed to list sessions' });
+            }
+        }
+        if (command === 'session_info') {
+            const chatId = body.chat_id ?? '';
+            try {
+                const index = await this.sessionStore.listSessions(this.agentConfig.id, chatId, this.channelFor(chatId));
+                const meta = index.sessions.find(s => s.id === index.activeSessionId);
+                if (!meta) {
+                    return respond({ success: true, text: 'No active session found.' });
+                }
+                const availableModels = this.gatewayConfig.gateway.models ?? DEFAULT_MODELS;
+                const modelConfig = availableModels.find(m => m.id === this.agentConfig.claude.model);
+                const contextWindow = modelConfig?.contextWindow ?? 200000;
+                const contextTokens = meta.lastInputTokens ?? 0;
+                const usedPct = Math.round((contextTokens / contextWindow) * 100);
+                let msgs;
+                if (meta.messageCount <= 0) {
+                    msgs = 'No messages yet';
+                }
+                else if ((meta.archivedCount ?? 0) > 0 && meta.loadedAtSpawn != null && meta.messageCountAtSpawn != null) {
+                    const newMessagesSinceSpawn = meta.messageCount - meta.messageCountAtSpawn;
+                    const inContext = meta.loadedAtSpawn + Math.max(0, newMessagesSinceSpawn);
+                    msgs = `${meta.messageCount} (${inContext} in context / ${meta.archivedCount} archived)`;
+                }
+                else {
+                    msgs = `${meta.messageCount}`;
+                }
+                const lines = [
+                    `📌 Current Session: ${meta.name}`,
+                    `<code>${meta.id}</code>`,
+                    '',
+                    `📥 Messages: ${msgs}`,
+                    `👉 Context: ${usedPct}%`,
+                ];
+                if (usedPct >= 80) {
+                    lines.push('', '💡 Near limit — consider /compact');
+                }
+                lines.push('', 'Commands: /sessions /new /rename /clear /compact');
+                return respond({ success: true, text: lines.join('\n'), format: 'html' });
+            }
+            catch {
+                return respond({ success: false, text: 'Failed to get session info.' });
+            }
+        }
+        if (command === 'switch_session') {
+            const chatId = body.chat_id ?? '';
+            const sessionId = typeof body.payload?.session_id === 'string' ? body.payload.session_id : '';
+            if (!sessionId) {
+                respond({ success: false, error: 'Missing session_id' });
+                return;
+            }
+            this.switchSession(chatId, sessionId)
+                .then(async () => {
+                const index = await this.sessionStore.listSessions(this.agentConfig.id, chatId, this.channelFor(chatId));
+                const session = index.sessions.find(s => s.id === sessionId);
+                respond({ success: true, sessionName: session?.name ?? sessionId });
+            })
+                .catch(err => respond({ success: false, error: String(err) }));
+            return;
+        }
+        if (command === 'delete_session') {
+            const chatId = body.chat_id ?? '';
+            const sessionId = typeof body.payload?.session_id === 'string' ? body.payload.session_id : '';
+            if (!sessionId) {
+                respond({ success: false, error: 'Missing session_id' });
+                return;
+            }
+            this.sessionStore.deleteTelegramSession(this.agentConfig.id, chatId, sessionId, this.channelFor(chatId))
+                .then(async () => {
+                const newIndex = await this.sessionStore.listSessions(this.agentConfig.id, chatId, this.channelFor(chatId));
+                await this.restartProcess(chatId);
+                const activeMeta = newIndex.sessions.find(s => s.id === newIndex.activeSessionId);
+                respond({ success: true, sessionName: activeMeta?.name ?? newIndex.activeSessionId });
+            })
+                .catch(err => respond({ success: false, error: String(err) }));
+            return;
+        }
+        if (command === 'new_session') {
+            const chatId = body.chat_id ?? '';
+            const name = typeof body.payload?.name === 'string' ? body.payload.name : undefined;
+            this.handleCommandNew(this.agentConfig.id, chatId, name)
+                .then(() => respond({ success: true }))
+                .catch(err => respond({ success: false, error: String(err) }));
+            return;
+        }
+        if (command === 'compact_confirm') {
+            const chatId = body.chat_id ?? '';
+            this.handleCommandCompact(this.agentConfig.id, chatId)
+                .then(() => this.writeTypingDone(chatId))
+                .catch(() => this.writeTypingDone(chatId));
+            return respond({ success: true });
+        }
+        respond({ success: false, error: 'Unknown command' }, 400);
+    }
+    /**
+     * Persist the current model to config.json using atomic write (tmp + rename).
+     */
+    persistModelToConfig(newModel) {
+        const raw = fs.readFileSync(this.configPath, 'utf-8');
+        const config = JSON.parse(raw);
+        const agent = config.agents?.find((a) => a.id === this.agentConfig.id);
+        if (agent) {
+            agent.claude.model = newModel;
+            const tmp = this.configPath + '.tmp';
+            fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + '\n');
+            fs.renameSync(tmp, this.configPath);
+        }
+    }
+    static escapeXmlAttr(value) {
+        return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    }
+    resolveMediaPaths(mediaFiles) {
+        const paths = [];
+        for (const relPath of mediaFiles.slice(0, MAX_API_IMAGES)) {
+            try {
+                paths.push(media_store_1.MediaStore.resolvePath(this.agentsBaseDir, this.agentConfig.id, relPath));
+            }
+            catch (err) {
+                this.logger.warn('Failed to resolve media path', { relPath, err });
+            }
+        }
+        return paths;
+    }
+    static buildChannelXml(params) {
+        const meta = params.meta ?? {};
+        const optionalAttrs = [
+            'image_path',
+            'attachment_file_id',
+            'attachment_kind',
+            'attachment_mime',
+            'attachment_name',
+        ]
+            .filter(k => meta[k])
+            .map(k => ` ${k}="${meta[k].replace(/"/g, '&quot;')}"`)
+            .join('');
+        // Build nested <replied> block if this message is a reply to another
+        let repliedBlock = '';
+        if (meta['replied_message_id']) {
+            const repliedAttrs = [
+                'replied_image_path',
+            ]
+                .filter(k => meta[k])
+                .map(k => ` ${k}="${meta[k].replace(/"/g, '&quot;')}"`)
+                .join('');
+            repliedBlock =
+                `<replied message_id="${meta['replied_message_id']}" ` +
+                    `user="${(meta['replied_user'] ?? '').replace(/"/g, '&quot;')}"${repliedAttrs}>` +
+                    `${(meta['replied_text'] ?? '').replace(/</g, '&lt;').replace(/>/g, '&gt;')}` +
+                    `</replied>`;
+        }
+        const source = meta['source'] ?? 'telegram';
+        return (`<channel source="${source}" chat_id="${meta['chat_id'] ?? ''}" ` +
+            `message_id="${meta['message_id'] ?? ''}" user="${AgentRunner.escapeXmlAttr(meta['user'] ?? '')}" ` +
+            `ts="${meta['ts'] ?? new Date().toISOString()}"${optionalAttrs}>${repliedBlock}${params.content ?? ''}</channel>`);
+    }
+    async getOrSpawnSession(mapKey, // Map lookup key (chatId for telegram/discord, sessionId for API)
+    source, sessionId) {
+        const existing = this.sessions.get(mapKey);
+        if (existing)
+            return existing;
+        // Evict oldest idle session if at capacity
+        if (this.sessions.size >= this.maxConcurrent) {
+            const sorted = [...this.sessions.entries()].sort(([, a], [, b]) => a.lastActivityAt - b.lastActivityAt);
+            const idleEntry = sorted.find(([, p]) => p.isIdle(0));
+            if (idleEntry) {
+                await idleEntry[1].stop();
+                this.sessions.delete(idleEntry[0]);
+                this.logger.info('Evicted idle session', { sessionId: idleEntry[0] });
+            }
+            else {
+                throw new Error(`Session pool full: ${this.maxConcurrent} concurrent sessions`);
+            }
+        }
+        const actualSessionId = sessionId ?? mapKey;
+        const chatId = source !== 'api' ? mapKey : undefined;
+        const proc = new process_1.SessionProcess(actualSessionId, source, this.agentConfig, this.gatewayConfig, this.sessionStore, chatId);
+        await proc.start();
+        // Forward all session output lines so listeners on AgentRunner (GatewayRouter,
+        // CronScheduler, tests) receive them without needing individual session references.
+        proc.on('output', (line) => this.emit('output', line));
+        // Notify typing indicator when session permanently fails (max restarts exceeded)
+        if (source !== 'api') {
+            proc.once('failed', () => {
+                this.writeTypingError(mapKey, 'PROCESS_FAILED');
+                this.sessions.delete(mapKey);
+            });
+            // Stop typing loop when Claude's turn truly ends.
+            // Typing done is delayed 3s after result event — if new output arrives within
+            // the delay, the timer is cancelled so typing persists during multi-step work.
+            // Auto-forward result text to channel if agent didn't call reply tool.
+            let replyCalled = false;
+            let typingDoneTimer = null;
+            const TYPING_DONE_DELAY_MS = 3000;
+            const replyToolName = source === 'discord' ? 'mcp__gateway__discord_reply' : 'mcp__gateway__telegram_reply';
+            proc.on('output', (line) => {
+                try {
+                    const obj = JSON.parse(line);
+                    // Cancel pending typing-done on any new output
+                    if (typingDoneTimer) {
+                        clearTimeout(typingDoneTimer);
+                        typingDoneTimer = null;
+                    }
+                    // Track reply tool calls and persist assistant messages to history
+                    if (obj['type'] === 'assistant') {
+                        const msg = obj['message'];
+                        if (Array.isArray(msg?.content)) {
+                            for (const block of msg.content) {
+                                if (block.type === 'tool_use' && block.name === replyToolName && !replyCalled) {
+                                    replyCalled = true;
+                                    // Persist the reply text to history so it appears in chat history API
+                                    const replyText = typeof block.input?.['text'] === 'string' ? block.input['text'].trim() : '';
+                                    if (replyText) {
+                                        const channelSrc = this.channelSourceMap.get(mapKey) ?? 'telegram';
+                                        this.historyDb.insertMessage({
+                                            chatId: `${channelSrc}-${mapKey}`,
+                                            sessionId: actualSessionId,
+                                            source: channelSrc,
+                                            role: 'assistant',
+                                            content: replyText,
+                                            ts: Date.now(),
+                                        });
+                                    }
+                                }
+                            }
+                        }
+                    }
+                    if (obj['type'] === 'result') {
+                        proc.setProcessing(false);
+                        // Telegram: accumulate image size via stat of local file (FIFO, one per turn)
+                        const queue = this.pendingImagePaths.get(mapKey);
+                        const imgPath = queue?.shift();
+                        if (queue?.length === 0)
+                            this.pendingImagePaths.delete(mapKey);
+                        if (imgPath) {
+                            this.statQueue = this.statQueue.then(async () => {
+                                try {
+                                    const stats = await fsPromises.stat(imgPath);
+                                    const prev = this.imageSizePerChat.get(mapKey) ?? 0;
+                                    const next = prev + stats.size;
+                                    this.imageSizePerChat.set(mapKey, next);
+                                    if (next >= exports.MAX_IMAGE_SIZE_BYTES) {
+                                        this.imageSizePerChat.delete(mapKey);
+                                        void this.triggerSummaryAndRestart(mapKey, actualSessionId, proc);
+                                    }
+                                }
+                                catch (err) {
+                                    this.logger.warn('Failed to stat image', { path: imgPath, error: err instanceof Error ? err.message : String(err) });
+                                }
+                            });
+                        }
+                        // Forward result text when agent did NOT call reply tool (fallback path).
+                        // If the agent already called the reply tool, skip result forwarding to avoid
+                        // sending a duplicate message to the channel.
+                        // Skip forwarding when session is in query mode (internal image summary request).
+                        const resultText = typeof obj['result'] === 'string' ? obj['result'] : '';
+                        if (resultText.trim() && !proc.queryMode && !replyCalled) {
+                            const text = resultText.trim();
+                            const channelSrcForResult = this.channelSourceMap.get(mapKey) ?? 'telegram';
+                            // Persist assistant reply to permanent history DB
+                            this.historyDb.insertMessage({
+                                chatId: `${channelSrcForResult}-${mapKey}`,
+                                sessionId: actualSessionId,
+                                source: channelSrcForResult,
+                                role: 'assistant',
+                                content: text,
+                                ts: Date.now(),
+                            });
+                            // Forward to channel
+                            if (channelSrcForResult !== 'discord' && (0, markdown_1.hasMarkdown)(text)) {
+                                this.writeAutoForward(mapKey, (0, markdown_1.toTelegramHtml)(text), 'html');
+                            }
+                            else {
+                                this.writeAutoForward(mapKey, text);
+                            }
+                        }
+                        replyCalled = false; // reset for next turn
+                        // Delay typing done — agent may continue with more work
+                        typingDoneTimer = setTimeout(() => {
+                            this.writeTypingDone(mapKey);
+                            typingDoneTimer = null;
+                        }, TYPING_DONE_DELAY_MS);
+                    }
+                }
+                catch { /* non-JSON */ }
+            });
+            // Track token usage and persist to session meta
+            // Use actualSessionId (captured at spawn time) — NOT getActiveSessionId() —
+            // so tokens are attributed to the session that owns this process.
+            proc.on('tokenUsage', async ({ inputTokens, totalTokens }) => {
+                try {
+                    const ch = this.channelFor(mapKey);
+                    const index = await this.sessionStore.listSessions(this.agentConfig.id, mapKey, ch);
+                    const meta = index.sessions.find(s => s.id === actualSessionId);
+                    const current = meta?.totalTokensUsed ?? 0;
+                    await this.sessionStore.updateSessionMeta(this.agentConfig.id, mapKey, actualSessionId, {
+                        totalTokensUsed: current + totalTokens,
+                        lastInputTokens: inputTokens,
+                    }, ch);
+                }
+                catch {
+                    // Non-fatal — token tracking is best-effort
+                }
+            });
+            // Persist spawn context (loaded vs archived message counts).
+            // Read from property instead of event — the event fired during start() before
+            // listeners were registered, causing a race condition.
+            if (proc.spawnContext) {
+                this.sessionStore.updateSessionMeta(this.agentConfig.id, mapKey, actualSessionId, {
+                    loadedAtSpawn: proc.spawnContext.loadedAtSpawn,
+                    archivedCount: proc.spawnContext.archivedCount,
+                    messageCountAtSpawn: proc.spawnContext.messageCountAtSpawn,
+                }, this.channelFor(mapKey)).catch(() => { });
+            }
+            // Clean up pending typing-done timer when session stops
+            proc.once('exit', () => {
+                proc.setProcessing(false);
+                if (typingDoneTimer) {
+                    clearTimeout(typingDoneTimer);
+                    typingDoneTimer = null;
+                }
+                this.writeTypingDone(mapKey);
+            });
+            // Deferred restart: stop session after its current turn completes
+            proc.once('deferredRestartReady', async () => {
+                this.logger.info('Deferred restart: stopping session after turn completed', { mapKey });
+                await proc.stop();
+                this.sessions.delete(mapKey);
+            });
+        }
+        this.sessions.set(mapKey, proc);
+        if (source === 'telegram' || source === 'discord') {
+            this.channelSourceMap.set(mapKey, source);
+        }
+        this.logger.info('Spawned session', {
+            mapKey,
+            actualSessionId,
+            source,
+            total: this.sessions.size,
+        });
+        return proc;
+    }
+    /**
+     * Returns true if the message content is a session management command.
+     */
+    isSessionCommand(content) {
+        return /^\/sessions?\b|^\/new(\s|$)|^\/clear\b|^\/compact\b|^\/rename(\s|$)|^\/stop(\s|$)/.test(content);
+    }
+    /**
+     * Dispatch a session management command to the appropriate handler.
+     */
+    async handleSessionCommand(chatId, content) {
+        const agentId = this.agentConfig.id;
+        if (content.startsWith('/sessions')) {
+            await this.handleCommandSessions(agentId, chatId);
+        }
+        else if (content.startsWith('/session') && !content.startsWith('/sessions')) {
+            await this.handleCommandSessionInfo(agentId, chatId);
+        }
+        else if (content.startsWith('/new')) {
+            const name = content.replace('/new', '').trim() || undefined;
+            await this.handleCommandNew(agentId, chatId, name);
+        }
+        else if (content.startsWith('/clear')) {
+            await this.handleCommandClear(agentId, chatId);
+        }
+        else if (content.startsWith('/compact')) {
+            await this.handleCommandCompact(agentId, chatId);
+        }
+        else if (content.startsWith('/rename')) {
+            const name = content.replace('/rename', '').trim();
+            await this.handleCommandRename(agentId, chatId, name);
+        }
+        else if (content.startsWith('/stop')) {
+            await this.handleCommandStop(chatId);
+        }
+    }
+    /**
+     * /sessions — list all sessions for this chat.
+     */
+    async handleCommandSessions(agentId, chatId) {
+        const index = await this.sessionStore.listSessions(agentId, chatId, this.channelFor(chatId));
+        const lines = [`Sessions (${agentId})`, ''];
+        for (const s of index.sessions) {
+            const isActive = s.id === index.activeSessionId;
+            const indicator = isActive ? '🟢 ' : '   ';
+            const age = this.formatAge(s.lastActive);
+            lines.push(`${indicator}${isActive ? `**${s.name}**` : s.name}`);
+            lines.push(`  ${s.messageCount} messages · last active ${age}`);
+            lines.push('');
+        }
+        lines.push('Use /new [name] to create a new session');
+        this.writeAutoForward(chatId, lines.join('\n'));
+    }
+    /**
+     * /session — show info about the current active session.
+     */
+    async handleCommandSessionInfo(agentId, chatId) {
+        const index = await this.sessionStore.listSessions(agentId, chatId, this.channelFor(chatId));
+        const meta = index.sessions.find(s => s.id === index.activeSessionId);
+        if (!meta) {
+            this.writeAutoForward(chatId, 'No active session found.');
+            return;
+        }
+        const availableModels = this.gatewayConfig.gateway.models ?? DEFAULT_MODELS;
+        const modelConfig = availableModels.find(m => m.id === this.agentConfig.claude.model);
+        const contextWindow = modelConfig?.contextWindow ?? 200000;
+        const contextTokens = meta.lastInputTokens ?? 0;
+        const usedPct = Math.round((contextTokens / contextWindow) * 100);
+        let msgs;
+        if (meta.messageCount <= 0) {
+            msgs = 'No messages yet';
+        }
+        else if ((meta.archivedCount ?? 0) > 0 && meta.loadedAtSpawn != null && meta.messageCountAtSpawn != null) {
+            const newMessagesSinceSpawn = meta.messageCount - meta.messageCountAtSpawn;
+            const inContext = meta.loadedAtSpawn + Math.max(0, newMessagesSinceSpawn);
+            msgs = `${meta.messageCount} (${inContext} in context / ${meta.archivedCount} archived)`;
+        }
+        else {
+            msgs = `${meta.messageCount}`;
+        }
+        const contextLine = `${usedPct}%`;
+        const lines = [
+            `📌 Current Session: ${meta.name}`,
+            `<code>${index.activeSessionId}</code>`,
+            '',
+            `📥 Messages: ${msgs}`,
+            `👉 Context: ${contextLine}`,
+        ];
+        if (usedPct >= 80) {
+            lines.push('', '💡 Near limit — consider /compact');
+        }
+        lines.push('', 'Commands: /sessions /new /rename /clear /compact');
+        const info = lines.join('\n');
+        this.writeAutoForward(chatId, info, 'html');
+    }
+    /**
+     * /new [name] — create a new session and switch to it.
+     */
+    async handleCommandNew(agentId, chatId, name) {
+        const newMeta = await this.sessionStore.createTelegramSession(agentId, chatId, name, this.channelFor(chatId));
+        await this.switchSession(chatId, newMeta.id);
+        this.writeAutoForward(chatId, `✅ New session created: "${newMeta.name}"\nNow chatting in a fresh context. Use /sessions to switch back.`);
+    }
+    /**
+     * /rename <name> — rename the current session.
+     */
+    async handleCommandRename(agentId, chatId, name) {
+        if (!name) {
+            this.writeAutoForward(chatId, '⚠️ Usage: /rename <new name>\nExample: /rename Design review');
+            return;
+        }
+        const sessionId = await this.sessionStore.getActiveSessionId(agentId, chatId, this.channelFor(chatId));
+        await this.sessionStore.updateSessionMeta(agentId, chatId, sessionId, { name }, this.channelFor(chatId));
+        this.writeAutoForward(chatId, `✅ Session renamed to "${name}"`);
+    }
+    /**
+     * /stop — interrupt the in-flight turn for this chat by sending SIGINT to the subprocess.
+     * Leaves session history and metadata intact. Queued messages still process afterwards.
+     */
+    async handleCommandStop(chatId) {
+        const session = this.sessions.get(chatId);
+        const stopped = session ? session.interrupt() : false;
+        this.writeAutoForward(chatId, stopped ? 'Stopped.' : 'No turn in progress.');
+    }
+    /**
+     * /clear — clear history of the current session and restart the process.
+     * Also clears the permanent history DB and media files for this chat.
+     */
+    async handleCommandClear(agentId, chatId) {
+        const ch = this.channelFor(chatId);
+        const sessionId = await this.sessionStore.getActiveSessionId(agentId, chatId, ch);
+        // Clear messages and reset all metadata in-place (preserves session ID and name)
+        await this.sessionStore.clearTelegramSessionHistory(agentId, chatId, sessionId, ch);
+        await this.sessionStore.updateSessionMeta(agentId, chatId, sessionId, {
+            totalTokensUsed: 0,
+            lastInputTokens: 0,
+            archivedCount: 0,
+            loadedAtSpawn: undefined,
+            messageCountAtSpawn: undefined,
+        }, ch);
+        // Clear permanent history DB for this chat
+        const historyChatId = `${ch}-${chatId}`;
+        this.historyDb.clearChat(historyChatId);
+        // Delete persisted media files for this chat
+        media_store_1.MediaStore.clearChatMedia(this.agentsBaseDir, agentId, historyChatId);
+        // Kill old process so next message spawns fresh
+        this.restartProcess(chatId).catch(() => { });
+    }
+    /**
+     * /compact — summarise old history and keep only recent messages.
+     */
+    async handleCommandCompact(agentId, chatId) {
+        const ch = this.channelFor(chatId);
+        const sessionId = await this.sessionStore.getActiveSessionId(agentId, chatId, ch);
+        const index = await this.sessionStore.listSessions(agentId, chatId, ch);
+        const meta = index.sessions.find(s => s.id === sessionId);
+        const name = meta?.name ?? 'Session';
+        const availableModels = this.gatewayConfig.gateway.models ?? DEFAULT_MODELS;
+        const modelConfig = availableModels.find(m => m.id === this.agentConfig.claude.model);
+        const contextWindow = modelConfig?.contextWindow ?? 200000;
+        this.writeAutoForward(chatId, `⏳ Compacting session "${name}"...`);
+        try {
+            const compactor = new compactor_1.SessionCompactor(this.sessionStore);
+            const result = await compactor.compact(agentId, chatId, sessionId, this.agentConfig.claude.model, contextWindow, ch);
+            await this.sessionStore.updateSessionMeta(agentId, chatId, sessionId, {
+                loadedAtSpawn: undefined,
+                archivedCount: undefined,
+                messageCountAtSpawn: undefined,
+            }, ch);
+            await this.restartProcess(chatId);
+            const summary = [
+                `✅ Session compacted`,
+                '',
+                `Before: ${result.beforeMessages} messages (~${result.beforeTokens.toLocaleString()} tokens)  →  ${result.contextPctBefore}% of context`,
+                `After:  ${result.afterMessages} messages (~${result.afterTokens.toLocaleString()} tokens)   →  ${result.contextPctAfter}% of context`,
+                `Reduced by: ${result.reductionPct}%`,
+                '',
+                'Summary preserved. Full history before compaction is archived.',
+            ].join('\n');
+            this.writeAutoForward(chatId, summary);
+        }
+        catch (err) {
+            if (err.name === 'NotEnoughMessagesError') {
+                this.writeAutoForward(chatId, `⚠️ ${err.message}`);
+            }
+            else {
+                this.logger.error('Compact failed', { error: err.message });
+                this.writeAutoForward(chatId, `❌ Compact failed: ${err.message}\n\nYour session history is unchanged.`);
+            }
+        }
+    }
+    /**
+     * Switch the active session for a chat: stop the existing process and update the store.
+     * The new process will be lazily spawned on the next incoming message.
+     */
+    async switchSession(chatId, newSessionId) {
+        const existing = this.sessions.get(chatId);
+        if (existing) {
+            await existing.stop();
+            this.sessions.delete(chatId);
+        }
+        await this.sessionStore.setActiveSession(this.agentConfig.id, chatId, newSessionId, this.channelFor(chatId));
+    }
+    /**
+     * Restart the process for a given chatId (stop + remove from map).
+     * The process will be lazily re-spawned on the next incoming message.
+     */
+    async restartProcess(chatId) {
+        const existing = this.sessions.get(chatId);
+        if (existing) {
+            await existing.stop();
+            this.sessions.delete(chatId);
+        }
+        // Process will be re-spawned on next incoming message
+    }
+    /**
+     * Stop all idle session subprocesses so they re-spawn with the latest
+     * system prompt on the next incoming message.
+     *
+     * - "Idle" = no activity for {@link IDLE_THRESHOLD_MS}ms (enough to exclude an in-flight turn).
+     * - Busy sessions are left alone; they will be picked up by the idle cleaner
+     *   (every 5m) or naturally on the next spawn after timeout.
+     * - Does NOT stop the receiver; incoming messages keep flowing.
+     *
+     * Used by the skills hot-reload path so that SKILL.md changes take effect
+     * without kicking users out of in-flight turns.
+     */
+    async restartOrDefer() {
+        let immediate = 0;
+        let deferred = 0;
+        const toStopNow = [];
+        for (const [id, proc] of this.sessions) {
+            if (proc.isProcessing) {
+                proc.markPendingRestart();
+                deferred++;
+            }
+            else {
+                toStopNow.push(id);
+            }
+        }
+        for (const id of toStopNow) {
+            const proc = this.sessions.get(id);
+            if (!proc)
+                continue;
+            await proc.stop();
+            this.sessions.delete(id);
+            immediate++;
+        }
+        this.logger.info('restartOrDefer: sessions restarted', { immediate, deferred });
+    }
+    /**
+     * Format a timestamp as a human-readable age string (e.g. "5m ago", "2h ago").
+     */
+    formatAge(ts) {
+        const diffMs = Date.now() - ts;
+        const diffMins = Math.floor(diffMs / 60000);
+        if (diffMins < 1)
+            return 'just now';
+        if (diffMins < 60)
+            return `${diffMins}m ago`;
+        const diffHours = Math.floor(diffMins / 60);
+        if (diffHours < 24)
+            return `${diffHours}h ago`;
+        const diffDays = Math.floor(diffHours / 24);
+        return `${diffDays}d ago`;
+    }
+    /**
+     * Write an error code to the typing signal directory so the receiver's
+     * typing loop can pick it up and notify the user via Telegram.
+     * Non-fatal: if the write fails the typing loop will stop via stalled timer.
+     */
+    getTypingDir(chatId) {
+        const channel = this.channelSourceMap.get(chatId) ?? 'telegram';
+        const stateDir = channel === 'discord' ? '.discord-state' : '.telegram-state';
+        return path.join(this.agentConfig.workspace, stateDir, 'typing');
+    }
+    writeTypingError(chatId, code) {
+        const typingDir = this.getTypingDir(chatId);
+        try {
+            fs.mkdirSync(typingDir, { recursive: true });
+            fs.writeFileSync(path.join(typingDir, `${chatId}.error`), code);
+        }
+        catch {
+            // Non-fatal — typing loop will stop via stalled timer instead
+        }
+    }
+    writeTypingDone(chatId) {
+        const typingDir = this.getTypingDir(chatId);
+        try {
+            fs.rmSync(path.join(typingDir, chatId), { force: true });
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+    async triggerSummaryAndRestart(chatId, sessionId, session) {
+        const IMAGE_CONTEXT_MARKER = '[Image Context Summary]';
+        try {
+            const prompt = [
+                'Briefly summarize each image you have seen in this conversation.',
+                'Format: "Image N: [1-2 sentence description]"',
+                'List every image separately.',
+            ].join(' ');
+            const description = await session.query(prompt);
+            if (description) {
+                const msg = {
+                    role: 'system',
+                    content: `${IMAGE_CONTEXT_MARKER}\n${description}`,
+                    ts: Date.now(),
+                };
+                await this.sessionStore.appendTelegramMessage(this.agentConfig.id, chatId, sessionId, msg, this.channelFor(chatId));
+            }
+        }
+        catch (err) {
+            this.logger.warn('Image context summary failed', { error: err instanceof Error ? err.message : String(err) });
+        }
+        this.pendingRestarts.add(chatId);
+    }
+    writeAutoForward(chatId, text, format = 'text') {
+        const typingDir = this.getTypingDir(chatId);
+        try {
+            fs.mkdirSync(typingDir, { recursive: true });
+            fs.writeFileSync(path.join(typingDir, `${chatId}.forward`), JSON.stringify({ text, format }));
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+    startIdleCleaner() {
+        this.idleCleanerTimer = setInterval(async () => {
+            for (const [id, proc] of this.sessions) {
+                if (proc.isIdle(this.idleTimeoutMs)) {
+                    this.logger.info('Stopping idle session', { sessionId: id });
+                    await proc.stop();
+                    this.sessions.delete(id);
+                }
+            }
+        }, 5 * 60 * 1000);
+    }
+    async start() {
+        this.stopping = false;
+        await this.startCallbackServer();
+        if (this.agentConfig.telegram?.botToken) {
+            this.receiver = new receiver_1.TelegramReceiver(this.agentConfig, this.callbackPort, this.gatewayConfig.gateway.logDir);
+            this.receiver.start();
+        }
+        if (this.agentConfig.discord?.botToken) {
+            this.discordReceiver = new receiver_2.DiscordReceiver(this.agentConfig, this.callbackPort, this.gatewayConfig.gateway.logDir);
+            this.discordReceiver.start();
+        }
+        this.startIdleCleaner();
+        this._startCleanupScheduler();
+        this.logger.info('AgentRunner started', { agentId: this.agentConfig.id });
+    }
+    startDiscordReceiver() {
+        if (this.discordReceiver?.isRunning())
+            return;
+        this.discordReceiver = new receiver_2.DiscordReceiver(this.agentConfig, this.callbackPort, this.gatewayConfig.gateway.logDir);
+        this.discordReceiver.start();
+        this.logger.info('DiscordReceiver hot-started', { agentId: this.agentConfig.id });
+    }
+    async stop() {
+        this.stopping = true;
+        if (this.idleCleanerTimer !== null) {
+            clearInterval(this.idleCleanerTimer);
+            this.idleCleanerTimer = null;
+        }
+        this.cancelCleanup?.();
+        this.cancelCleanup = null;
+        this.callbackServer?.close();
+        this.callbackServer = null;
+        this.receiver?.stop();
+        this.discordReceiver?.stop();
+        await Promise.all([...this.sessions.values()].map((s) => s.stop()));
+        this.sessions.clear();
+    }
+    _startCleanupScheduler() {
+        const gw = this.gatewayConfig.gateway;
+        const retentionDays = (0, cleanup_1.resolveRetentionDays)(this.agentConfig.history?.retentionDays, gw.history?.retentionDays);
+        const cleanupHour = gw.history?.cleanupHour ?? 0;
+        const cleanupTimezone = gw.history?.cleanupTimezone ?? 'UTC';
+        const agentMediaRoot = media_store_1.MediaStore.agentMediaRoot(this.agentsBaseDir, this.agentConfig.id);
+        const logPath = path.join(this.agentDir, 'cleanup.log');
+        this.cancelCleanup = (0, cleanup_1.scheduleCleanup)({
+            db: this.historyDb,
+            agentMediaRoot,
+            logPath,
+            retentionDays,
+            cleanupHour,
+            cleanupTimezone,
+        });
+    }
+    async restart() {
+        await this.stop();
+        this.stopping = false;
+        await this.start();
+    }
+    isRunning() {
+        return this.receiver?.isRunning() ?? false;
+    }
+    /**
+     * Send a message to an API session and wait for the response.
+     *
+     * - Spawns a new SessionProcess (source='api') if none exists for sessionId.
+     * - Rejects with code 'CONFLICT' if a prior request is still in-flight for this session.
+     * - Rejects with code 'TIMEOUT' if Claude does not respond within timeoutMs.
+     * - Appends user message and assistant reply to SessionStore for history persistence.
+     */
+    async sendApiMessage(sessionId, chatId, message, opts) {
+        if (this.pendingApiSessions.has(sessionId)) {
+            const err = Object.assign(new Error(`Session ${sessionId} already has a pending request`), { code: 'CONFLICT' });
+            throw err;
+        }
+        const session = await this.getOrSpawnSession(sessionId, 'api');
+        // Register session in api-{chatId} index.json on first use
+        const internalChatIdForSession = `api-${chatId}`;
+        await this.sessionStore.ensureApiSession(this.agentConfig.id, internalChatIdForSession, sessionId).catch((err) => {
+            this.logger.warn('Failed to register API session in index', { agentId: this.agentConfig.id, chatId, sessionId, error: err.message });
+        });
+        // Promote UI-uploaded files from staging to permanent per-session storage
+        const finalMediaFiles = opts.mediaFiles?.length
+            ? await promoteUiUploads(this.agentsBaseDir, this.agentConfig.id, sessionId, opts.mediaFiles, this.logger)
+            : undefined;
+        // Resolve media files to absolute paths for file-path based image passing
+        // (same pattern as Telegram — Claude Code reads files via Read tool instead of base64 inline)
+        const imagePaths = finalMediaFiles?.length ? this.resolveMediaPaths(finalMediaFiles) : [];
+        // Persist user message
+        const apiUserTs = Date.now();
+        await this.sessionStore
+            .appendMessage(this.agentConfig.id, sessionId, {
+            role: 'user',
+            content: message,
+            ts: apiUserTs,
+        })
+            .catch(() => { });
+        this.historyDb.insertMessage({
+            chatId: `api-${chatId}`,
+            sessionId,
+            source: 'api',
+            role: 'user',
+            content: message,
+            mediaFiles: finalMediaFiles?.length ? finalMediaFiles : undefined,
+            ts: apiUserTs,
+        });
+        this.pendingApiSessions.add(sessionId);
+        session.touch();
+        // Image paths only work when allowTools:true — Claude needs the Read tool to access them
+        const allowTools = opts.allowTools ?? false;
+        if (!allowTools && imagePaths.length) {
+            this.logger.warn('Images ignored: allowTools is false, Claude cannot use Read tool', { sessionId, imageCount: imagePaths.length });
+        }
+        const effectiveImagePaths = allowTools ? imagePaths : [];
+        const systemNote = buildApiSystemNote(allowTools, effectiveImagePaths.length ? effectiveImagePaths : undefined);
+        // Detect skill commands (same as channel message path)
+        const skillInvocation = (0, skills_1.detectSkillCommand)(message, this.skillRegistry);
+        if (skillInvocation) {
+            this.logger.info('Skill invoked via API', {
+                skill: skillInvocation.skillKey,
+                args: skillInvocation.args,
+                sessionId,
+            });
+        }
+        // Build channel XML with image_path attribute (like Telegram) for first image
+        const imageAttr = effectiveImagePaths.length ? ` image_path="${AgentRunner.escapeXmlAttr(effectiveImagePaths[0])}"` : '';
+        const channelXml = `<channel source="api" chat_id="${chatId}" session_id="${sessionId}" ts="${new Date().toISOString()}"${imageAttr}>\n` +
+            `${message}\n\n` +
+            `${systemNote}` +
+            `</channel>` +
+            (skillInvocation ? `\n${(0, skills_1.formatSkillContext)(skillInvocation)}` : '');
+        return new Promise((resolve, reject) => {
+            const buffer = [];
+            let quietTimer;
+            // Track partial message text for delta computation (--include-partial-messages)
+            let lastPartialText = '';
+            const done = (result) => {
+                cleanup();
+                // Persist assistant reply
+                if (result.trim()) {
+                    const apiAssistantTs = Date.now();
+                    this.sessionStore
+                        .appendMessage(this.agentConfig.id, sessionId, {
+                        role: 'assistant',
+                        content: result.trim(),
+                        ts: apiAssistantTs,
+                    })
+                        .catch(() => { });
+                    this.historyDb.insertMessage({
+                        chatId: `api-${chatId}`,
+                        sessionId,
+                        source: 'api',
+                        role: 'assistant',
+                        content: result.trim(),
+                        ts: apiAssistantTs,
+                    });
+                }
+                resolve(result.trim());
+            };
+            const fail = (err) => {
+                cleanup();
+                reject(err);
+            };
+            const cleanup = () => {
+                clearTimeout(globalTimer);
+                if (quietTimer)
+                    clearTimeout(quietTimer);
+                session.off('output', onOutput);
+                this.pendingApiSessions.delete(sessionId);
+            };
+            const resetQuiet = () => {
+                if (quietTimer)
+                    clearTimeout(quietTimer);
+                quietTimer = setTimeout(() => done(buffer.join('')), 2000);
+            };
+            const onOutput = (line) => {
+                try {
+                    const obj = JSON.parse(line);
+                    // Handle partial assistant messages (from --include-partial-messages)
+                    if (obj['type'] === 'assistant') {
+                        const msg = obj['message'];
+                        if (Array.isArray(msg?.content)) {
+                            let fullText = '';
+                            for (const block of msg.content) {
+                                if (block.type === 'text' && block.text)
+                                    fullText += block.text;
+                            }
+                            if (fullText.length > lastPartialText.length) {
+                                buffer.push(fullText.slice(lastPartialText.length));
+                                resetQuiet();
+                            }
+                            lastPartialText = fullText;
+                        }
+                    }
+                    // Standalone text delta
+                    if (obj['type'] === 'text') {
+                        const text = obj['text'] ?? '';
+                        if (text) {
+                            buffer.push(text);
+                            resetQuiet();
+                        }
+                    }
+                    // result event = end of turn
+                    if (obj['type'] === 'result') {
+                        session.setProcessing(false);
+                        const resultText = obj['result'] ?? buffer.join('');
+                        done(resultText);
+                    }
+                }
+                catch {
+                    /* non-JSON stdout line */
+                }
+            };
+            const globalTimer = setTimeout(() => {
+                session.setProcessing(false);
+                fail(Object.assign(new Error('Agent response timeout'), { code: 'TIMEOUT' }));
+            }, opts.timeoutMs);
+            session.on('output', onOutput);
+            session.setProcessing(true);
+            session.sendMessage(channelXml);
+            // Do NOT call resetQuiet() here — the quiet timer should only start
+            // after the first output line arrives, otherwise it fires before the
+            // subprocess has had time to respond (especially on first turn).
+        });
+    }
+    /**
+     * Send a message to an API session and stream back events via callbacks.
+     *
+     * Returns a cleanup function that removes all listeners and frees the session slot.
+     * The caller MUST invoke cleanup on client disconnect or when done.
+     */
+    async sendApiMessageStream(sessionId, chatId, message, callbacks, opts) {
+        if (this.pendingApiSessions.has(sessionId)) {
+            const err = Object.assign(new Error(`Session ${sessionId} already has a pending request`), { code: 'CONFLICT' });
+            throw err;
+        }
+        const session = await this.getOrSpawnSession(sessionId, 'api');
+        // Register session in api-{chatId} index.json on first use
+        const internalChatIdStream = `api-${chatId}`;
+        await this.sessionStore.ensureApiSession(this.agentConfig.id, internalChatIdStream, sessionId).catch((err) => {
+            this.logger.warn('Failed to register API session in index', { agentId: this.agentConfig.id, chatId, sessionId, error: err.message });
+        });
+        // Promote UI-uploaded files from staging to permanent per-session storage
+        const finalMediaFilesStream = opts.mediaFiles?.length
+            ? await promoteUiUploads(this.agentsBaseDir, this.agentConfig.id, sessionId, opts.mediaFiles, this.logger)
+            : undefined;
+        // Resolve media files to absolute paths for file-path based image passing
+        const imagePathsStream = finalMediaFilesStream?.length ? this.resolveMediaPaths(finalMediaFilesStream) : [];
+        // Persist user message
+        const streamUserTs = Date.now();
+        await this.sessionStore
+            .appendMessage(this.agentConfig.id, sessionId, {
+            role: 'user',
+            content: message,
+            ts: streamUserTs,
+        })
+            .catch(() => { });
+        this.historyDb.insertMessage({
+            chatId: `api-${chatId}`,
+            sessionId,
+            source: 'api',
+            role: 'user',
+            content: message,
+            mediaFiles: finalMediaFilesStream?.length ? finalMediaFilesStream : undefined,
+            ts: streamUserTs,
+        });
+        this.pendingApiSessions.add(sessionId);
+        session.touch();
+        const buffer = [];
+        let settled = false;
+        // Track partial message text for delta computation (--include-partial-messages)
+        let lastPartialText = '';
+        const done = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            // Persist assistant reply
+            if (result.trim()) {
+                const streamAssistantTs = Date.now();
+                this.sessionStore
+                    .appendMessage(this.agentConfig.id, sessionId, {
+                    role: 'assistant',
+                    content: result.trim(),
+                    ts: streamAssistantTs,
+                })
+                    .catch(() => { });
+                this.historyDb.insertMessage({
+                    chatId: `api-${chatId}`,
+                    sessionId,
+                    source: 'api',
+                    role: 'assistant',
+                    content: result.trim(),
+                    ts: streamAssistantTs,
+                });
+            }
+            callbacks.onDone(result.trim());
+        };
+        const fail = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            callbacks.onError(err);
+        };
+        const cleanup = () => {
+            clearTimeout(globalTimer);
+            session.off('output', onOutput);
+            this.pendingApiSessions.delete(sessionId);
+        };
+        const onOutput = (line) => {
+            try {
+                const obj = JSON.parse(line);
+                // Partial assistant message (from --include-partial-messages)
+                // Contains cumulative text; compute delta and emit as text_delta
+                if (obj['type'] === 'assistant') {
+                    const msg = obj['message'];
+                    if (Array.isArray(msg?.content)) {
+                        let fullText = '';
+                        for (const block of msg.content) {
+                            if (block.type === 'text' && block.text)
+                                fullText += block.text;
+                        }
+                        if (fullText.length > lastPartialText.length) {
+                            const delta = fullText.slice(lastPartialText.length);
+                            buffer.push(delta);
+                            callbacks.onChunk({ type: 'text_delta', text: delta });
+                        }
+                        lastPartialText = fullText;
+                    }
+                }
+                // Standalone text delta (legacy format)
+                if (obj['type'] === 'text') {
+                    const text = obj['text'] ?? '';
+                    if (text) {
+                        buffer.push(text);
+                        callbacks.onChunk({ type: 'text_delta', text });
+                    }
+                }
+                // stream_event from --output-format stream-json
+                // Format: {"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"text_delta","text":"..."}}}
+                if (obj['type'] === 'stream_event') {
+                    const event = obj['event'];
+                    if (event?.['type'] === 'content_block_delta') {
+                        const delta = event['delta'];
+                        if (delta?.['type'] === 'text_delta' && typeof delta['text'] === 'string' && delta['text']) {
+                            buffer.push(delta['text']);
+                            // Update lastPartialText so the final 'assistant' message won't re-send the full text
+                            lastPartialText += delta['text'];
+                            callbacks.onChunk({ type: 'text_delta', text: delta['text'] });
+                        }
+                    }
+                }
+                // Text from delta field (other formats)
+                if (obj['type'] !== 'assistant' && obj['type'] !== 'text' && obj['type'] !== 'result' && obj['type'] !== 'stream_event') {
+                    const deltaText = obj['delta']?.['text'];
+                    if (deltaText) {
+                        buffer.push(deltaText);
+                        callbacks.onChunk({ type: 'text_delta', text: deltaText });
+                    }
+                }
+                // Tool use
+                if (obj['type'] === 'tool_use') {
+                    callbacks.onChunk({
+                        type: 'tool_use',
+                        name: obj['name'] ?? '',
+                        id: obj['id'] ?? '',
+                    });
+                }
+                // Thinking
+                if (obj['type'] === 'thinking') {
+                    callbacks.onChunk({
+                        type: 'thinking',
+                        text: obj['text'] ?? '',
+                    });
+                }
+                // Result = end of turn
+                if (obj['type'] === 'result') {
+                    session.setProcessing(false);
+                    lastPartialText = ''; // reset for next turn
+                    const resultText = obj['result'] ?? buffer.join('');
+                    done(resultText);
+                }
+            }
+            catch {
+                /* non-JSON stdout line */
+            }
+        };
+        const globalTimer = setTimeout(() => {
+            session.setProcessing(false);
+            fail(Object.assign(new Error('Agent response timeout'), { code: 'TIMEOUT' }));
+        }, opts.timeoutMs);
+        session.on('output', onOutput);
+        // Image paths only work when allowTools:true — Claude needs the Read tool to access them
+        const allowToolsStream = opts.allowTools ?? false;
+        if (!allowToolsStream && imagePathsStream.length) {
+            this.logger.warn('Images ignored: allowTools is false, Claude cannot use Read tool', { sessionId, imageCount: imagePathsStream.length });
+        }
+        const effectiveImagePathsStream = allowToolsStream ? imagePathsStream : [];
+        const systemNote = buildApiSystemNote(allowToolsStream, effectiveImagePathsStream.length ? effectiveImagePathsStream : undefined);
+        // Detect skill commands (same as channel message path)
+        const skillInvocationStream = (0, skills_1.detectSkillCommand)(message, this.skillRegistry);
+        if (skillInvocationStream) {
+            this.logger.info('Skill invoked via API stream', {
+                skill: skillInvocationStream.skillKey,
+                args: skillInvocationStream.args,
+                sessionId,
+            });
+        }
+        // Build channel XML with image_path attribute (like Telegram) for first image
+        const imageAttrStream = effectiveImagePathsStream.length ? ` image_path="${AgentRunner.escapeXmlAttr(effectiveImagePathsStream[0])}"` : '';
+        const channelXml = `<channel source="api" chat_id="${chatId}" session_id="${sessionId}" ts="${new Date().toISOString()}"${imageAttrStream}>\n` +
+            `${message}\n\n` +
+            systemNote +
+            `</channel>` +
+            (skillInvocationStream ? `\n${(0, skills_1.formatSkillContext)(skillInvocationStream)}` : '');
+        session.setProcessing(true);
+        session.sendMessage(channelXml);
+        // Return cleanup function for client disconnect
+        return () => {
+            if (!settled) {
+                settled = true;
+                cleanup();
+            }
+        };
+    }
+    /**
+     * Check if a session has a pending API request (for preflight conflict check).
+     */
+    hasActiveApiSession(sessionId) {
+        return this.pendingApiSessions.has(sessionId);
+    }
+    getAgentsBaseDir() {
+        return this.agentsBaseDir;
+    }
+    getAgentDir() {
+        return this.agentDir;
+    }
+    getHistoryDb() {
+        return this.historyDb;
+    }
+    getAllSessionNames() {
+        return this.sessionStore.getAllSessionNames(this.agentConfig.id);
+    }
+    async listSessionsForChat(chatId, channel) {
+        return this.sessionStore.listSessions(this.agentConfig.id, chatId, channel);
+    }
+    async executeApiCommand(sessionId, chatId, command) {
+        const agentId = this.agentConfig.id;
+        const internalChatId = `api-${chatId}`;
+        if (command === '/model') {
+            return { model: this.agentConfig.claude.model };
+        }
+        if (command === '/stop') {
+            const session = this.sessions.get(sessionId);
+            const stopped = session ? session.interrupt() : false;
+            return { stopped };
+        }
+        if (command === '/restart') {
+            this.restartProcess(sessionId).catch(() => { });
+            return { restarting: true };
+        }
+        if (command === '/session') {
+            const index = await this.sessionStore.listSessions(agentId, internalChatId, 'api').catch(() => null);
+            const meta = index?.sessions.find((s) => s.id === sessionId);
+            if (!meta)
+                return { sessionId, sessionName: null, messageCount: 0, archivedCount: 0, contextUsedPct: 0, model: this.agentConfig.claude.model };
+            const availableModels = this.gatewayConfig.gateway.models ?? DEFAULT_MODELS;
+            const modelConfig = availableModels.find((m) => m.id === this.agentConfig.claude.model);
+            const contextWindow = modelConfig?.contextWindow ?? 200000;
+            const contextUsedPct = Math.round(((meta.lastInputTokens ?? 0) / contextWindow) * 100);
+            return {
+                sessionId,
+                sessionName: meta.name,
+                messageCount: meta.messageCount,
+                archivedCount: meta.archivedCount ?? 0,
+                contextUsedPct,
+                model: this.agentConfig.claude.model,
+            };
+        }
+        if (command === '/clear') {
+            const ch = 'api';
+            await this.sessionStore.clearTelegramSessionHistory(agentId, internalChatId, sessionId, ch);
+            await this.sessionStore.updateSessionMeta(agentId, internalChatId, sessionId, {
+                totalTokensUsed: 0,
+                lastInputTokens: 0,
+                archivedCount: 0,
+                loadedAtSpawn: undefined,
+                messageCountAtSpawn: undefined,
+            }, ch);
+            const mediaPaths = this.historyDb.clearSession(internalChatId, sessionId);
+            media_store_1.MediaStore.deleteMediaFiles(this.agentsBaseDir, agentId, mediaPaths);
+            this.restartProcess(sessionId).catch(() => { });
+            return { success: true };
+        }
+        if (command === '/compact') {
+            const ch = 'api';
+            const availableModels = this.gatewayConfig.gateway.models ?? DEFAULT_MODELS;
+            const modelConfig = availableModels.find((m) => m.id === this.agentConfig.claude.model);
+            const contextWindow = modelConfig?.contextWindow ?? 200000;
+            const compactor = new compactor_1.SessionCompactor(this.sessionStore);
+            const result = await compactor.compact(agentId, internalChatId, sessionId, this.agentConfig.claude.model, contextWindow, ch);
+            await this.sessionStore.updateSessionMeta(agentId, internalChatId, sessionId, {
+                loadedAtSpawn: undefined,
+                archivedCount: undefined,
+                messageCountAtSpawn: undefined,
+            }, ch);
+            await this.restartProcess(sessionId);
+            return { success: true, keptMessages: result.afterMessages, archivedMessages: result.beforeMessages - result.afterMessages };
+        }
+        throw new Error(`Unknown command: ${command}`);
+    }
+    async setModel(newModel) {
+        const availableModels = this.gatewayConfig.gateway.models ?? DEFAULT_MODELS;
+        if (!availableModels.find((m) => m.id === newModel)) {
+            throw Object.assign(new Error(`Unknown model: ${newModel}`), { code: 'UNKNOWN_MODEL' });
+        }
+        this.agentConfig.claude.model = newModel;
+        try {
+            this.persistModelToConfig(newModel);
+        }
+        catch (err) {
+            this.logger.error('Failed to persist model to config', { error: err.message });
+        }
+    }
+    async listApiSessions(chatId) {
+        return this.sessionStore.listSessions(this.agentConfig.id, `api-${chatId}`, 'api');
+    }
+    async createApiSession(chatId, prompt, name) {
+        let sessionName = name;
+        if (!sessionName && prompt) {
+            try {
+                const { execFile } = await Promise.resolve().then(() => __importStar(require('child_process')));
+                const { promisify } = await Promise.resolve().then(() => __importStar(require('util')));
+                const execFileAsync = promisify(execFile);
+                const titlePrompt = `Summarise in 3-5 words as a session title (no punctuation, no quotes): ${prompt}`;
+                const { stdout } = await execFileAsync('claude', ['-p', titlePrompt, '--output-format', 'text', '--model', 'claude-haiku-4-5-20251001'], { timeout: 15000, encoding: 'utf-8' });
+                sessionName = stdout.trim().slice(0, 60) || undefined;
+            }
+            catch {
+                sessionName = undefined;
+            }
+        }
+        return this.sessionStore.createTelegramSession(this.agentConfig.id, `api-${chatId}`, sessionName, 'api');
+    }
+    async getApiSessionInfo(chatId, sessionId) {
+        const index = await this.sessionStore.listSessions(this.agentConfig.id, `api-${chatId}`, 'api').catch(() => null);
+        const meta = index?.sessions.find((s) => s.id === sessionId);
+        if (!meta)
+            return null;
+        const availableModels = this.gatewayConfig.gateway.models ?? DEFAULT_MODELS;
+        const modelConfig = availableModels.find((m) => m.id === this.agentConfig.claude.model);
+        const contextWindow = modelConfig?.contextWindow ?? 200000;
+        const contextUsedPct = Math.round(((meta.lastInputTokens ?? 0) / contextWindow) * 100);
+        return {
+            sessionId: meta.id,
+            sessionName: meta.name,
+            messageCount: meta.messageCount,
+            archivedCount: meta.archivedCount ?? 0,
+            contextUsedPct,
+            model: this.agentConfig.claude.model,
+        };
+    }
+    async renameApiSession(chatId, sessionId, sessionName) {
+        await this.sessionStore.updateSessionMeta(this.agentConfig.id, `api-${chatId}`, sessionId, { name: sessionName }, 'api');
+    }
+    async deleteApiSession(chatId, sessionId) {
+        await this.sessionStore.deleteTelegramSession(this.agentConfig.id, `api-${chatId}`, sessionId, 'api');
+    }
+    /**
+     * Send a message into an existing channel session (cross-channel continuation from UI).
+     * The session process receives full history context from the session JSON (Layer 1).
+     * The reply is streamed back via SSE callbacks and persisted to history DB.
+     */
+    async sendMessageToSession(rawChatId, channel, sessionId, message, senderName, callbacks, opts) {
+        // Ensure the session process uses the correct channel source
+        this.channelSourceMap.set(rawChatId, channel);
+        const session = await this.getOrSpawnSession(rawChatId, channel, sessionId);
+        // Persist user message (Layer 1 session JSON + Layer 2 history DB)
+        const uiUserTs = Date.now();
+        await this.sessionStore.appendTelegramMessage(this.agentConfig.id, rawChatId, sessionId, {
+            role: 'user',
+            content: message,
+            ts: uiUserTs,
+        }, channel).catch(() => { });
+        this.historyDb.insertMessage({
+            chatId: `${channel}-${rawChatId}`,
+            sessionId,
+            source: 'ui',
+            role: 'user',
+            content: message,
+            senderName,
+            ts: uiUserTs,
+        });
+        const buffer = [];
+        let settled = false;
+        let lastPartialText = '';
+        const done = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if (result.trim()) {
+                const uiAssistantTs = Date.now();
+                this.sessionStore.appendTelegramMessage(this.agentConfig.id, rawChatId, sessionId, {
+                    role: 'assistant',
+                    content: result.trim(),
+                    ts: uiAssistantTs,
+                }, channel).catch(() => { });
+                this.historyDb.insertMessage({
+                    chatId: `${channel}-${rawChatId}`,
+                    sessionId,
+                    source: channel,
+                    role: 'assistant',
+                    content: result.trim(),
+                    ts: uiAssistantTs,
+                });
+            }
+            callbacks.onDone(result.trim());
+        };
+        const fail = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            callbacks.onError(err);
+        };
+        let globalTimer;
+        const cleanup = () => {
+            if (globalTimer)
+                clearTimeout(globalTimer);
+            session.off('output', onOutput);
+        };
+        const onOutput = (line) => {
+            try {
+                const obj = JSON.parse(line);
+                if (obj['type'] === 'assistant') {
+                    const msg = obj['message'];
+                    if (Array.isArray(msg?.content)) {
+                        let fullText = '';
+                        for (const block of msg.content) {
+                            if (block.type === 'text' && block.text)
+                                fullText += block.text;
+                        }
+                        if (fullText.length > lastPartialText.length) {
+                            const delta = fullText.slice(lastPartialText.length);
+                            buffer.push(delta);
+                            callbacks.onChunk({ type: 'text_delta', text: delta });
+                        }
+                        lastPartialText = fullText;
+                    }
+                }
+                if (obj['type'] === 'text') {
+                    const text = obj['text'] ?? '';
+                    if (text) {
+                        buffer.push(text);
+                        callbacks.onChunk({ type: 'text_delta', text });
+                    }
+                }
+                if (obj['type'] === 'result') {
+                    session.setProcessing(false);
+                    const resultText = obj['result'] ?? buffer.join('');
+                    done(resultText);
+                }
+            }
+            catch { /* non-JSON */ }
+        };
+        globalTimer = setTimeout(() => {
+            session.setProcessing(false);
+            fail(Object.assign(new Error('Agent response timeout'), { code: 'TIMEOUT' }));
+        }, opts.timeoutMs);
+        session.on('output', onOutput);
+        const channelXml = `<channel source="ui" chat_id="${AgentRunner.escapeXmlAttr(rawChatId)}" session_id="${AgentRunner.escapeXmlAttr(sessionId)}" ` +
+            `user="${AgentRunner.escapeXmlAttr(senderName ?? 'ui')}" ts="${new Date().toISOString()}">\n${message}\n</channel>`;
+        session.setProcessing(true);
+        session.sendMessage(channelXml);
+        return () => {
+            if (!settled) {
+                settled = true;
+                cleanup();
+            }
+        };
+    }
+    /**
+     * Expose the callback server port for integration tests that need to simulate
+     * incoming Telegram messages by POSTing directly to the channel endpoint.
+     */
+    getCallbackPort() {
+        return this.callbackPort;
+    }
+    /**
+     * Send a message to all active sessions.
+     * Used for heartbeat/cron tasks delivered out-of-band.
+     *
+     * If no Telegram sessions are active, a transient `__heartbeat__` API session is
+     * spawned so that CronScheduler tasks can always run regardless of active user sessions.
+     */
+    sendMessage(message) {
+        if (this.sessions.size === 0) {
+            // No active user sessions — spawn a shared heartbeat session so the prompt
+            // reaches a subprocess and output events fire for CronScheduler/tests.
+            this.getOrSpawnSession('__heartbeat__', 'api')
+                .then((session) => {
+                session.sendMessage(message);
+                session.touch();
+            })
+                .catch((err) => this.logger.error('sendMessage failed to spawn heartbeat session', {
+                error: err.message,
+            }));
+            return;
+        }
+        for (const session of this.sessions.values()) {
+            session.sendMessage(message);
+        }
+    }
+}
+exports.AgentRunner = AgentRunner;
+//# sourceMappingURL=runner.js.map