instar 0.7.14 → 0.7.15

package/.claude/skills/setup-wizard/skill.md

@@ -656,8 +656,16 @@ Adapt the tone and examples to the agent's personality and role. Keep it warm an
 After the server is running and the greeting is sent:
 
 > "All done! [Agent name] just messaged you in the Lifeline topic on Telegram. From here on, that's your primary channel — just talk to your agent there."
+
+Then explain the connectivity requirement clearly:
+
+> "One important thing to know: your agent runs on this computer. As long as it's on and awake, your agent is reachable via Telegram."
 >
-> "As long as your computer is running the Instar server, your agent is available."
+> "If your computer goes to sleep or shuts down, Telegram messages will queue up. Your agent will pick them up when it wakes back up."
+>
+> "For always-on access, some users keep a dedicated machine running — but it's not required to get started."
+
+Keep it matter-of-fact, not alarming. The user should understand the tradeoff without feeling like they need a server farm to use this.
 
 **Do NOT present a list of CLI commands or next steps.** The setup wizard's job is done. The user's next action is opening Telegram and replying to their agent.
 

package/.vercel/README.txt

@@ -0,0 +1,11 @@
+> Why do I have a folder named ".vercel" in my project?
+The ".vercel" folder is created when you link a directory to a Vercel project.
+
+> What does the "project.json" file contain?
+The "project.json" file contains:
+- The ID of the Vercel project that you linked ("projectId")
+- The ID of the user or team your Vercel project is owned by ("orgId")
+
+> Should I commit the ".vercel" folder?
+No, you should not share the ".vercel" folder with anyone.
+Upon creation, it will be automatically added to your ".gitignore" file.

package/.vercel/project.json

@@ -0,0 +1 @@
+{"projectId":"prj_evM5LcItYL3IAmw8zNvEPGrHeaya","orgId":"team_dHctwIDcV3X9ydapQlCPHFGI","projectName":"claude-agent-kit"}

package/dist/commands/setup.js

@@ -462,6 +462,19 @@ async function runClassicSetup() {
             const parsed = JSON.parse(topicResult);
             if (parsed.ok && parsed.result?.message_thread_id) {
                 lifelineThreadId = parsed.result.message_thread_id;
+                // Persist lifelineTopicId back to config.json
+                try {
+                    const configPath = path.join(stateDir, 'config.json');
+                    const rawConfig = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+                    const tgEntry = rawConfig.messaging?.find((m) => m.type === 'telegram');
+                    if (tgEntry?.config) {
+                        tgEntry.config.lifelineTopicId = lifelineThreadId;
+                        const tmpPath = `${configPath}.${process.pid}.tmp`;
+                        fs.writeFileSync(tmpPath, JSON.stringify(rawConfig, null, 2));
+                        fs.renameSync(tmpPath, configPath);
+                    }
+                }
+                catch { /* non-fatal */ }
             }
         }
         catch {
@@ -480,6 +493,8 @@ async function runClassicSetup() {
                 '- I can proactively create topics when something needs attention',
                 '- Lifeline is always here for anything that doesn\'t fit elsewhere',
                 '',
+                '_I run on your computer, so I\'m available as long as it\'s on and awake. If it sleeps, I\'ll pick up messages when it wakes back up._',
+                '',
                 'What should we work on first?',
             ].join('\n');
             const payload = {
@@ -504,7 +519,10 @@ async function runClassicSetup() {
         const topicNote = lifelineThreadId ? ' in the Lifeline topic' : '';
         console.log(pc.bold(`  All done! ${projectName} just messaged you${topicNote} on Telegram.`));
         console.log(pc.dim('  That\'s your primary channel from here on — no terminal needed.'));
-        console.log(pc.dim('  As long as your computer is running the Instar server, your agent is available.'));
+        console.log();
+        console.log(pc.dim('  Your agent runs on this computer. As long as it\'s on and awake,'));
+        console.log(pc.dim('  your agent is reachable via Telegram. If your computer sleeps or'));
+        console.log(pc.dim('  shuts down, messages will queue and be picked up when it wakes.'));
     }
     else {
         console.log();

package/dist/lifeline/TelegramLifeline.d.ts

@@ -29,6 +29,7 @@ export declare class TelegramLifeline {
     private offsetPath;
     private stopHeartbeat;
     private replayInterval;
+    private lifelineTopicId;
     constructor(projectDir?: string);
     /**
      * Start the lifeline — begins Telegram polling and server supervision.
@@ -43,6 +44,14 @@ export declare class TelegramLifeline {
     private handleLifelineCommand;
     private replayQueue;
     private notifyServerDown;
+    /**
+     * Ensure the Lifeline topic exists. Recreates if deleted.
+     */
+    private ensureLifelineTopic;
+    /**
+     * Persist the Lifeline topic ID to config.json.
+     */
+    private persistLifelineTopicId;
     private sendToTopic;
     private getUpdates;
     private apiCall;

package/dist/lifeline/TelegramLifeline.js

@@ -36,6 +36,7 @@ export class TelegramLifeline {
     offsetPath;
     stopHeartbeat = null;
     replayInterval = null;
+    lifelineTopicId = null;
     constructor(projectDir) {
         this.projectConfig = loadConfig(projectDir);
         ensureStateDir(this.projectConfig.stateDir);
@@ -81,6 +82,11 @@ export class TelegramLifeline {
         }
         catch { /* non-critical */ }
         this.stopHeartbeat = startHeartbeat(`${this.projectConfig.projectName}-lifeline`);
+        // Ensure Lifeline topic exists (auto-recreate if deleted)
+        this.lifelineTopicId = await this.ensureLifelineTopic();
+        if (this.lifelineTopicId) {
+            console.log(pc.green(`  Lifeline topic: ${this.lifelineTopicId}`));
+        }
         // Start server supervisor
         const serverStarted = await this.supervisor.start();
         if (serverStarted) {
@@ -300,8 +306,82 @@ export class TelegramLifeline {
     }
     // ── Notifications ─────────────────────────────────────────
     async notifyServerDown(reason) {
-        // Send to General topic (1) — since we don't know which topic the user is watching
-        await this.sendToTopic(1, `Server went down: ${reason}\n\nYour messages will be queued until recovery. Use /lifeline status to check.`).catch(() => { });
+        // Send to Lifeline topic if available, otherwise General
+        const topicId = this.lifelineTopicId ?? 1;
+        await this.sendToTopic(topicId, `Server went down: ${reason}\n\nYour messages will be queued until recovery. Use /lifeline status to check.`).catch(() => { });
+    }
+    // ── Lifeline Topic ──────────────────────────────────────────
+    /**
+     * Ensure the Lifeline topic exists. Recreates if deleted.
+     */
+    async ensureLifelineTopic() {
+        const existingId = this.config.lifelineTopicId;
+        if (existingId) {
+            // Verify it still exists
+            try {
+                await this.apiCall('sendMessage', {
+                    chat_id: this.config.chatId,
+                    message_thread_id: existingId,
+                    text: '🟢 Lifeline connected.',
+                });
+                return existingId;
+            }
+            catch (err) {
+                const errStr = String(err);
+                if (errStr.includes('thread not found') || errStr.includes('TOPIC_DELETED') ||
+                    errStr.includes('TOPIC_CLOSED') || errStr.includes('not found')) {
+                    console.log(`[Lifeline] Topic ${existingId} was deleted — recreating`);
+                }
+                else {
+                    // Non-fatal error (network etc.) — assume it still exists
+                    console.warn(`[Lifeline] Topic check failed (non-fatal): ${err}`);
+                    return existingId;
+                }
+            }
+        }
+        // Create or recreate
+        try {
+            const result = await this.apiCall('createForumTopic', {
+                chat_id: this.config.chatId,
+                name: 'Lifeline',
+                icon_color: 9367192, // green
+            });
+            const topicId = result.message_thread_id;
+            this.config.lifelineTopicId = topicId;
+            this.persistLifelineTopicId(topicId);
+            console.log(`[Lifeline] ${existingId ? 'Recreated' : 'Created'} Lifeline topic: ${topicId}`);
+            // Send welcome message in new topic
+            await this.sendToTopic(topicId, '🟢 Lifeline connected. This topic is always available — even when the server is down.');
+            return topicId;
+        }
+        catch (err) {
+            console.error(`[Lifeline] Failed to create Lifeline topic: ${err}`);
+            return null;
+        }
+    }
+    /**
+     * Persist the Lifeline topic ID to config.json.
+     */
+    persistLifelineTopicId(topicId) {
+        try {
+            const configPath = path.join(this.projectConfig.projectDir, '.instar', 'config.json');
+            if (fs.existsSync(configPath)) {
+                const raw = fs.readFileSync(configPath, 'utf-8');
+                const config = JSON.parse(raw);
+                if (Array.isArray(config.messaging)) {
+                    const entry = config.messaging.find((m) => m.type === 'telegram');
+                    if (entry?.config) {
+                        entry.config.lifelineTopicId = topicId;
+                        const tmpPath = `${configPath}.${process.pid}.tmp`;
+                        fs.writeFileSync(tmpPath, JSON.stringify(config, null, 2));
+                        fs.renameSync(tmpPath, configPath);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            console.warn(`[Lifeline] Failed to persist lifelineTopicId: ${err}`);
+        }
     }
     // ── Telegram API ──────────────────────────────────────────
     async sendToTopic(topicId, text) {

package/dist/messaging/TelegramAdapter.d.ts

@@ -22,6 +22,8 @@ export interface TelegramConfig {
     voiceProvider?: string;
     /** Stall detection timeout in minutes (default: 5, 0 to disable) */
     stallTimeoutMinutes?: number;
+    /** Lifeline topic thread ID — the always-available channel. Auto-recreated if deleted. */
+    lifelineTopicId?: number;
 }
 export interface SendResult {
     /** Telegram message ID */
@@ -100,6 +102,19 @@ export declare class TelegramAdapter implements MessagingAdapter {
         topicId: number;
         name: string;
     }>;
+    /**
+     * Get the Lifeline topic ID (if configured).
+     */
+    getLifelineTopicId(): number | undefined;
+    /**
+     * Ensure the Lifeline topic exists. If it was deleted, recreate it.
+     * Called on startup and can be called periodically.
+     */
+    ensureLifelineTopic(): Promise<number | null>;
+    /**
+     * Persist the Lifeline topic ID back to config.json so it survives restarts.
+     */
+    private persistLifelineTopicId;
     /**
      * Close a forum topic.
      */

package/dist/messaging/TelegramAdapter.js

@@ -87,6 +87,8 @@ export class TelegramAdapter {
         this.polling = true;
         this.startedAt = new Date();
         this.consecutivePollErrors = 0;
+        // Ensure Lifeline topic exists (auto-recreate if deleted)
+        await this.ensureLifelineTopic();
         console.log(`[telegram] Starting long-polling...`);
         this.poll();
         // Start stall detection if configured
@@ -180,6 +182,97 @@ export class TelegramAdapter {
         console.log(`[telegram] Created forum topic: "${name}" (ID: ${result.message_thread_id})`);
         return { topicId: result.message_thread_id, name: result.name };
     }
+    /**
+     * Get the Lifeline topic ID (if configured).
+     */
+    getLifelineTopicId() {
+        return this.config.lifelineTopicId;
+    }
+    /**
+     * Ensure the Lifeline topic exists. If it was deleted, recreate it.
+     * Called on startup and can be called periodically.
+     */
+    async ensureLifelineTopic() {
+        if (!this.config.lifelineTopicId) {
+            // No lifeline topic configured — create one
+            try {
+                const topic = await this.createForumTopic('Lifeline', 9367192); // Green
+                this.config.lifelineTopicId = topic.topicId;
+                this.persistLifelineTopicId(topic.topicId);
+                console.log(`[telegram] Created Lifeline topic: ${topic.topicId}`);
+                return topic.topicId;
+            }
+            catch (err) {
+                console.error(`[telegram] Failed to create Lifeline topic: ${err}`);
+                return null;
+            }
+        }
+        // Lifeline topic ID exists — verify it's still valid by sending a test
+        try {
+            await this.apiCall('sendMessage', {
+                chat_id: this.config.chatId,
+                message_thread_id: this.config.lifelineTopicId,
+                text: '🟢 Lifeline connected.',
+            });
+            console.log(`[telegram] Lifeline topic verified: ${this.config.lifelineTopicId}`);
+            return this.config.lifelineTopicId;
+        }
+        catch (err) {
+            const errStr = String(err);
+            // Topic was deleted — "message thread not found" or "TOPIC_CLOSED" or similar
+            if (errStr.includes('thread not found') || errStr.includes('TOPIC_DELETED') ||
+                errStr.includes('TOPIC_CLOSED') || errStr.includes('not found')) {
+                console.log(`[telegram] Lifeline topic ${this.config.lifelineTopicId} was deleted — recreating`);
+                try {
+                    const topic = await this.createForumTopic('Lifeline', 9367192);
+                    this.config.lifelineTopicId = topic.topicId;
+                    this.persistLifelineTopicId(topic.topicId);
+                    console.log(`[telegram] Recreated Lifeline topic: ${topic.topicId}`);
+                    return topic.topicId;
+                }
+                catch (recreateErr) {
+                    console.error(`[telegram] Failed to recreate Lifeline topic: ${recreateErr}`);
+                    return null;
+                }
+            }
+            // Some other error (network, etc.) — don't recreate, just warn
+            console.warn(`[telegram] Lifeline topic check failed (non-fatal): ${err}`);
+            return this.config.lifelineTopicId;
+        }
+    }
+    /**
+     * Persist the Lifeline topic ID back to config.json so it survives restarts.
+     */
+    persistLifelineTopicId(topicId) {
+        try {
+            // Find config.json in state dir's parent (stateDir is .instar/state or .instar)
+            const candidates = [
+                path.join(this.stateDir, '..', 'config.json'),
+                path.join(this.stateDir, 'config.json'),
+            ];
+            for (const configPath of candidates) {
+                if (fs.existsSync(configPath)) {
+                    const raw = fs.readFileSync(configPath, 'utf-8');
+                    const config = JSON.parse(raw);
+                    // Find the telegram messaging config and update it
+                    if (Array.isArray(config.messaging)) {
+                        const telegramEntry = config.messaging.find((m) => m.type === 'telegram');
+                        if (telegramEntry?.config) {
+                            telegramEntry.config.lifelineTopicId = topicId;
+                            const tmpPath = `${configPath}.${process.pid}.tmp`;
+                            fs.writeFileSync(tmpPath, JSON.stringify(config, null, 2));
+                            fs.renameSync(tmpPath, configPath);
+                            console.log(`[telegram] Saved lifelineTopicId=${topicId} to config`);
+                            return;
+                        }
+                    }
+                }
+            }
+        }
+        catch (err) {
+            console.warn(`[telegram] Failed to persist lifelineTopicId: ${err}`);
+        }
+    }
     /**
      * Close a forum topic.
      */

package/package.json

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