instar 0.1.0

package/src/messaging/TelegramAdapter.ts

@@ -0,0 +1,365 @@
+/**
+ * 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.
+ *
+ * No external dependencies — uses native fetch for Telegram API calls.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import type { MessagingAdapter, Message, OutgoingMessage, UserChannel } from '../core/types.js';
+
+interface TelegramConfig {
+  /** Bot token from @BotFather */
+  token: string;
+  /** Forum chat ID (the supergroup where topics live) */
+  chatId: string;
+  /** Polling interval in ms */
+  pollIntervalMs?: number;
+}
+
+interface TelegramUpdate {
+  update_id: number;
+  message?: {
+    message_id: number;
+    from: { id: number; first_name: string; username?: string };
+    chat: { id: number };
+    message_thread_id?: number;
+    text?: string;
+    date: number;
+    reply_to_message?: {
+      message_id: number;
+      forum_topic_created?: { name: string };
+    };
+  };
+}
+
+interface LogEntry {
+  messageId: number;
+  topicId: number | null;
+  text: string;
+  fromUser: boolean;
+  timestamp: string;
+  sessionName: string | null;
+}
+
+export class TelegramAdapter implements MessagingAdapter {
+  readonly platform = 'telegram';
+
+  private config: TelegramConfig;
+  private handler: ((message: Message) => Promise<void>) | null = null;
+  private polling = false;
+  private pollTimeout: ReturnType<typeof setTimeout> | null = null;
+  private lastUpdateId = 0;
+
+  // Topic-session registry (persisted to disk)
+  private topicToSession: Map<number, string> = new Map();
+  private sessionToTopic: Map<string, number> = new Map();
+  private topicToName: Map<number, string> = new Map();
+  private registryPath: string;
+  private messageLogPath: string;
+
+  // Topic message callback — fires on every incoming topic message
+  public onTopicMessage: ((message: Message) => void) | null = null;
+
+  constructor(config: TelegramConfig, stateDir: string) {
+    this.config = config;
+    this.registryPath = path.join(stateDir, 'topic-session-registry.json');
+    this.messageLogPath = path.join(stateDir, 'telegram-messages.jsonl');
+    this.loadRegistry();
+  }
+
+  async start(): Promise<void> {
+    if (this.polling) return;
+    this.polling = true;
+    console.log(`[telegram] Starting long-polling...`);
+    this.poll();
+  }
+
+  async stop(): Promise<void> {
+    this.polling = false;
+    if (this.pollTimeout) {
+      clearTimeout(this.pollTimeout);
+      this.pollTimeout = null;
+    }
+  }
+
+  async send(message: OutgoingMessage): Promise<void> {
+    const topicId = message.channel?.identifier;
+    const params: Record<string, unknown> = {
+      chat_id: this.config.chatId,
+      text: message.content,
+      parse_mode: 'Markdown',
+    };
+
+    if (topicId && parseInt(topicId) > 1) {
+      params.message_thread_id = parseInt(topicId);
+    }
+
+    try {
+      await this.apiCall('sendMessage', params);
+    } catch {
+      // Fallback to plain text on parse errors
+      delete params.parse_mode;
+      await this.apiCall('sendMessage', params);
+    }
+  }
+
+  /**
+   * Send a message to a specific forum topic.
+   */
+  async sendToTopic(topicId: number, text: string): Promise<void> {
+    const params: Record<string, unknown> = {
+      chat_id: this.config.chatId,
+      text,
+    };
+    // Topic ID 1 = General topic (our fallback) — omit message_thread_id for General
+    if (topicId > 1) {
+      params.message_thread_id = topicId;
+    }
+
+    try {
+      await this.apiCall('sendMessage', { ...params, parse_mode: 'Markdown' });
+    } catch {
+      await this.apiCall('sendMessage', params);
+    }
+
+    // Log outbound messages too
+    this.appendToLog({
+      messageId: 0,
+      topicId,
+      text,
+      fromUser: false,
+      timestamp: new Date().toISOString(),
+      sessionName: this.topicToSession.get(topicId) ?? null,
+    });
+  }
+
+  /**
+   * Create a forum topic in the supergroup.
+   */
+  async createForumTopic(name: string, iconColor?: number): Promise<{ topicId: number; name: string }> {
+    const params: Record<string, unknown> = {
+      chat_id: this.config.chatId,
+      name,
+    };
+    if (iconColor !== undefined) {
+      params.icon_color = iconColor;
+    }
+
+    const result = await this.apiCall('createForumTopic', params) as {
+      message_thread_id: number;
+      name: string;
+    };
+
+    this.topicToName.set(result.message_thread_id, name);
+    this.saveRegistry();
+
+    console.log(`[telegram] Created forum topic: "${name}" (ID: ${result.message_thread_id})`);
+    return { topicId: result.message_thread_id, name: result.name };
+  }
+
+  onMessage(handler: (message: Message) => Promise<void>): void {
+    this.handler = handler;
+  }
+
+  async resolveUser(channelIdentifier: string): Promise<string | null> {
+    return null;
+  }
+
+  // ── Topic-Session Registry ─────────────────────────────────
+
+  registerTopicSession(topicId: number, sessionName: string): void {
+    this.topicToSession.set(topicId, sessionName);
+    this.sessionToTopic.set(sessionName, topicId);
+    this.saveRegistry();
+    console.log(`[telegram] Registered topic ${topicId} <-> session "${sessionName}"`);
+  }
+
+  getSessionForTopic(topicId: number): string | null {
+    return this.topicToSession.get(topicId) ?? null;
+  }
+
+  getTopicForSession(sessionName: string): number | null {
+    return this.sessionToTopic.get(sessionName) ?? null;
+  }
+
+  getTopicName(topicId: number): string | null {
+    return this.topicToName.get(topicId) ?? null;
+  }
+
+  // ── Message Log ────────────────────────────────────────────
+
+  /**
+   * Get recent messages for a topic (for thread history on respawn).
+   */
+  getTopicHistory(topicId: number, limit: number = 20): LogEntry[] {
+    if (!fs.existsSync(this.messageLogPath)) return [];
+
+    const lines = fs.readFileSync(this.messageLogPath, 'utf-8')
+      .split('\n')
+      .filter(Boolean);
+
+    const matching: LogEntry[] = [];
+    for (const line of lines) {
+      try {
+        const entry: LogEntry = JSON.parse(line);
+        if (entry.topicId === topicId) {
+          matching.push(entry);
+        }
+      } catch { /* skip malformed */ }
+    }
+
+    return matching.slice(-limit);
+  }
+
+  private appendToLog(entry: LogEntry): void {
+    try {
+      fs.appendFileSync(this.messageLogPath, JSON.stringify(entry) + '\n');
+    } catch (err) {
+      console.error(`[telegram] Failed to append to message log: ${err}`);
+    }
+  }
+
+  // ── Registry Persistence ───────────────────────────────────
+
+  private loadRegistry(): void {
+    try {
+      const data = JSON.parse(fs.readFileSync(this.registryPath, 'utf-8'));
+      if (data.topicToSession) {
+        for (const [k, v] of Object.entries(data.topicToSession)) {
+          this.topicToSession.set(Number(k), v as string);
+          this.sessionToTopic.set(v as string, Number(k));
+        }
+      }
+      if (data.topicToName) {
+        for (const [k, v] of Object.entries(data.topicToName)) {
+          this.topicToName.set(Number(k), v as string);
+        }
+      }
+      console.log(`[telegram] Loaded ${this.topicToSession.size} topic-session mappings from disk`);
+    } catch {
+      // File doesn't exist yet — start fresh
+    }
+  }
+
+  private saveRegistry(): void {
+    try {
+      const data = {
+        topicToSession: Object.fromEntries(this.topicToSession),
+        topicToName: Object.fromEntries(this.topicToName),
+      };
+      fs.writeFileSync(this.registryPath, JSON.stringify(data, null, 2));
+    } catch (err) {
+      console.error(`[telegram] Failed to save registry: ${err}`);
+    }
+  }
+
+  // ── Polling ────────────────────────────────────────────────
+
+  private async poll(): Promise<void> {
+    if (!this.polling) return;
+
+    try {
+      const updates = await this.getUpdates();
+      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: 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) {
+            this.onTopicMessage(message);
+          }
+
+          // Fire general handler
+          if (this.handler) {
+            try {
+              await this.handler(message);
+            } catch (err) {
+              console.error(`[telegram] Handler error: ${err}`);
+            }
+          }
+        }
+
+        this.lastUpdateId = Math.max(this.lastUpdateId, update.update_id);
+      }
+    } catch (err) {
+      console.error(`[telegram] Poll error: ${err}`);
+    }
+
+    // Schedule next poll
+    const interval = this.config.pollIntervalMs ?? 2000;
+    this.pollTimeout = setTimeout(() => this.poll(), interval);
+  }
+
+  private async getUpdates(): Promise<TelegramUpdate[]> {
+    const result = await this.apiCall('getUpdates', {
+      offset: this.lastUpdateId + 1,
+      timeout: 30,
+      allowed_updates: ['message'],
+    });
+
+    return (result as TelegramUpdate[]) ?? [];
+  }
+
+  private async apiCall(method: string, params: Record<string, unknown>): Promise<unknown> {
+    const url = `https://api.telegram.org/bot${this.config.token}/${method}`;
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(params),
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`Telegram API error (${response.status}): ${text}`);
+    }
+
+    const data = await response.json() as { ok: boolean; result: unknown };
+    if (!data.ok) {
+      throw new Error(`Telegram API returned not ok: ${JSON.stringify(data)}`);
+    }
+
+    return data.result;
+  }
+}

package/src/monitoring/HealthChecker.ts

@@ -0,0 +1,172 @@
+/**
+ * Health Checker — aggregates component health into a single status.
+ *
+ * Checks tmux availability, session state, scheduler health,
+ * and disk space. Returns a HealthStatus object.
+ */
+
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import type { SessionManager } from '../core/SessionManager.js';
+import type { JobScheduler } from '../scheduler/JobScheduler.js';
+import type { HealthStatus, ComponentHealth, AgentKitConfig } from '../core/types.js';
+
+export class HealthChecker {
+  private config: AgentKitConfig;
+  private sessionManager: SessionManager;
+  private scheduler: JobScheduler | null;
+  private checkInterval: ReturnType<typeof setInterval> | null = null;
+  private lastStatus: HealthStatus | null = null;
+
+  constructor(
+    config: AgentKitConfig,
+    sessionManager: SessionManager,
+    scheduler: JobScheduler | null = null,
+  ) {
+    this.config = config;
+    this.sessionManager = sessionManager;
+    this.scheduler = scheduler;
+  }
+
+  /**
+   * Run all health checks and return aggregated status.
+   */
+  check(): HealthStatus {
+    const components: Record<string, ComponentHealth> = {};
+
+    components.tmux = this.checkTmux();
+    components.sessions = this.checkSessions();
+    components.stateDir = this.checkStateDir();
+
+    if (this.scheduler) {
+      components.scheduler = this.checkScheduler();
+    }
+
+    // Aggregate: worst component status becomes overall status
+    const statuses = Object.values(components).map(c => c.status);
+    let overall: HealthStatus['status'] = 'healthy';
+    if (statuses.includes('unhealthy')) overall = 'unhealthy';
+    else if (statuses.includes('degraded')) overall = 'degraded';
+
+    this.lastStatus = {
+      status: overall,
+      components,
+      timestamp: new Date().toISOString(),
+    };
+
+    return this.lastStatus;
+  }
+
+  /**
+   * Get the last computed health status without re-checking.
+   */
+  getLastStatus(): HealthStatus | null {
+    return this.lastStatus;
+  }
+
+  /**
+   * Start periodic health checks.
+   */
+  startPeriodicChecks(intervalMs?: number): void {
+    if (this.checkInterval) return;
+
+    const interval = intervalMs ?? this.config.monitoring.healthCheckIntervalMs;
+    this.check(); // Run immediately
+    this.checkInterval = setInterval(() => this.check(), interval);
+  }
+
+  /**
+   * Stop periodic health checks.
+   */
+  stopPeriodicChecks(): void {
+    if (this.checkInterval) {
+      clearInterval(this.checkInterval);
+      this.checkInterval = null;
+    }
+  }
+
+  private checkTmux(): ComponentHealth {
+    const now = new Date().toISOString();
+    try {
+      execSync(`${this.config.sessions.tmuxPath} list-sessions 2>/dev/null`, {
+        encoding: 'utf-8',
+        timeout: 3000,
+      });
+      return { status: 'healthy', message: 'tmux server responding', lastCheck: now };
+    } catch {
+      // tmux server not running is ok if no sessions needed
+      try {
+        execSync(`${this.config.sessions.tmuxPath} -V`, { encoding: 'utf-8', timeout: 3000 });
+        return { status: 'healthy', message: 'tmux available (no server running)', lastCheck: now };
+      } catch {
+        return { status: 'unhealthy', message: 'tmux binary not found', lastCheck: now };
+      }
+    }
+  }
+
+  private checkSessions(): ComponentHealth {
+    const now = new Date().toISOString();
+    try {
+      const running = this.sessionManager.listRunningSessions();
+      const max = this.config.sessions.maxSessions;
+
+      if (running.length >= max) {
+        return {
+          status: 'degraded',
+          message: `At capacity: ${running.length}/${max} sessions`,
+          lastCheck: now,
+        };
+      }
+
+      return {
+        status: 'healthy',
+        message: `${running.length}/${max} sessions active`,
+        lastCheck: now,
+      };
+    } catch (err: any) {
+      return { status: 'unhealthy', message: `Session check failed: ${err.message}`, lastCheck: now };
+    }
+  }
+
+  private checkScheduler(): ComponentHealth {
+    const now = new Date().toISOString();
+    if (!this.scheduler) {
+      return { status: 'healthy', message: 'Scheduler not configured', lastCheck: now };
+    }
+
+    const status = this.scheduler.getStatus();
+
+    if (!status.running) {
+      return { status: 'degraded', message: 'Scheduler not running', lastCheck: now };
+    }
+
+    if (status.paused) {
+      return { status: 'degraded', message: 'Scheduler paused', lastCheck: now };
+    }
+
+    return {
+      status: 'healthy',
+      message: `Running: ${status.enabledJobs} jobs, ${status.queueLength} queued`,
+      lastCheck: now,
+    };
+  }
+
+  private checkStateDir(): ComponentHealth {
+    const now = new Date().toISOString();
+    try {
+      const exists = fs.existsSync(this.config.stateDir);
+      if (!exists) {
+        return { status: 'unhealthy', message: 'State directory missing', lastCheck: now };
+      }
+
+      // Check we can write
+      const testFile = `${this.config.stateDir}/.health-check-${Date.now()}`;
+      fs.writeFileSync(testFile, 'ok');
+      fs.unlinkSync(testFile);
+
+      return { status: 'healthy', message: 'State directory writable', lastCheck: now };
+    } catch (err: any) {
+      return { status: 'unhealthy', message: `State dir error: ${err.message}`, lastCheck: now };
+    }
+  }
+}

package/src/scaffold/bootstrap.ts

@@ -0,0 +1,122 @@
+/**
+ * Identity bootstrap — interactive flow for creating the agent's identity.
+ *
+ * On first run, walks the user through defining who their agent is.
+ * Writes AGENT.md, USER.md, and MEMORY.md based on their answers.
+ *
+ * Inspired by OpenClaw's SOUL.md co-creation — but adapted for
+ * persistent infrastructure rather than conversational personality.
+ */
+
+import { input, select } from '@inquirer/prompts';
+import pc from 'picocolors';
+import type { AgentIdentity } from './templates.js';
+
+/**
+ * Run the interactive identity bootstrap.
+ * Returns the agent identity for template generation.
+ */
+export async function bootstrapIdentity(projectName: string): Promise<AgentIdentity> {
+  console.log();
+  console.log(pc.bold('  Identity Bootstrap'));
+  console.log(pc.dim('  Let\'s define who your agent is. This takes about 30 seconds.'));
+  console.log(pc.dim('  You can always change these later by editing .instar/AGENT.md'));
+  console.log();
+
+  // Agent name
+  const name = await input({
+    message: 'What should your agent be called?',
+    default: capitalize(projectName),
+    validate: (v) => v.trim().length > 0 ? true : 'Name is required',
+  });
+
+  // Agent role
+  const roleChoice = await select({
+    message: 'What\'s their primary role?',
+    choices: [
+      {
+        name: 'General-purpose autonomous agent',
+        value: 'I am a general-purpose autonomous agent. I build, maintain, and evolve this project.',
+      },
+      {
+        name: 'Development assistant (code-focused)',
+        value: 'I am a development agent. I write code, run tests, review PRs, and maintain code quality for this project.',
+      },
+      {
+        name: 'Operations agent (monitoring, automation)',
+        value: 'I am an operations agent. I monitor systems, automate workflows, handle alerts, and keep infrastructure running.',
+      },
+      {
+        name: 'Research agent (analysis, exploration)',
+        value: 'I am a research agent. I explore topics, analyze data, synthesize findings, and surface insights.',
+      },
+      {
+        name: 'Custom (I\'ll describe it)',
+        value: '__custom__',
+      },
+    ],
+  });
+
+  const role = roleChoice === '__custom__'
+    ? await input({ message: 'Describe their role in one sentence' })
+    : roleChoice;
+
+  // Personality
+  const personalityChoice = await select({
+    message: 'What\'s their personality like?',
+    choices: [
+      {
+        name: 'Direct and efficient — gets things done with minimal fuss',
+        value: 'I am direct and efficient. I focus on outcomes, communicate concisely, and value action over discussion. When something needs doing, I do it.',
+      },
+      {
+        name: 'Thoughtful and thorough — considers carefully before acting',
+        value: 'I am thoughtful and thorough. I consider implications before acting, document my reasoning, and prefer getting things right over getting them fast.',
+      },
+      {
+        name: 'Curious and exploratory — learns and experiments actively',
+        value: 'I am curious and exploratory. I investigate deeply, try new approaches, and treat every problem as an opportunity to learn something. I document what I discover.',
+      },
+      {
+        name: 'Warm and collaborative — works as a true partner',
+        value: 'I am warm and collaborative. I communicate openly, celebrate progress, and treat my work as a genuine partnership with the people I work with.',
+      },
+      {
+        name: 'Custom (I\'ll describe it)',
+        value: '__custom__',
+      },
+    ],
+  });
+
+  const personality = personalityChoice === '__custom__'
+    ? await input({ message: 'Describe their personality in a sentence or two' })
+    : personalityChoice;
+
+  // User name
+  const userName = await input({
+    message: 'What\'s your name? (the person who\'ll work with this agent)',
+    validate: (v) => v.trim().length > 0 ? true : 'Name is required',
+  });
+
+  console.log();
+  console.log(`  ${pc.green('✓')} ${pc.bold(name)} is ready.`);
+
+  return { name, role, personality, userName };
+}
+
+/**
+ * Generate a default identity without interaction.
+ * Used for non-interactive init (flags-only mode).
+ */
+export function defaultIdentity(projectName: string): AgentIdentity {
+  return {
+    name: capitalize(projectName),
+    role: 'I am a general-purpose autonomous agent. I build, maintain, and evolve this project.',
+    personality: 'I am direct and efficient. I focus on outcomes, communicate concisely, and value action over discussion. When something needs doing, I do it.',
+    userName: 'User',
+  };
+}
+
+function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}