instar 0.3.7 → 0.4.0

package/dist/commands/server.js

@@ -72,6 +72,48 @@ async function respawnSessionForTopic(sessionManager, telegram, targetSession, t
     await telegram.sendToTopic(topicId, `Session respawned.`);
     console.log(`[telegram→session] Respawned "${newSessionName}" for topic ${topicId}`);
 }
+/**
+ * Wire up Telegram session management callbacks.
+ * These enable /interrupt, /restart, /sessions commands and stall detection.
+ */
+function wireTelegramCallbacks(telegram, sessionManager, state) {
+    // /interrupt — send Escape key to a tmux session
+    telegram.onInterruptSession = async (sessionName) => {
+        try {
+            execFileSync(detectTmuxPath(), ['send-keys', '-t', `=${sessionName}:`, 'Escape'], {
+                encoding: 'utf-8', timeout: 5000,
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    // /restart — kill session and respawn
+    telegram.onRestartSession = async (sessionName, topicId) => {
+        // Kill existing session
+        try {
+            execFileSync(detectTmuxPath(), ['kill-session', '-t', `=${sessionName}`], { stdio: 'ignore' });
+        }
+        catch { /* may already be dead */ }
+        // Respawn with thread history
+        await respawnSessionForTopic(sessionManager, telegram, sessionName, topicId);
+    };
+    // /sessions — list running sessions
+    telegram.onListSessions = () => {
+        const sessions = state.listSessions({ status: 'running' });
+        return sessions.map(s => ({
+            name: s.name,
+            tmuxSession: s.tmuxSession,
+            status: s.status,
+            alive: sessionManager.isSessionAlive(s.tmuxSession),
+        }));
+    };
+    // Stall detection — check if a session is alive
+    telegram.onIsSessionAlive = (sessionName) => {
+        return sessionManager.isSessionAlive(sessionName);
+    };
+}
 /**
  * Wire up Telegram message routing: topic messages → Claude sessions.
  * This is the core handler that makes Telegram topics work like sessions.
@@ -82,7 +124,8 @@ function wireTelegramRouting(telegram, sessionManager) {
         if (!topicId)
             return;
         const text = msg.content;
-        // Handle /new command — spawn a new session with its own topic
+        // Most commands are handled inside TelegramAdapter.handleCommand().
+        // /new is handled here because it needs sessionManager access.
         const newMatch = text.match(/^\/new(?:\s+(.+))?$/);
         if (newMatch) {
             const sessionName = newMatch[1]?.trim() || null;
@@ -110,6 +153,8 @@ function wireTelegramRouting(telegram, sessionManager) {
             if (sessionManager.isSessionAlive(targetSession)) {
                 console.log(`[telegram→session] Injecting into ${targetSession}: "${text.slice(0, 80)}"`);
                 sessionManager.injectTelegramMessage(targetSession, topicId, text);
+                // Track for stall detection
+                telegram.trackMessageInjection(topicId, targetSession, text);
             }
             else {
                 // Session died — respawn with thread history
@@ -235,8 +280,9 @@ export async function startServer(options) {
             telegram = new TelegramAdapter(telegramConfig.config, config.stateDir);
             await telegram.start();
             console.log(pc.green('  Telegram connected'));
-            // Wire up topic → session routing
+            // Wire up topic → session routing and session management callbacks
             wireTelegramRouting(telegram, sessionManager);
+            wireTelegramCallbacks(telegram, sessionManager, state);
             console.log(pc.green('  Telegram message routing active'));
             if (scheduler) {
                 scheduler.setMessenger(telegram);

package/dist/core/types.d.ts

@@ -156,8 +156,8 @@ export interface MessagingAdapter {
     start(): Promise<void>;
     /** Stop listening */
     stop(): Promise<void>;
-    /** Send a message to a user */
-    send(message: OutgoingMessage): Promise<void>;
+    /** Send a message to a user. Returns platform-specific delivery info. */
+    send(message: OutgoingMessage): Promise<void | unknown>;
     /** Register a handler for incoming messages */
     onMessage(handler: (message: Message) => Promise<void>): void;
     /** Resolve a platform-specific identifier to a user ID */

package/dist/messaging/TelegramAdapter.d.ts

@@ -2,8 +2,9 @@
  * Telegram Messaging Adapter — send/receive messages via Telegram Bot API.
  *
  * Uses long polling to receive messages. Supports forum topics
- * (each user gets a topic thread). Includes topic-session registry
- * and message logging for session respawn with thread history.
+ * (each user gets a topic thread). Includes topic-session registry,
+ * message logging, voice transcription, photo handling, stall detection,
+ * auth gating, and delivery confirmation.
  *
  * No external dependencies — uses native fetch for Telegram API calls.
  */
@@ -15,6 +16,18 @@ export interface TelegramConfig {
     chatId: string;
     /** Polling interval in ms */
     pollIntervalMs?: number;
+    /** Authorized Telegram user IDs (only these users' messages are processed) */
+    authorizedUserIds?: number[];
+    /** Voice transcription provider: 'groq' or 'openai' (auto-detects if not set) */
+    voiceProvider?: string;
+    /** Stall detection timeout in minutes (default: 5, 0 to disable) */
+    stallTimeoutMinutes?: number;
+}
+export interface SendResult {
+    /** Telegram message ID */
+    messageId: number;
+    /** Topic the message was sent to */
+    topicId?: number;
 }
 interface LogEntry {
     messageId: number;
@@ -31,21 +44,36 @@ export declare class TelegramAdapter implements MessagingAdapter {
     private polling;
     private pollTimeout;
     private lastUpdateId;
+    private startedAt;
+    private consecutivePollErrors;
     private topicToSession;
     private sessionToTopic;
     private topicToName;
     private registryPath;
     private messageLogPath;
     private offsetPath;
+    private stateDir;
+    private pendingMessages;
+    private stallCheckInterval;
     onTopicMessage: ((message: Message) => void) | null;
+    onInterruptSession: ((sessionName: string) => Promise<boolean>) | null;
+    onRestartSession: ((sessionName: string, topicId: number) => Promise<void>) | null;
+    onListSessions: (() => Array<{
+        name: string;
+        tmuxSession: string;
+        status: string;
+        alive: boolean;
+    }>) | null;
+    onIsSessionAlive: ((tmuxSession: string) => boolean) | null;
     constructor(config: TelegramConfig, stateDir: string);
     start(): Promise<void>;
     stop(): Promise<void>;
-    send(message: OutgoingMessage): Promise<void>;
+    send(message: OutgoingMessage): Promise<SendResult>;
     /**
      * Send a message to a specific forum topic.
+     * Returns the Telegram message ID for delivery confirmation.
      */
-    sendToTopic(topicId: number, text: string): Promise<void>;
+    sendToTopic(topicId: number, text: string): Promise<SendResult>;
     /**
      * Create a forum topic in the supergroup.
      */
@@ -53,9 +81,19 @@ export declare class TelegramAdapter implements MessagingAdapter {
         topicId: number;
         name: string;
     }>;
+    /**
+     * Close a forum topic.
+     */
+    closeForumTopic(topicId: number): Promise<boolean>;
     onMessage(handler: (message: Message) => Promise<void>): void;
     resolveUser(channelIdentifier: string): Promise<string | null>;
+    /**
+     * Check if a message is from an authorized user.
+     * If no authorizedUserIds configured, all messages are accepted.
+     */
+    private isAuthorized;
     registerTopicSession(topicId: number, sessionName: string): void;
+    unregisterTopic(topicId: number): void;
     getSessionForTopic(topicId: number): string | null;
     getTopicForSession(sessionName: string): number | null;
     getTopicName(topicId: number): string | null;
@@ -67,6 +105,41 @@ export declare class TelegramAdapter implements MessagingAdapter {
         sessionName: string;
         topicName: string | null;
     }>;
+    /**
+     * Track that a message was injected into a session.
+     * Used by stall detection to alert if no response comes back.
+     */
+    trackMessageInjection(topicId: number, sessionName: string, messageText: string): void;
+    private clearStallForTopic;
+    private checkForStalls;
+    getStatus(): {
+        started: boolean;
+        uptime: number | null;
+        pendingStalls: number;
+        topicMappings: number;
+    };
+    /**
+     * Download a file from Telegram by file_id.
+     */
+    private downloadFile;
+    /**
+     * Resolve voice transcription provider from config or environment.
+     * Checks explicit config, then env vars, then auto-detects.
+     */
+    private resolveTranscriptionProvider;
+    /**
+     * Transcribe a voice message using the configured provider.
+     */
+    private transcribeVoice;
+    /**
+     * Download a photo from Telegram and save it locally.
+     * Returns the local file path.
+     */
+    private downloadPhoto;
+    /**
+     * Process Telegram commands. Returns true if the message was a command.
+     */
+    private handleCommand;
     /**
      * Get recent messages for a topic (for thread history on respawn).
      */
@@ -74,13 +147,25 @@ export declare class TelegramAdapter implements MessagingAdapter {
     private appendToLog;
     /** Keep only the last 75,000 lines when log exceeds 100,000 lines.
      *  High limits because message history is core agent memory.
-     *  At ~200 bytes/line average, 100k lines ≈ 20MB — fine for a dedicated machine. */
+     *  At ~200 bytes/line average, 100k lines ~ 20MB — fine for a dedicated machine. */
     private maybeRotateLog;
     private loadRegistry;
     private saveRegistry;
     private loadOffset;
     private saveOffset;
     private poll;
+    /**
+     * Process a single Telegram update (text, voice, or photo).
+     */
+    private processUpdate;
+    /**
+     * Handle an incoming voice message: download, transcribe, route as text.
+     */
+    private handleVoiceMessage;
+    /**
+     * Handle an incoming photo message: download, save, route with path.
+     */
+    private handlePhotoMessage;
     private getUpdates;
     private apiCall;
 }

package/dist/messaging/TelegramAdapter.js

@@ -2,8 +2,9 @@
  * Telegram Messaging Adapter — send/receive messages via Telegram Bot API.
  *
  * Uses long polling to receive messages. Supports forum topics
- * (each user gets a topic thread). Includes topic-session registry
- * and message logging for session respawn with thread history.
+ * (each user gets a topic thread). Includes topic-session registry,
+ * message logging, voice transcription, photo handling, stall detection,
+ * auth gating, and delivery confirmation.
  *
  * No external dependencies — uses native fetch for Telegram API calls.
  */
@@ -16,6 +17,8 @@ export class TelegramAdapter {
     polling = false;
     pollTimeout = null;
     lastUpdateId = 0;
+    startedAt = null;
+    consecutivePollErrors = 0;
     // Topic-session registry (persisted to disk)
     topicToSession = new Map();
     sessionToTopic = new Map();
@@ -23,10 +26,20 @@ export class TelegramAdapter {
     registryPath;
     messageLogPath;
     offsetPath;
+    stateDir;
+    // Stall detection
+    pendingMessages = new Map(); // key = topicId-timestamp
+    stallCheckInterval = null;
     // Topic message callback — fires on every incoming topic message
     onTopicMessage = null;
+    // Session management callbacks (wired by server.ts)
+    onInterruptSession = null;
+    onRestartSession = null;
+    onListSessions = null;
+    onIsSessionAlive = null;
     constructor(config, stateDir) {
         this.config = config;
+        this.stateDir = stateDir;
         this.registryPath = path.join(stateDir, 'topic-session-registry.json');
         this.messageLogPath = path.join(stateDir, 'telegram-messages.jsonl');
         this.offsetPath = path.join(stateDir, 'telegram-poll-offset.json');
@@ -37,8 +50,15 @@ export class TelegramAdapter {
         if (this.polling)
             return;
         this.polling = true;
+        this.startedAt = new Date();
+        this.consecutivePollErrors = 0;
         console.log(`[telegram] Starting long-polling...`);
         this.poll();
+        // Start stall detection if configured
+        const stallMinutes = this.config.stallTimeoutMinutes ?? 5;
+        if (stallMinutes > 0) {
+            this.stallCheckInterval = setInterval(() => this.checkForStalls(), 30_000); // Check every 30s
+        }
     }
     async stop() {
         this.polling = false;
@@ -46,6 +66,10 @@ export class TelegramAdapter {
             clearTimeout(this.pollTimeout);
             this.pollTimeout = null;
         }
+        if (this.stallCheckInterval) {
+            clearInterval(this.stallCheckInterval);
+            this.stallCheckInterval = null;
+        }
     }
     async send(message) {
         const topicId = message.channel?.identifier;
@@ -58,22 +82,23 @@ export class TelegramAdapter {
             params.message_thread_id = parseInt(topicId, 10);
         }
         try {
-            await this.apiCall('sendMessage', params);
+            const result = await this.apiCall('sendMessage', params);
+            return { messageId: result.message_id, topicId: topicId ? parseInt(topicId, 10) : undefined };
         }
         catch (err) {
             // Only retry without parse_mode on 400 errors (likely Markdown parse failures)
             const errMsg = err instanceof Error ? err.message : String(err);
             if (errMsg.includes('(400)') && params.parse_mode) {
                 delete params.parse_mode;
-                await this.apiCall('sendMessage', params);
-            }
-            else {
-                throw err;
+                const result = await this.apiCall('sendMessage', params);
+                return { messageId: result.message_id, topicId: topicId ? parseInt(topicId, 10) : undefined };
             }
+            throw err;
         }
     }
     /**
      * Send a message to a specific forum topic.
+     * Returns the Telegram message ID for delivery confirmation.
      */
     async sendToTopic(topicId, text) {
         const params = {
@@ -84,21 +109,25 @@ export class TelegramAdapter {
         if (topicId > 1) {
             params.message_thread_id = topicId;
         }
+        let result;
         try {
-            await this.apiCall('sendMessage', { ...params, parse_mode: 'Markdown' });
+            result = await this.apiCall('sendMessage', { ...params, parse_mode: 'Markdown' });
         }
         catch {
-            await this.apiCall('sendMessage', params);
+            result = await this.apiCall('sendMessage', params);
         }
         // Log outbound messages too
         this.appendToLog({
-            messageId: 0,
+            messageId: result.message_id,
             topicId,
             text,
             fromUser: false,
             timestamp: new Date().toISOString(),
             sessionName: this.topicToSession.get(topicId) ?? null,
         });
+        // Clear stall tracking for this topic (agent responded)
+        this.clearStallForTopic(topicId);
+        return { messageId: result.message_id, topicId };
     }
     /**
      * Create a forum topic in the supergroup.
@@ -117,12 +146,38 @@ export class TelegramAdapter {
         console.log(`[telegram] Created forum topic: "${name}" (ID: ${result.message_thread_id})`);
         return { topicId: result.message_thread_id, name: result.name };
     }
+    /**
+     * Close a forum topic.
+     */
+    async closeForumTopic(topicId) {
+        try {
+            await this.apiCall('closeForumTopic', {
+                chat_id: this.config.chatId,
+                message_thread_id: topicId,
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     onMessage(handler) {
         this.handler = handler;
     }
     async resolveUser(channelIdentifier) {
         return null;
     }
+    // ── Auth Gating ──────────────────────────────────────────
+    /**
+     * Check if a message is from an authorized user.
+     * If no authorizedUserIds configured, all messages are accepted.
+     */
+    isAuthorized(userId) {
+        const authorized = this.config.authorizedUserIds;
+        if (!authorized || authorized.length === 0)
+            return true;
+        return authorized.includes(userId);
+    }
     // ── Topic-Session Registry ─────────────────────────────────
     registerTopicSession(topicId, sessionName) {
         this.topicToSession.set(topicId, sessionName);
@@ -130,6 +185,13 @@ export class TelegramAdapter {
         this.saveRegistry();
         console.log(`[telegram] Registered topic ${topicId} <-> session "${sessionName}"`);
     }
+    unregisterTopic(topicId) {
+        const sessionName = this.topicToSession.get(topicId);
+        this.topicToSession.delete(topicId);
+        if (sessionName)
+            this.sessionToTopic.delete(sessionName);
+        this.saveRegistry();
+    }
     getSessionForTopic(topicId) {
         return this.topicToSession.get(topicId) ?? null;
     }
@@ -153,6 +215,308 @@ export class TelegramAdapter {
         }
         return result;
     }
+    // ── Stall Detection ──────────────────────────────────────
+    /**
+     * Track that a message was injected into a session.
+     * Used by stall detection to alert if no response comes back.
+     */
+    trackMessageInjection(topicId, sessionName, messageText) {
+        const key = `${topicId}-${Date.now()}`;
+        this.pendingMessages.set(key, {
+            topicId,
+            sessionName,
+            messageText: messageText.slice(0, 100),
+            injectedAt: Date.now(),
+            alerted: false,
+        });
+    }
+    clearStallForTopic(topicId) {
+        for (const [key, pending] of this.pendingMessages) {
+            if (pending.topicId === topicId) {
+                this.pendingMessages.delete(key);
+            }
+        }
+    }
+    checkForStalls() {
+        const stallMinutes = this.config.stallTimeoutMinutes ?? 5;
+        const stallThresholdMs = stallMinutes * 60 * 1000;
+        const now = Date.now();
+        for (const [key, pending] of this.pendingMessages) {
+            if (pending.alerted)
+                continue;
+            if (now - pending.injectedAt < stallThresholdMs)
+                continue;
+            // Check if session is still alive
+            const alive = this.onIsSessionAlive
+                ? this.onIsSessionAlive(pending.sessionName)
+                : true; // assume alive if no checker
+            pending.alerted = true;
+            const status = alive ? 'running but not responding' : 'no longer running';
+            const minutesAgo = Math.round((now - pending.injectedAt) / 60000);
+            this.sendToTopic(pending.topicId, `\u26a0\ufe0f No response after ${minutesAgo} minutes. Session "${pending.sessionName}" is ${status}.\n\nMessage: "${pending.messageText}..."${alive ? '\n\nTry /interrupt to unstick, or /restart to respawn.' : '\n\nSend another message to auto-respawn.'}`).catch(err => {
+                console.error(`[telegram] Stall alert failed: ${err}`);
+            });
+        }
+        // Clean up old entries (older than 30 minutes, already alerted)
+        for (const [key, pending] of this.pendingMessages) {
+            if (pending.alerted && now - pending.injectedAt > 30 * 60 * 1000) {
+                this.pendingMessages.delete(key);
+            }
+        }
+    }
+    // ── Health Status ────────────────────────────────────────
+    getStatus() {
+        return {
+            started: this.polling,
+            uptime: this.startedAt ? Date.now() - this.startedAt.getTime() : null,
+            pendingStalls: this.pendingMessages.size,
+            topicMappings: this.topicToSession.size,
+        };
+    }
+    // ── Voice Transcription ──────────────────────────────────
+    /**
+     * Download a file from Telegram by file_id.
+     */
+    async downloadFile(fileId, destPath) {
+        const fileInfo = await this.apiCall('getFile', { file_id: fileId });
+        const fileUrl = `https://api.telegram.org/file/bot${this.config.token}/${fileInfo.file_path}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 60_000);
+        try {
+            const response = await fetch(fileUrl, { signal: controller.signal });
+            if (!response.ok)
+                throw new Error(`Download failed: ${response.status}`);
+            const buffer = Buffer.from(await response.arrayBuffer());
+            fs.writeFileSync(destPath, buffer);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Resolve voice transcription provider from config or environment.
+     * Checks explicit config, then env vars, then auto-detects.
+     */
+    resolveTranscriptionProvider() {
+        const providers = {
+            groq: {
+                envKey: 'GROQ_API_KEY',
+                baseUrl: 'https://api.groq.com/openai/v1',
+                model: 'whisper-large-v3',
+            },
+            openai: {
+                envKey: 'OPENAI_API_KEY',
+                baseUrl: 'https://api.openai.com/v1',
+                model: 'whisper-1',
+            },
+        };
+        // Check explicit config
+        const explicit = this.config.voiceProvider?.toLowerCase();
+        if (explicit && providers[explicit]) {
+            const p = providers[explicit];
+            const apiKey = process.env[p.envKey];
+            if (!apiKey) {
+                console.warn(`[telegram] ${p.envKey} not set — required for ${explicit} voice transcription`);
+                return null;
+            }
+            return { apiKey, baseUrl: p.baseUrl, model: p.model };
+        }
+        // Auto-detect: try Groq first (cheaper), then OpenAI
+        for (const [name, p] of Object.entries(providers)) {
+            const apiKey = process.env[p.envKey];
+            if (apiKey) {
+                console.log(`[telegram] Auto-detected voice transcription provider: ${name}`);
+                return { apiKey, baseUrl: p.baseUrl, model: p.model };
+            }
+        }
+        return null;
+    }
+    /**
+     * Transcribe a voice message using the configured provider.
+     */
+    async transcribeVoice(filePath) {
+        const provider = this.resolveTranscriptionProvider();
+        if (!provider) {
+            throw new Error('No voice transcription provider configured. Set GROQ_API_KEY or OPENAI_API_KEY.');
+        }
+        const formData = new FormData();
+        const fileBuffer = fs.readFileSync(filePath);
+        const blob = new Blob([fileBuffer], { type: 'audio/ogg' });
+        formData.append('file', blob, path.basename(filePath));
+        formData.append('model', provider.model);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 60_000);
+        try {
+            const response = await fetch(`${provider.baseUrl}/audio/transcriptions`, {
+                method: 'POST',
+                headers: { Authorization: `Bearer ${provider.apiKey}` },
+                body: formData,
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const errText = await response.text();
+                throw new Error(`Transcription API error (${response.status}): ${errText}`);
+            }
+            const data = await response.json();
+            return data.text;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    // ── Photo Handling ───────────────────────────────────────
+    /**
+     * Download a photo from Telegram and save it locally.
+     * Returns the local file path.
+     */
+    async downloadPhoto(fileId, messageId) {
+        const photoDir = path.join(this.stateDir, 'telegram-images');
+        fs.mkdirSync(photoDir, { recursive: true });
+        const filename = `photo-${Date.now()}-${messageId}.jpg`;
+        const filepath = path.join(photoDir, filename);
+        await this.downloadFile(fileId, filepath);
+        return filepath;
+    }
+    // ── Command Handling ─────────────────────────────────────
+    /**
+     * Process Telegram commands. Returns true if the message was a command.
+     */
+    async handleCommand(text, topicId, userId) {
+        const cmd = text.trim().toLowerCase();
+        // /sessions — list all sessions with claim status
+        if (cmd === '/sessions' || cmd.startsWith('/sessions ')) {
+            const filterUnclaimed = cmd.includes('unclaimed');
+            if (!this.onListSessions) {
+                await this.sendToTopic(topicId, 'Session listing not available.').catch(() => { });
+                return true;
+            }
+            const sessions = this.onListSessions();
+            if (sessions.length === 0) {
+                await this.sendToTopic(topicId, 'No sessions running.').catch(() => { });
+                return true;
+            }
+            const lines = [];
+            for (const s of sessions) {
+                const linkedTopic = this.getTopicForSession(s.tmuxSession);
+                const claimed = linkedTopic !== null;
+                if (filterUnclaimed && claimed)
+                    continue;
+                const status = s.alive ? '\u2705' : '\u274c';
+                const claimTag = claimed ? ` (topic ${linkedTopic})` : ' \u{1f7e1} unclaimed';
+                lines.push(`${status} ${s.name}${claimTag}`);
+            }
+            if (lines.length === 0) {
+                await this.sendToTopic(topicId, filterUnclaimed ? 'No unclaimed sessions.' : 'No sessions.').catch(() => { });
+            }
+            else {
+                await this.sendToTopic(topicId, lines.join('\n')).catch(() => { });
+            }
+            return true;
+        }
+        // /claim <session> — claim a session into this topic
+        if (cmd.startsWith('/claim ')) {
+            const sessionName = text.trim().slice(7).trim();
+            if (!sessionName) {
+                await this.sendToTopic(topicId, 'Usage: /claim <session-name>').catch(() => { });
+                return true;
+            }
+            // Check if already claimed
+            const existingSession = this.getSessionForTopic(topicId);
+            if (existingSession) {
+                await this.sendToTopic(topicId, `This topic is already linked to "${existingSession}". Use /unlink first.`).catch(() => { });
+                return true;
+            }
+            this.registerTopicSession(topicId, sessionName);
+            await this.sendToTopic(topicId, `Claimed session "${sessionName}" into this topic.`).catch(() => { });
+            return true;
+        }
+        // /link <session> — alias for /claim
+        if (cmd.startsWith('/link ')) {
+            const sessionName = text.trim().slice(6).trim();
+            if (!sessionName) {
+                await this.sendToTopic(topicId, 'Usage: /link <session-name>').catch(() => { });
+                return true;
+            }
+            const existingSession = this.getSessionForTopic(topicId);
+            if (existingSession) {
+                await this.sendToTopic(topicId, `This topic is already linked to "${existingSession}". Use /unlink first.`).catch(() => { });
+                return true;
+            }
+            this.registerTopicSession(topicId, sessionName);
+            await this.sendToTopic(topicId, `Linked session "${sessionName}" to this topic.`).catch(() => { });
+            return true;
+        }
+        // /unlink — unlink session from this topic
+        if (cmd === '/unlink') {
+            const sessionName = this.getSessionForTopic(topicId);
+            if (!sessionName) {
+                await this.sendToTopic(topicId, 'No session linked to this topic.').catch(() => { });
+                return true;
+            }
+            this.unregisterTopic(topicId);
+            await this.sendToTopic(topicId, `Unlinked session "${sessionName}" from this topic.`).catch(() => { });
+            return true;
+        }
+        // /interrupt — send Escape to unstick a stalled session
+        if (cmd === '/interrupt') {
+            const sessionName = this.getSessionForTopic(topicId);
+            if (!sessionName) {
+                await this.sendToTopic(topicId, 'No session linked to this topic.').catch(() => { });
+                return true;
+            }
+            if (!this.onInterruptSession) {
+                await this.sendToTopic(topicId, 'Interrupt not available (no handler registered).').catch(() => { });
+                return true;
+            }
+            try {
+                const success = await this.onInterruptSession(sessionName);
+                if (success) {
+                    await this.sendToTopic(topicId, `Sent Escape to "${sessionName}" \u2014 it should resume processing.`).catch(() => { });
+                }
+                else {
+                    await this.sendToTopic(topicId, `Failed to interrupt "${sessionName}" \u2014 session may not exist.`).catch(() => { });
+                }
+            }
+            catch (err) {
+                await this.sendToTopic(topicId, `Interrupt error: ${err instanceof Error ? err.message : String(err)}`).catch(() => { });
+            }
+            return true;
+        }
+        // /restart — kill and respawn the session for this topic
+        if (cmd === '/restart') {
+            const sessionName = this.getSessionForTopic(topicId);
+            if (!sessionName) {
+                await this.sendToTopic(topicId, 'No session linked to this topic.').catch(() => { });
+                return true;
+            }
+            if (!this.onRestartSession) {
+                await this.sendToTopic(topicId, 'Restart not available (no handler registered).').catch(() => { });
+                return true;
+            }
+            await this.sendToTopic(topicId, `Restarting "${sessionName}"...`).catch(() => { });
+            try {
+                await this.onRestartSession(sessionName, topicId);
+                await this.sendToTopic(topicId, 'Session restarted.').catch(() => { });
+            }
+            catch (err) {
+                await this.sendToTopic(topicId, `Restart failed: ${err instanceof Error ? err.message : String(err)}`).catch(() => { });
+            }
+            return true;
+        }
+        // /status — show Telegram adapter status
+        if (cmd === '/status') {
+            const s = this.getStatus();
+            const lines = [
+                `Telegram adapter: ${s.started ? '\u2705 running' : '\u274c stopped'}`,
+                `Uptime: ${s.uptime ? Math.round(s.uptime / 60000) + 'm' : 'n/a'}`,
+                `Topic mappings: ${s.topicMappings}`,
+                `Pending stall alerts: ${s.pendingStalls}`,
+            ];
+            await this.sendToTopic(topicId, lines.join('\n')).catch(() => { });
+            return true;
+        }
+        return false;
+    }
     // ── Message Log ────────────────────────────────────────────
     /**
      * Get recent messages for a topic (for thread history on respawn).
@@ -191,7 +555,7 @@ export class TelegramAdapter {
     }
     /** Keep only the last 75,000 lines when log exceeds 100,000 lines.
      *  High limits because message history is core agent memory.
-     *  At ~200 bytes/line average, 100k lines ≈ 20MB — fine for a dedicated machine. */
+     *  At ~200 bytes/line average, 100k lines ~ 20MB — fine for a dedicated machine. */
     maybeRotateLog() {
         try {
             const stat = fs.statSync(this.messageLogPath);
@@ -214,7 +578,7 @@ export class TelegramAdapter {
                     catch { /* ignore */ }
                     throw rotateErr;
                 }
-                console.log(`[telegram] Rotated message log: ${lines.length} → ${kept.length} lines`);
+                console.log(`[telegram] Rotated message log: ${lines.length} -> ${kept.length} lines`);
             }
         }
         catch {
@@ -304,61 +668,9 @@ export class TelegramAdapter {
             return;
         try {
             const updates = await this.getUpdates();
+            this.consecutivePollErrors = 0; // Reset on success
             for (const update of updates) {
-                if (update.message?.text) {
-                    const msg = update.message;
-                    const text = msg.text;
-                    // Use message_thread_id if present; fall back to 1 (General topic) for forum groups
-                    const numericTopicId = msg.message_thread_id ?? 1;
-                    const topicId = numericTopicId.toString();
-                    // Auto-capture topic name from reply_to_message
-                    if (msg.reply_to_message?.forum_topic_created?.name) {
-                        if (!this.topicToName.has(numericTopicId)) {
-                            this.topicToName.set(numericTopicId, msg.reply_to_message.forum_topic_created.name);
-                            this.saveRegistry();
-                        }
-                    }
-                    const message = {
-                        id: `tg-${msg.message_id}`,
-                        userId: msg.from.id.toString(),
-                        content: text,
-                        channel: { type: 'telegram', identifier: topicId },
-                        receivedAt: new Date(msg.date * 1000).toISOString(),
-                        metadata: {
-                            telegramUserId: msg.from.id,
-                            username: msg.from.username,
-                            firstName: msg.from.first_name,
-                            messageThreadId: numericTopicId,
-                        },
-                    };
-                    // Log the message
-                    this.appendToLog({
-                        messageId: msg.message_id,
-                        topicId: numericTopicId,
-                        text,
-                        fromUser: true,
-                        timestamp: new Date(msg.date * 1000).toISOString(),
-                        sessionName: this.topicToSession.get(numericTopicId) ?? null,
-                    });
-                    // Fire topic message callback (always fires — General topic falls back to ID 1)
-                    if (this.onTopicMessage) {
-                        try {
-                            this.onTopicMessage(message);
-                        }
-                        catch (err) {
-                            console.error(`[telegram] Topic message handler error: ${err}`);
-                        }
-                    }
-                    // Fire general handler
-                    if (this.handler) {
-                        try {
-                            await this.handler(message);
-                        }
-                        catch (err) {
-                            console.error(`[telegram] Handler error: ${err}`);
-                        }
-                    }
-                }
+                await this.processUpdate(update);
                 this.lastUpdateId = Math.max(this.lastUpdateId, update.update_id);
             }
             // Persist offset so restarts don't re-process old messages
@@ -367,12 +679,251 @@ export class TelegramAdapter {
             }
         }
         catch (err) {
-            console.error(`[telegram] Poll error: ${err}`);
+            this.consecutivePollErrors++;
+            const errMsg = err instanceof Error ? err.message : String(err);
+            // Check for fatal errors that require restart
+            if (errMsg.includes('401') || errMsg.includes('Unauthorized')) {
+                console.error(`[telegram] FATAL: Bot token is invalid. Stopping polling.`);
+                this.polling = false;
+                return;
+            }
+            // Exponential backoff on consecutive errors
+            if (this.consecutivePollErrors > 1) {
+                const backoffMs = Math.min(1000 * Math.pow(2, this.consecutivePollErrors - 1), 60_000);
+                console.error(`[telegram] Poll error (attempt ${this.consecutivePollErrors}), backing off ${backoffMs}ms: ${errMsg}`);
+                await new Promise(r => setTimeout(r, backoffMs));
+            }
+            else {
+                console.error(`[telegram] Poll error: ${errMsg}`);
+            }
         }
         // Schedule next poll
         const interval = this.config.pollIntervalMs ?? 2000;
         this.pollTimeout = setTimeout(() => this.poll(), interval);
     }
+    /**
+     * Process a single Telegram update (text, voice, or photo).
+     */
+    async processUpdate(update) {
+        const msg = update.message;
+        if (!msg)
+            return;
+        // Auth gating — reject messages from unauthorized users
+        if (!this.isAuthorized(msg.from.id)) {
+            console.log(`[telegram] Ignoring message from unauthorized user ${msg.from.id} (${msg.from.username ?? msg.from.first_name})`);
+            return;
+        }
+        const numericTopicId = msg.message_thread_id ?? 1;
+        const topicId = numericTopicId.toString();
+        // Auto-capture topic name from reply_to_message
+        if (msg.reply_to_message?.forum_topic_created?.name) {
+            if (!this.topicToName.has(numericTopicId)) {
+                this.topicToName.set(numericTopicId, msg.reply_to_message.forum_topic_created.name);
+                this.saveRegistry();
+            }
+        }
+        // Handle voice messages
+        if (msg.voice) {
+            await this.handleVoiceMessage(msg, numericTopicId);
+            return;
+        }
+        // Handle photo messages
+        if (msg.photo && msg.photo.length > 0) {
+            await this.handlePhotoMessage(msg, numericTopicId);
+            return;
+        }
+        // Handle text messages
+        if (!msg.text)
+            return;
+        const text = msg.text;
+        // Check for commands first
+        if (text.startsWith('/')) {
+            const handled = await this.handleCommand(text, numericTopicId, msg.from.id);
+            if (handled)
+                return;
+        }
+        const message = {
+            id: `tg-${msg.message_id}`,
+            userId: msg.from.id.toString(),
+            content: text,
+            channel: { type: 'telegram', identifier: topicId },
+            receivedAt: new Date(msg.date * 1000).toISOString(),
+            metadata: {
+                telegramUserId: msg.from.id,
+                username: msg.from.username,
+                firstName: msg.from.first_name,
+                messageThreadId: numericTopicId,
+            },
+        };
+        // Log the message
+        this.appendToLog({
+            messageId: msg.message_id,
+            topicId: numericTopicId,
+            text,
+            fromUser: true,
+            timestamp: new Date(msg.date * 1000).toISOString(),
+            sessionName: this.topicToSession.get(numericTopicId) ?? null,
+        });
+        // Fire topic message callback (always fires — General topic falls back to ID 1)
+        if (this.onTopicMessage) {
+            try {
+                this.onTopicMessage(message);
+            }
+            catch (err) {
+                console.error(`[telegram] Topic message handler error: ${err}`);
+            }
+        }
+        // Fire general handler
+        if (this.handler) {
+            try {
+                await this.handler(message);
+            }
+            catch (err) {
+                console.error(`[telegram] Handler error: ${err}`);
+            }
+        }
+    }
+    /**
+     * Handle an incoming voice message: download, transcribe, route as text.
+     */
+    async handleVoiceMessage(msg, topicId) {
+        const voice = msg.voice;
+        // Download the voice file
+        const voiceDir = path.join(this.stateDir, 'telegram-voice');
+        fs.mkdirSync(voiceDir, { recursive: true });
+        const filename = `voice-${Date.now()}-${msg.message_id}.ogg`;
+        const filepath = path.join(voiceDir, filename);
+        try {
+            await this.downloadFile(voice.file_id, filepath);
+        }
+        catch (err) {
+            console.error(`[telegram] Failed to download voice: ${err}`);
+            await this.sendToTopic(topicId, `(Voice message received but download failed)`).catch(() => { });
+            return;
+        }
+        // Transcribe
+        try {
+            const transcript = await this.transcribeVoice(filepath);
+            console.log(`[telegram] Transcribed voice (${voice.duration}s): "${transcript.slice(0, 80)}"`);
+            // Create a message with the transcription
+            const message = {
+                id: `tg-${msg.message_id}`,
+                userId: msg.from.id.toString(),
+                content: `[voice] ${transcript}`,
+                channel: { type: 'telegram', identifier: topicId.toString() },
+                receivedAt: new Date(msg.date * 1000).toISOString(),
+                metadata: {
+                    telegramUserId: msg.from.id,
+                    username: msg.from.username,
+                    firstName: msg.from.first_name,
+                    messageThreadId: topicId,
+                    voiceFile: filepath,
+                    voiceDuration: voice.duration,
+                },
+            };
+            // Log it
+            this.appendToLog({
+                messageId: msg.message_id,
+                topicId,
+                text: `[voice] ${transcript}`,
+                fromUser: true,
+                timestamp: new Date(msg.date * 1000).toISOString(),
+                sessionName: this.topicToSession.get(topicId) ?? null,
+            });
+            // Fire callbacks
+            if (this.onTopicMessage) {
+                try {
+                    this.onTopicMessage(message);
+                }
+                catch (err) {
+                    console.error(`[telegram] Topic message handler error: ${err}`);
+                }
+            }
+            if (this.handler) {
+                try {
+                    await this.handler(message);
+                }
+                catch (err) {
+                    console.error(`[telegram] Handler error: ${err}`);
+                }
+            }
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            const isNotConfigured = errMsg.includes('No voice transcription provider configured');
+            const replyText = isNotConfigured
+                ? '\ud83c\udfa4 Voice transcription is not configured. To enable it, set GROQ_API_KEY or OPENAI_API_KEY in your environment.'
+                : `(Voice message received but transcription failed: ${errMsg})`;
+            await this.sendToTopic(topicId, replyText).catch(() => { });
+        }
+        finally {
+            // Clean up voice file after processing
+            try {
+                fs.unlinkSync(filepath);
+            }
+            catch { /* ignore */ }
+        }
+    }
+    /**
+     * Handle an incoming photo message: download, save, route with path.
+     */
+    async handlePhotoMessage(msg, topicId) {
+        const photos = msg.photo;
+        // Get highest resolution (last in array)
+        const photo = photos[photos.length - 1];
+        const caption = msg.caption || '';
+        try {
+            const filepath = await this.downloadPhoto(photo.file_id, msg.message_id);
+            console.log(`[telegram] Downloaded photo: ${filepath}`);
+            const content = caption
+                ? `[image:${filepath}] ${caption}`
+                : `[image:${filepath}]`;
+            const message = {
+                id: `tg-${msg.message_id}`,
+                userId: msg.from.id.toString(),
+                content,
+                channel: { type: 'telegram', identifier: topicId.toString() },
+                receivedAt: new Date(msg.date * 1000).toISOString(),
+                metadata: {
+                    telegramUserId: msg.from.id,
+                    username: msg.from.username,
+                    firstName: msg.from.first_name,
+                    messageThreadId: topicId,
+                    photoPath: filepath,
+                },
+            };
+            // Log it
+            this.appendToLog({
+                messageId: msg.message_id,
+                topicId,
+                text: content,
+                fromUser: true,
+                timestamp: new Date(msg.date * 1000).toISOString(),
+                sessionName: this.topicToSession.get(topicId) ?? null,
+            });
+            // Fire callbacks
+            if (this.onTopicMessage) {
+                try {
+                    this.onTopicMessage(message);
+                }
+                catch (err) {
+                    console.error(`[telegram] Topic message handler error: ${err}`);
+                }
+            }
+            if (this.handler) {
+                try {
+                    await this.handler(message);
+                }
+                catch (err) {
+                    console.error(`[telegram] Handler error: ${err}`);
+                }
+            }
+        }
+        catch (err) {
+            console.error(`[telegram] Failed to download photo: ${err}`);
+            await this.sendToTopic(topicId, `(Photo received but download failed: ${err instanceof Error ? err.message : String(err)})`).catch(() => { });
+        }
+    }
     async getUpdates() {
         const result = await this.apiCall('getUpdates', {
             offset: this.lastUpdateId + 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.3.7",
+  "version": "0.4.0",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",