instar 0.8.6 → 0.8.7

package/dist/core/PostUpdateMigrator.js

@@ -135,6 +135,11 @@ When user input starts with \`[telegram:N]\` (e.g., \`[telegram:26] hello\`), th
 
 **IMMEDIATE ACKNOWLEDGMENT (MANDATORY):** When you receive a Telegram message, your FIRST action — before reading files, searching code, or doing any work — must be sending a brief acknowledgment back. This confirms the message was received and you haven't stalled. Examples: "Got it, looking into this now." / "On it — checking the scheduler." / "Received, working on the sync." Then do the work, then send the full response.
 
+**Message types:**
+- **Text**: \`[telegram:26] hello there\` — standard text message
+- **Voice**: \`[telegram:26] [voice] transcribed text here\` — voice message, already transcribed
+- **Photo**: \`[telegram:26] [image:/path/to/file.jpg]\` or \`[telegram:26] [image:/path/to/file.jpg] caption text\` — use the Read tool to view the image at the given path
+
 **Response relay:** After completing your work, relay your response back:
 
 \`\`\`bash
@@ -163,6 +168,17 @@ Strip the \`[telegram:N]\` prefix before interpreting the message. Respond natur
                 }
             }
         }
+        // Upgrade existing Telegram Relay sections to document image message format
+        if (this.config.hasTelegram && content.includes('Telegram Relay') && !content.includes('[image:')) {
+            const imageBlock = `\n**Message types:**\n- **Text**: \`[telegram:N] hello there\` — standard text message\n- **Voice**: \`[telegram:N] [voice] transcribed text here\` — voice message, already transcribed\n- **Photo**: \`[telegram:N] [image:/path/to/file.jpg]\` or with caption — use the Read tool to view the image at the given path\n`;
+            // Insert before the Response relay section
+            const relayIdx = content.indexOf('**Response relay:**');
+            if (relayIdx >= 0) {
+                content = content.slice(0, relayIdx) + imageBlock + '\n' + content.slice(relayIdx);
+                patched = true;
+                result.upgraded.push('CLAUDE.md: added image/photo message format to Telegram Relay');
+            }
+        }
         // Private Viewer + Tunnel section
         if (!content.includes('Private Viewing') && !content.includes('POST /view')) {
             const section = `

package/dist/lifeline/TelegramLifeline.d.ts

@@ -38,6 +38,14 @@ export declare class TelegramLifeline {
     start(): Promise<void>;
     private poll;
     private processUpdate;
+    /**
+     * Handle an incoming photo message: download it and forward/queue with [image:path] content.
+     */
+    private handlePhotoMessage;
+    /**
+     * Download a photo from Telegram and save it to the state directory.
+     */
+    private downloadPhoto;
     /**
      * Forward a message to the Instar server's Telegram webhook.
      */

package/dist/lifeline/TelegramLifeline.js

@@ -233,7 +233,14 @@ export class TelegramLifeline {
     }
     async processUpdate(update) {
         const msg = update.message;
-        if (!msg || !msg.text)
+        if (!msg)
+            return;
+        // Handle photo messages
+        if (msg.photo && msg.photo.length > 0 && !msg.text) {
+            await this.handlePhotoMessage(msg);
+            return;
+        }
+        if (!msg.text)
             return;
         const topicId = msg.message_thread_id ?? 1;
         const text = msg.text;
@@ -276,6 +283,73 @@ export class TelegramLifeline {
         // Notify user that message is queued
         await this.sendToTopic(topicId, `Server is temporarily down. Your message has been queued (${this.queue.length} in queue). It will be delivered when the server recovers.`);
     }
+    /**
+     * Handle an incoming photo message: download it and forward/queue with [image:path] content.
+     */
+    async handlePhotoMessage(msg) {
+        const topicId = msg.message_thread_id ?? 1;
+        const photos = msg.photo;
+        const photo = photos[photos.length - 1]; // highest resolution
+        const caption = msg.caption ?? '';
+        let content;
+        let photoPath;
+        try {
+            photoPath = await this.downloadPhoto(photo.file_id, msg.message_id);
+            content = caption ? `[image:${photoPath}] ${caption}` : `[image:${photoPath}]`;
+        }
+        catch (err) {
+            // Download failed — forward caption or placeholder so message isn't silently dropped
+            content = caption ? `[image:download-failed] ${caption}` : '[image:download-failed]';
+            console.error(`[lifeline] Failed to download photo: ${err}`);
+        }
+        if (this.supervisor.healthy) {
+            const forwarded = await this.forwardToServer(topicId, content, msg);
+            if (forwarded) {
+                await this.sendToTopic(topicId, '✓ Delivered');
+                return;
+            }
+        }
+        // Queue the photo message (server down or forward failed)
+        this.queue.enqueue({
+            id: `tg-${msg.message_id}`,
+            topicId,
+            text: content,
+            fromUserId: msg.from.id,
+            fromUsername: msg.from.username,
+            fromFirstName: msg.from.first_name,
+            timestamp: new Date(msg.date * 1000).toISOString(),
+            photoPath,
+        });
+        if (this.supervisor.healthy) {
+            await this.sendToTopic(topicId, `Server is restarting. Your photo has been queued (${this.queue.length} in queue). It will be delivered when the server recovers.`);
+        }
+        else {
+            await this.sendToTopic(topicId, `Server is temporarily down. Your photo has been queued (${this.queue.length} in queue). It will be delivered when the server recovers.`);
+        }
+    }
+    /**
+     * Download a photo from Telegram and save it to the state directory.
+     */
+    async downloadPhoto(fileId, messageId) {
+        // Get file path from Telegram
+        const infoRes = await fetch(`https://api.telegram.org/bot${this.config.token}/getFile?file_id=${encodeURIComponent(fileId)}`);
+        if (!infoRes.ok)
+            throw new Error(`getFile failed: ${infoRes.status}`);
+        const infoData = await infoRes.json();
+        if (!infoData.ok || !infoData.result?.file_path)
+            throw new Error('getFile returned no path');
+        const filePath = infoData.result.file_path;
+        const photoDir = path.join(this.projectConfig.stateDir, 'telegram-images');
+        fs.mkdirSync(photoDir, { recursive: true });
+        const filename = `photo-${Date.now()}-${messageId}.jpg`;
+        const localPath = path.join(photoDir, filename);
+        const fileRes = await fetch(`https://api.telegram.org/file/bot${this.config.token}/${filePath}`);
+        if (!fileRes.ok)
+            throw new Error(`File download failed: ${fileRes.status}`);
+        const buf = Buffer.from(await fileRes.arrayBuffer());
+        fs.writeFileSync(localPath, buf);
+        return localPath;
+    }
     /**
      * Forward a message to the Instar server's Telegram webhook.
      */

package/package.json

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