instar 0.3.5 → 0.3.6

package/dist/commands/init.d.ts

@@ -42,7 +42,8 @@ export declare function initProject(options: InitOptions): Promise<void>;
  * Refresh hooks, Claude settings, and CLAUDE.md for an existing installation.
  * Called after updates to ensure new hooks and documentation are installed.
  * Re-writes all hook files (idempotent), merges new hooks into settings,
- * and appends any missing sections to CLAUDE.md.
+ * appends any missing sections to CLAUDE.md, and installs scripts for
+ * configured integrations (e.g., Telegram relay).
  */
 export declare function refreshHooksAndSettings(projectDir: string, stateDir: string): void;
 export {};

package/dist/commands/init.js

@@ -636,13 +636,15 @@ If everything looks healthy, exit silently. Only report issues.`,
  * Refresh hooks, Claude settings, and CLAUDE.md for an existing installation.
  * Called after updates to ensure new hooks and documentation are installed.
  * Re-writes all hook files (idempotent), merges new hooks into settings,
- * and appends any missing sections to CLAUDE.md.
+ * appends any missing sections to CLAUDE.md, and installs scripts for
+ * configured integrations (e.g., Telegram relay).
  */
 export function refreshHooksAndSettings(projectDir, stateDir) {
     installHooks(stateDir);
     installClaudeSettings(projectDir);
     refreshClaudeMd(projectDir, stateDir);
     refreshJobs(stateDir);
+    refreshScripts(projectDir, stateDir);
 }
 /**
  * Merge new default jobs into existing jobs.json without overwriting user changes.
@@ -675,21 +677,116 @@ function refreshJobs(stateDir) {
     }
     catch { /* don't break on errors */ }
 }
+/**
+ * Read config.json from state dir, returning parsed config or null.
+ */
+function readConfig(stateDir) {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(stateDir, 'config.json'), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if Telegram is configured in config.json.
+ */
+function isTelegramConfigured(stateDir) {
+    const config = readConfig(stateDir);
+    if (!config)
+        return false;
+    const messaging = config.messaging;
+    return !!messaging?.some(m => m.type === 'telegram' && m.enabled);
+}
+/**
+ * Install scripts for configured integrations (e.g., Telegram relay).
+ * Called during refresh to ensure scripts exist for all configured integrations.
+ */
+function refreshScripts(projectDir, stateDir) {
+    const config = readConfig(stateDir);
+    if (!config)
+        return;
+    const port = config.port || 4040;
+    // Install telegram-reply.sh if Telegram is configured
+    if (isTelegramConfigured(stateDir)) {
+        installTelegramRelay(projectDir, port);
+    }
+}
+/**
+ * Install the Telegram relay script that Claude uses to send responses
+ * back to Telegram topics via the instar server API.
+ */
+function installTelegramRelay(projectDir, port) {
+    const scriptsDir = path.join(projectDir, '.claude', 'scripts');
+    fs.mkdirSync(scriptsDir, { recursive: true });
+    const scriptContent = `#!/bin/bash
+# telegram-reply.sh — Send a message back to a Telegram topic via instar server.
+#
+# Usage:
+#   .claude/scripts/telegram-reply.sh TOPIC_ID "message text"
+#   echo "message text" | .claude/scripts/telegram-reply.sh TOPIC_ID
+#   cat <<'EOF' | .claude/scripts/telegram-reply.sh TOPIC_ID
+#   Multi-line message here
+#   EOF
+
+TOPIC_ID="$1"
+shift
+
+if [ -z "$TOPIC_ID" ]; then
+  echo "Usage: telegram-reply.sh TOPIC_ID [message]" >&2
+  exit 1
+fi
+
+# Read message from args or stdin
+if [ $# -gt 0 ]; then
+  MSG="$*"
+else
+  MSG="$(cat)"
+fi
+
+if [ -z "$MSG" ]; then
+  echo "No message provided" >&2
+  exit 1
+fi
+
+PORT="\${INSTAR_PORT:-${port}}"
+
+# Escape for JSON
+JSON_MSG=$(printf '%s' "$MSG" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))' 2>/dev/null)
+if [ -z "$JSON_MSG" ]; then
+  # Fallback if python3 not available: basic escape
+  JSON_MSG="$(printf '%s' "$MSG" | sed 's/\\\\\\\\/\\\\\\\\\\\\\\\\/g; s/"/\\\\\\\\"/g' | sed ':a;N;$!ba;s/\\\\n/\\\\\\\\n/g')"
+  JSON_MSG="\\"$JSON_MSG\\""
+fi
+
+RESPONSE=$(curl -s -w "\\n%{http_code}" -X POST "http://localhost:\${PORT}/telegram/reply/\${TOPIC_ID}" \\
+  -H 'Content-Type: application/json' \\
+  -d "{\\"text\\":\${JSON_MSG}}")
+
+HTTP_CODE=$(echo "$RESPONSE" | tail -1)
+BODY=$(echo "$RESPONSE" | sed '$d')
+
+if [ "$HTTP_CODE" = "200" ]; then
+  echo "Sent $(echo "$MSG" | wc -c | tr -d ' ') chars to topic $TOPIC_ID"
+else
+  echo "Failed (HTTP $HTTP_CODE): $BODY" >&2
+  exit 1
+fi
+`;
+    const scriptPath = path.join(scriptsDir, 'telegram-reply.sh');
+    fs.writeFileSync(scriptPath, scriptContent, { mode: 0o755 });
+}
 /**
  * Append missing sections to CLAUDE.md without overwriting user customizations.
  * Reads config.json for port, checks for known section headers, appends if missing.
+ * Also adds Telegram relay section if Telegram is configured.
  */
 function refreshClaudeMd(projectDir, stateDir) {
     const claudeMdPath = path.join(projectDir, 'CLAUDE.md');
     if (!fs.existsSync(claudeMdPath))
         return;
-    // Read port from config
-    let port = 4321;
-    try {
-        const config = JSON.parse(fs.readFileSync(path.join(stateDir, 'config.json'), 'utf-8'));
-        port = config.port || 4321;
-    }
-    catch { /* use default port */ }
+    const config = readConfig(stateDir);
+    const port = config?.port || 4040;
     const content = fs.readFileSync(claudeMdPath, 'utf-8');
     const additions = [];
     // Check for Self-Diagnosis section
@@ -719,6 +816,22 @@ curl -s -X POST http://localhost:${port}/feedback \\
 Types: \`bug\`, \`feature\`, \`improvement\`, \`question\`
 
 **Do not wait for the user to notice.** If a hook throws an error, report it. If a job fails, report it. If the server returns unexpected data, report it. You are not just using instar — you are part of its immune system.
+`);
+    }
+    // Check for Telegram Relay section (add if Telegram is configured)
+    if (isTelegramConfigured(stateDir) && !content.includes('Telegram Relay')) {
+        additions.push(`
+## Telegram Relay
+
+When user input starts with \`[telegram:N]\`, the message came from a user via Telegram topic N. After responding, relay the response back:
+
+\`\`\`bash
+cat <<'EOF' | .claude/scripts/telegram-reply.sh N
+Your response text here
+EOF
+\`\`\`
+
+Strip the \`[telegram:N]\` prefix before interpreting the message. Only relay conversational text — not tool output.
 `);
     }
     if (additions.length > 0) {

package/dist/commands/server.js

@@ -50,20 +50,17 @@ async function respawnSessionForTopic(sessionManager, telegram, targetSession, t
     catch (err) {
         console.error(`[telegram→session] Failed to fetch thread history:`, err);
     }
-    // Always keep the user's message inline — never hide it behind a file reference.
-    // Only thread history goes into a file for supplementary context.
+    // Single-line bootstrap to avoid tmux send-keys newline issues.
+    // Thread history and context go into temp files for Claude to read.
+    const tmpDir = '/tmp/instar-telegram';
+    fs.mkdirSync(tmpDir, { recursive: true });
     let bootstrapMessage;
     if (historyLines.length > 0) {
         const historyContent = historyLines.join('\n');
-        const tmpDir = '/tmp/instar-telegram';
-        fs.mkdirSync(tmpDir, { recursive: true });
         const filepath = path.join(tmpDir, `history-${topicId}-${Date.now()}-${process.pid}.txt`);
         fs.writeFileSync(filepath, historyContent);
-        bootstrapMessage = [
-            `[telegram:${topicId}] ${msg}`,
-            ``,
-            `(Session was respawned. Thread history is at ${filepath} — read it for context. Then RESPOND to the user's message above via Telegram relay.)`,
-        ].join('\n');
+        // Single-line: user message + file reference for history
+        bootstrapMessage = `[telegram:${topicId}] ${msg} (Session respawned. Thread history at ${filepath} — read it for context before responding.)`;
     }
     else {
         bootstrapMessage = `[telegram:${topicId}] ${msg}`;
@@ -125,15 +122,22 @@ function wireTelegramRouting(telegram, sessionManager) {
             // No session mapped — auto-spawn one
             console.log(`[telegram→session] No session for topic ${topicId}, auto-spawning...`);
             const storedName = telegram.getTopicName(topicId) || `topic-${topicId}`;
-            // Always keep the user's message inline — never hide it behind a file reference
-            const bootstrapMessage = [
-                `[telegram:${topicId}] ${text}`,
-                ``,
-                `(This session was auto-created for a Telegram topic. Respond to the user's message above via Telegram relay.)`,
-            ].join('\n');
+            // Single-line bootstrap to avoid tmux send-keys newline issues.
+            // Multi-line context is written to a temp file for Claude to read.
+            const contextLines = [
+                `This session was auto-created for Telegram topic ${topicId}.`,
+                `Respond to the user's message via Telegram relay: cat <<'EOF' | .claude/scripts/telegram-reply.sh ${topicId}`,
+                `Your response here`,
+                `EOF`,
+            ];
+            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}`;
             sessionManager.spawnInteractiveSession(bootstrapMessage, storedName).then((newSessionName) => {
                 telegram.registerTopicSession(topicId, newSessionName);
-                telegram.sendToTopic(topicId, `Session auto-created. I'm here.`).catch(() => { });
+                telegram.sendToTopic(topicId, `Session created.`).catch(() => { });
                 console.log(`[telegram→session] Auto-spawned "${newSessionName}" for topic ${topicId}`);
             }).catch((err) => {
                 console.error(`[telegram→session] Auto-spawn failed:`, err);

package/dist/core/SessionManager.d.ts

@@ -88,11 +88,14 @@ export declare class SessionManager extends EventEmitter {
     injectTelegramMessage(tmuxSession: string, topicId: number, text: string): void;
     /**
      * Send text to a tmux session via send-keys.
-     * Uses -l (literal) flag for text, then sends Enter separately.
+     * For single-line text, uses -l (literal) flag directly.
+     * For multi-line text, writes to a temp file and uses tmux load-buffer/paste-buffer
+     * to avoid newlines being interpreted as Enter keypresses.
      */
     private injectMessage;
     /**
      * Wait for Claude to be ready in a tmux session by polling output.
+     * Looks for Claude Code's prompt character (❯) which appears when ready for input.
      */
     private waitForClaudeReady;
     private tmuxSessionExists;

package/dist/core/SessionManager.js

@@ -314,9 +314,15 @@ export class SessionManager extends EventEmitter {
             this.waitForClaudeReady(tmuxSession).then((ready) => {
                 if (ready) {
                     this.injectMessage(tmuxSession, initialMessage);
+                    console.log(`[SessionManager] Injected initial message into "${tmuxSession}" (${initialMessage.length} chars)`);
                 }
                 else {
-                    console.error(`[SessionManager] Claude not ready in session "${tmuxSession}" after timeout`);
+                    console.error(`[SessionManager] Claude not ready in session "${tmuxSession}" — message NOT injected. Session may need manual intervention.`);
+                    // Still try to inject — Claude might be ready but prompt detection failed
+                    if (this.tmuxSessionExists(tmuxSession)) {
+                        console.log(`[SessionManager] Session "${tmuxSession}" still alive — attempting injection anyway`);
+                        this.injectMessage(tmuxSession, initialMessage);
+                    }
                 }
             }).catch((err) => {
                 console.error(`[SessionManager] Error waiting for Claude ready in "${tmuxSession}": ${err}`);
@@ -346,19 +352,50 @@ export class SessionManager extends EventEmitter {
     }
     /**
      * Send text to a tmux session via send-keys.
-     * Uses -l (literal) flag for text, then sends Enter separately.
+     * For single-line text, uses -l (literal) flag directly.
+     * For multi-line text, writes to a temp file and uses tmux load-buffer/paste-buffer
+     * to avoid newlines being interpreted as Enter keypresses.
      */
     injectMessage(tmuxSession, text) {
         const exactTarget = `=${tmuxSession}:`;
         try {
-            // Send the text literally
-            execFileSync(this.config.tmuxPath, ['send-keys', '-t', exactTarget, '-l', text], {
-                encoding: 'utf-8', timeout: 5000,
-            });
-            // Send Enter separately
-            execFileSync(this.config.tmuxPath, ['send-keys', '-t', exactTarget, 'Enter'], {
-                encoding: 'utf-8', timeout: 5000,
-            });
+            if (text.includes('\n')) {
+                // Multi-line: write to temp file, load into tmux buffer, paste into pane.
+                // This avoids newlines being treated as Enter keypresses which would
+                // fragment the message into multiple Claude prompts.
+                const tmpDir = path.join('/tmp', 'instar-inject');
+                fs.mkdirSync(tmpDir, { recursive: true });
+                const tmpPath = path.join(tmpDir, `msg-${Date.now()}-${process.pid}.txt`);
+                fs.writeFileSync(tmpPath, text);
+                try {
+                    execFileSync(this.config.tmuxPath, ['load-buffer', tmpPath], {
+                        encoding: 'utf-8', timeout: 5000,
+                    });
+                    execFileSync(this.config.tmuxPath, ['paste-buffer', '-t', exactTarget, '-p'], {
+                        encoding: 'utf-8', timeout: 5000,
+                    });
+                    // Send Enter to submit
+                    execFileSync(this.config.tmuxPath, ['send-keys', '-t', exactTarget, 'Enter'], {
+                        encoding: 'utf-8', timeout: 5000,
+                    });
+                }
+                finally {
+                    try {
+                        fs.unlinkSync(tmpPath);
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+            else {
+                // Single-line: simple send-keys
+                execFileSync(this.config.tmuxPath, ['send-keys', '-t', exactTarget, '-l', text], {
+                    encoding: 'utf-8', timeout: 5000,
+                });
+                // Send Enter separately
+                execFileSync(this.config.tmuxPath, ['send-keys', '-t', exactTarget, 'Enter'], {
+                    encoding: 'utf-8', timeout: 5000,
+                });
+            }
         }
         catch (err) {
             console.error(`[SessionManager] Failed to inject message into ${tmuxSession}: ${err}`);
@@ -366,20 +403,29 @@ export class SessionManager extends EventEmitter {
     }
     /**
      * Wait for Claude to be ready in a tmux session by polling output.
+     * Looks for Claude Code's prompt character (❯) which appears when ready for input.
      */
-    async waitForClaudeReady(tmuxSession, timeoutMs = 15000) {
+    async waitForClaudeReady(tmuxSession, timeoutMs = 30000) {
         const start = Date.now();
         // Wait a minimum startup delay before checking (Claude needs time to load)
-        await new Promise(r => setTimeout(r, 2000));
+        await new Promise(r => setTimeout(r, 3000));
         while (Date.now() - start < timeoutMs) {
+            if (!this.tmuxSessionExists(tmuxSession)) {
+                console.error(`[SessionManager] Session "${tmuxSession}" died during startup`);
+                return false;
+            }
             const output = this.captureOutput(tmuxSession, 10);
             // Check for Claude Code's specific prompt character (❯)
             // Avoid matching generic shell prompts (> and $) which cause false positives
             if (output && output.includes('❯')) {
+                console.log(`[SessionManager] Claude ready in "${tmuxSession}" after ${Date.now() - start}ms`);
                 return true;
             }
             await new Promise(r => setTimeout(r, 500));
         }
+        // Log what we see on timeout for debugging
+        const finalOutput = this.captureOutput(tmuxSession, 20);
+        console.error(`[SessionManager] Claude not ready in "${tmuxSession}" after ${timeoutMs}ms. Output: ${(finalOutput || '').slice(-200)}`);
         return false;
     }
     tmuxSessionExists(name) {

package/package.json

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