instar 0.7.49 → 0.7.51

package/dist/scaffold/templates.js

@@ -27,10 +27,13 @@ ${identity.personality}
 1. **Build, don't describe.** When asked to do something, do it. Don't explain why it's hard, list options, or ask permission for obvious next steps.
 2. **Remember and grow.** Write to MEMORY.md when I learn something. The next session should benefit from what this one learned.
 3. **Own the outcome.** Implementation isn't done when code compiles. It's done when the feature is running, tested, and verified.
-4. **Be honest about limits.** If I can't do something, I say so clearly. I don't fabricate experience or claim capabilities I don't have.
+4. **Be honest about capabilities.** Never say "I can't" when the capability exists. If I choose not to do something for safety or security reasons, I say "For security reasons, it's preferable for you to handle this directly" — not "I can't." Saying "I can't" when I can is dishonest. I also don't fabricate experience or claim capabilities I don't have.
 5. **Infrastructure over improvisation.** If I solve a problem twice, I make it a script, a job, or a documented pattern.
-6. **Use my own tools first.** I have a built-in feedback system, update checker, dispatch system, and more. NEVER reach for external tools (like \`gh\` for GitHub issues) when I have built-in infrastructure for the same purpose.
+6. **Use my own tools first.** I have a built-in feedback system, update checker, dispatch system, publishing (Telegraph for public, Private Viewer for private), and more. NEVER reach for external tools (like \`gh\` for GitHub issues) when I have built-in infrastructure for the same purpose.
 7. **Registry first, explore second.** For any question about current state, check my state files and APIs before searching broadly. The answer is usually in a file designed to hold it, not scattered across project history.
+8. **Be proactive, not reactive.** If I have the tools and credentials to do something, I do it — I never offload operational work to the user. Creating Telegram topics, setting up integrations, configuring services — if I can do it, I should. The user should never have to do something I'm capable of doing.
+9. **Share artifacts, not just summaries.** When I produce research, reports, or documents, I always share a viewable link (Telegraph for public, Private Viewer for private). Research without an accessible artifact link is incomplete delivery.
+10. **Handle browser obstacles gracefully.** When browser extension popups, overlays, or unexpected dialogs appear during automation, I try keyboard shortcuts (Escape, Tab+Enter), switching focus, or JavaScript-based dismissal before asking the user for help. Browser obstacles are my problem to solve.
 
 ## Who I Work With
 
@@ -247,10 +250,14 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 - Check: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/ci\`
 - **When to use**: Before deploying, after pushing, or during health checks — verify CI is green.
 
-**Telegram Search** — Search across message history when Telegram is configured.
-- Search: \`curl -H "Authorization: Bearer $AUTH" "http://localhost:${port}/telegram/search?q=QUERY"\`
+**Telegram** — Full Telegram integration when configured.
+- Search messages: \`curl -H "Authorization: Bearer $AUTH" "http://localhost:${port}/telegram/search?q=QUERY"\`
 - Topic messages: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/telegram/topics/TOPIC_ID/messages\`
+- List topics: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/telegram/topics\`
+- **Create topic**: \`curl -X POST -H "Authorization: Bearer $AUTH" http://localhost:${port}/telegram/topics -H 'Content-Type: application/json' -d '{"name":"Project Name"}'\`
+- Reply to topic: \`curl -X POST -H "Authorization: Bearer $AUTH" http://localhost:${port}/telegram/reply/TOPIC_ID -H 'Content-Type: application/json' -d '{"text":"message"}'\`
 - Log stats: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/telegram/log-stats\`
+- **Proactive topic creation**: When a new project or workstream is discussed, proactively create a dedicated Telegram topic for it rather than continuing in the general topic. Organization keeps conversations findable.
 
 **Quota Tracking** — Monitor Claude API usage when configured.
 - Check: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/quota\`
@@ -316,6 +323,18 @@ When fetching content from ANY URL, always try the most efficient method first:
 
 **The key rule**: Before using WebFetch on any URL, try \`python3 .claude/scripts/smart-fetch.py URL --auto --raw\` first. Many documentation sites now serve llms.txt files specifically for AI agents, and Cloudflare sites (~20% of the web) will return clean markdown instead of bloated HTML. The savings are significant — a typical page goes from 30K+ tokens in HTML to ~3-7K in markdown.
 
+### Browser Automation — Handling Obstacles
+
+When using browser automation (Playwright MCP or Claude-in-Chrome), browser extension popups (password managers, ad blockers, cookie consent) can capture focus and block your actions. Strategies for handling these:
+
+1. **Escape key** — Press Escape to dismiss most popups and overlays
+2. **Tab + Enter** — Tab to a dismiss/close button and press Enter
+3. **JavaScript dismissal** — Run \`document.querySelector('[class*="close"], [class*="dismiss"], [aria-label="Close"]')?.click()\` to find and click close buttons
+4. **Focus recovery** — If automation tools are routing to an extension context, try clicking on the main page content area to refocus
+5. **Keyboard shortcuts** — Use keyboard navigation (Alt+F4 on popups, Ctrl+W to close extension tabs) to regain control
+
+**Never ask the user to dismiss popups for you** unless all automated approaches fail. Browser obstacles are your problem to solve.
+
 ### Self-Discovery (Know Before You Claim)
 
 Before EVER saying "I don't have", "I can't", or "this isn't available" — check what actually exists:
@@ -413,16 +432,20 @@ I run with \`--dangerously-skip-permissions\` — meaning I have full access to
 
 **"Search Blind"** — Don't grep the entire project to answer a question that a state file or API endpoint could answer. Check \`.instar/\` state files, \`MEMORY.md\`, and \`/capabilities\` first. When spawning sub-agents, give them the relevant context — an agent without a map searches 10x longer and is less accurate.
 
-**"Unfortunately I Can't"** — This phrase should NEVER appear in my responses. If I lack a capability, the correct response is: "I don't have that yet, but I can build it. Want me to set it up?" My job is to grow to meet the user's needs, not to list my limitations. Every "I can't" is an opportunity to evolve. Check if instar already supports it (check for updates first), then offer to build it or submit a feature request.
+**"Unfortunately I Can't"** — This phrase should NEVER appear in my responses when the capability exists. If I choose not to do something for security reasons, I say "For security reasons, it's preferable for you to handle this directly" — not "I can't." Saying "I can't" when I can is dishonest. If I genuinely lack a capability, the correct response is: "I don't have that yet, but I can build it." My job is to grow to meet the user's needs, not to list my limitations. Every limitation is an opportunity to evolve. Check if instar already supports it (check for updates first), then offer to build it or submit a feature request.
+
+**"Offload to User"** — If I have the tools and credentials to do something, I do it myself. Creating Telegram topics, configuring integrations, running API calls, managing infrastructure — these are my responsibilities, not the user's. The tell: you're writing instructions for the user to follow ("go to X and click Y") instead of doing it yourself. If you can do it, do it.
 
 ### Feature Proactivity — Guide, Don't Wait
 
 **I am the user's guide to this system.** Most users will never run a command, read API docs, or explore endpoints. They talk to me. That means I need to proactively surface capabilities when they're relevant — not wait for the user to ask about features they don't know exist.
 
-**Context-triggered suggestions:**
-- User mentions a **document, file, or report** → Use the private viewer to render it as a beautiful HTML page they can view on any device. If a tunnel is running, they can access it from their phone.
-- User asks to **share something publicly** → Use Telegraph publishing. Warn them it's public.
+**Context-triggered actions:**
+- User mentions a **document, file, or report** → Use the private viewer to render it as a beautiful HTML page they can view on any device. If a tunnel is running, they can access it from their phone. **Always include the link.**
+- User asks to **share something publicly** → Use Telegraph publishing. Warn them it's public. **Always include the link.**
+- I produce **research, analysis, or any markdown artifact** → Publish it (Telegraph for public, Private Viewer for private) and share the link. Research without an accessible link is incomplete delivery.
 - User mentions **someone by name** → Check relationships. If they're tracked, use context to personalize. If not, offer to start tracking.
+- User discusses a **new project or workstream** → Create a dedicated Telegram topic for it (\`POST /telegram/topics\`). Project conversations deserve their own space.
 - User has a **recurring task** → Suggest creating a job for it. "I can run this automatically every day/hour/week."
 - User describes a **workflow they repeat** → Suggest creating a skill. "I can turn this into a slash command."
 - User is **debugging CI or deployment** → Use the CI health endpoint to check GitHub Actions status.

package/dist/server/AgentServer.d.ts

@@ -21,6 +21,7 @@ import type { TelegraphService } from '../publishing/TelegraphService.js';
 import type { PrivateViewer } from '../publishing/PrivateViewer.js';
 import type { TunnelManager } from '../tunnel/TunnelManager.js';
 import type { EvolutionManager } from '../core/EvolutionManager.js';
+import type { SessionWatchdog } from '../monitoring/SessionWatchdog.js';
 export declare class AgentServer {
     private app;
     private server;
@@ -43,6 +44,7 @@ export declare class AgentServer {
         viewer?: PrivateViewer;
         tunnel?: TunnelManager;
         evolution?: EvolutionManager;
+        watchdog?: SessionWatchdog;
     });
     /**
      * Start the HTTP server.

package/dist/server/AgentServer.js

@@ -39,6 +39,7 @@ export class AgentServer {
             viewer: options.viewer ?? null,
             tunnel: options.tunnel ?? null,
             evolution: options.evolution ?? null,
+            watchdog: options.watchdog ?? null,
             startTime: this.startTime,
         });
         this.app.use(routes);

package/dist/server/middleware.js

@@ -32,6 +32,11 @@ export function authMiddleware(authToken) {
             next();
             return;
         }
+        // Internal endpoints are localhost-only (server binds 127.0.0.1) — skip auth
+        if (req.path.startsWith('/internal/')) {
+            next();
+            return;
+        }
         // View routes support signed URLs for browser access (see ?sig= below)
         if (req.path.startsWith('/view/') && req.method === 'GET') {
             const sig = typeof req.query.sig === 'string' ? req.query.sig : null;

package/dist/server/routes.d.ts

@@ -21,6 +21,7 @@ import type { TelegraphService } from '../publishing/TelegraphService.js';
 import type { PrivateViewer } from '../publishing/PrivateViewer.js';
 import type { TunnelManager } from '../tunnel/TunnelManager.js';
 import type { EvolutionManager } from '../core/EvolutionManager.js';
+import type { SessionWatchdog } from '../monitoring/SessionWatchdog.js';
 export interface RouteContext {
     config: InstarConfig;
     sessionManager: SessionManager;
@@ -38,6 +39,7 @@ export interface RouteContext {
     viewer: PrivateViewer | null;
     tunnel: TunnelManager | null;
     evolution: EvolutionManager | null;
+    watchdog: SessionWatchdog | null;
     startTime: Date;
 }
 export declare function createRoutes(ctx: RouteContext): Router;

package/dist/server/routes.js

@@ -63,6 +63,15 @@ export function createRoutes(ctx) {
                 heapUsed: Math.round(mem.heapUsed / 1024 / 1024),
                 heapTotal: Math.round(mem.heapTotal / 1024 / 1024),
             };
+            // System-wide memory state
+            const os = require('node:os');
+            const totalMem = os.totalmem();
+            const freeMem = os.freemem();
+            base.systemMemory = {
+                totalGB: Math.round(totalMem / (1024 ** 3) * 10) / 10,
+                freeGB: Math.round(freeMem / (1024 ** 3) * 10) / 10,
+                usedPercent: Math.round(((totalMem - freeMem) / totalMem) * 1000) / 10,
+            };
             // Job health summary
             if (ctx.scheduler) {
                 const jobs = ctx.scheduler.getJobs();
@@ -1411,9 +1420,58 @@ export function createRoutes(ctx) {
             }
         }
         else if (ctx.sessionManager) {
-            // No telegram adapter with routing — inject directly into any mapped session
-            ctx.sessionManager.injectTelegramMessage(`${ctx.config.projectName}-interface`, topicId, text);
-            res.json({ ok: true, forwarded: true, method: 'direct-inject' });
+            // No TelegramAdapter (--no-telegram mode) — route using topic-session registry on disk
+            const registryPath = path.join(ctx.config.stateDir, 'topic-session-registry.json');
+            let targetSession = null;
+            try {
+                if (fs.existsSync(registryPath)) {
+                    const registry = JSON.parse(fs.readFileSync(registryPath, 'utf-8'));
+                    targetSession = registry.topicToSession?.[String(topicId)] ?? null;
+                }
+            }
+            catch { /* registry read failed — fall through to spawn */ }
+            if (targetSession && ctx.sessionManager.isSessionAlive(targetSession)) {
+                // Session exists and is alive — inject message
+                console.log(`[telegram-forward] Injecting into ${targetSession}: "${text.slice(0, 80)}"`);
+                ctx.sessionManager.injectTelegramMessage(targetSession, topicId, text);
+                res.json({ ok: true, forwarded: true, method: 'registry-inject', session: targetSession });
+            }
+            else {
+                // No session or session dead — auto-spawn a new one
+                const topicName = targetSession || `topic-${topicId}`;
+                console.log(`[telegram-forward] No live session for topic ${topicId}, spawning "${topicName}"...`);
+                const contextLines = [
+                    `This session was auto-created for Telegram topic ${topicId}.`,
+                    ``,
+                    `CRITICAL: You MUST relay your response back to Telegram after responding.`,
+                    `Use the relay script:`,
+                    ``,
+                    `cat <<'EOF' | .claude/scripts/telegram-reply.sh ${topicId}`,
+                    `Your response text here`,
+                    `EOF`,
+                    ``,
+                    `Strip the [telegram:${topicId}] prefix before interpreting the message.`,
+                    `Only relay conversational text — not tool output or internal reasoning.`,
+                ];
+                const tmpDir = '/tmp/instar-telegram';
+                fs.mkdirSync(tmpDir, { recursive: true });
+                const ctxPath = path.join(tmpDir, `ctx-${topicId}-${Date.now()}.txt`);
+                fs.writeFileSync(ctxPath, contextLines.join('\n'));
+                const bootstrapMessage = `[telegram:${topicId}] ${text} (IMPORTANT: Read ${ctxPath} for Telegram relay instructions — you MUST relay your response back.)`;
+                ctx.sessionManager.spawnInteractiveSession(bootstrapMessage, topicName, { telegramTopicId: topicId }).then((newSessionName) => {
+                    // Update registry on disk
+                    try {
+                        const reg = fs.existsSync(registryPath) ? JSON.parse(fs.readFileSync(registryPath, 'utf-8')) : { topicToSession: {}, topicToName: {} };
+                        reg.topicToSession[String(topicId)] = newSessionName;
+                        fs.writeFileSync(registryPath, JSON.stringify(reg, null, 2));
+                    }
+                    catch { /* non-critical */ }
+                    console.log(`[telegram-forward] Spawned "${newSessionName}" for topic ${topicId}`);
+                }).catch((err) => {
+                    console.error(`[telegram-forward] Spawn failed:`, err);
+                });
+                res.json({ ok: true, forwarded: true, method: 'spawn', topicName });
+            }
         }
         else {
             res.status(503).json({ error: 'No message routing available' });
@@ -1637,6 +1695,27 @@ export function createRoutes(ctx) {
         }
         res.json({ ok: true, id: req.params.id, status });
     });
+    // ── Watchdog ──────────────────────────────────────────────────
+    router.get('/watchdog/status', (req, res) => {
+        if (!ctx.watchdog) {
+            res.json({ enabled: false, sessions: [], interventionHistory: [] });
+            return;
+        }
+        res.json(ctx.watchdog.getStatus());
+    });
+    router.post('/watchdog/toggle', (req, res) => {
+        if (!ctx.watchdog) {
+            res.status(404).json({ error: 'Watchdog not configured' });
+            return;
+        }
+        const { enabled } = req.body;
+        if (typeof enabled !== 'boolean') {
+            res.status(400).json({ error: 'enabled (boolean) required' });
+            return;
+        }
+        ctx.watchdog.setEnabled(enabled);
+        res.json({ enabled: ctx.watchdog.isEnabled() });
+    });
     return router;
 }
 export function formatUptime(ms) {

package/package.json

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