instar 0.1.0

package/dist/core/types.d.ts

@@ -0,0 +1,279 @@
+/**
+ * Core type definitions for instar.
+ *
+ * These types define the contracts between all modules.
+ * Everything flows from these — sessions, jobs, users, messaging.
+ */
+export interface Session {
+    id: string;
+    name: string;
+    status: SessionStatus;
+    /** The job that spawned this session, if any */
+    jobSlug?: string;
+    /** tmux session name */
+    tmuxSession: string;
+    /** When the session was created */
+    startedAt: string;
+    /** When the session ended (if completed) */
+    endedAt?: string;
+    /** User who triggered the session, if any */
+    triggeredBy?: string;
+    /** Model to use for this session */
+    model?: ModelTier;
+    /** The initial prompt/instruction sent to Claude */
+    prompt?: string;
+}
+export type SessionStatus = 'starting' | 'running' | 'completed' | 'failed' | 'killed';
+export type ModelTier = 'opus' | 'sonnet' | 'haiku';
+export interface SessionManagerConfig {
+    /** Path to tmux binary */
+    tmuxPath: string;
+    /** Path to claude CLI binary */
+    claudePath: string;
+    /** Project directory (where CLAUDE.md lives) */
+    projectDir: string;
+    /** Maximum concurrent sessions */
+    maxSessions: number;
+    /** Protected session names that should never be reaped */
+    protectedSessions: string[];
+    /** Patterns in tmux output that indicate session completion */
+    completionPatterns: string[];
+}
+export interface JobDefinition {
+    slug: string;
+    name: string;
+    description: string;
+    /** Cron expression (e.g., "0 0/4 * * *" for every 4 hours) */
+    schedule: string;
+    /** Priority level — higher priority jobs run first and survive quota pressure */
+    priority: JobPriority;
+    /** Expected duration in minutes (for scheduling decisions) */
+    expectedDurationMinutes: number;
+    /** Model tier to use */
+    model: ModelTier;
+    /** Whether this job is currently enabled */
+    enabled: boolean;
+    /** The skill or prompt to execute */
+    execute: JobExecution;
+    /** Tags for filtering/grouping */
+    tags?: string[];
+    /** Telegram topic ID this job reports to (auto-created if not set) */
+    topicId?: number;
+}
+export type JobPriority = 'critical' | 'high' | 'medium' | 'low';
+export interface JobExecution {
+    /** Type of execution */
+    type: 'skill' | 'prompt' | 'script';
+    /** The skill name, prompt text, or script path */
+    value: string;
+    /** Additional arguments */
+    args?: string;
+}
+export interface JobState {
+    slug: string;
+    lastRun?: string;
+    lastResult?: 'success' | 'failure' | 'timeout';
+    nextScheduled?: string;
+    consecutiveFailures: number;
+}
+export interface JobSchedulerConfig {
+    /** Path to jobs definition file */
+    jobsFile: string;
+    /** Whether the scheduler is active */
+    enabled: boolean;
+    /** Maximum parallel job sessions */
+    maxParallelJobs: number;
+    /** Quota thresholds for load shedding */
+    quotaThresholds: {
+        /** Below this: all jobs run */
+        normal: number;
+        /** Above this: only high+ priority */
+        elevated: number;
+        /** Above this: only critical */
+        critical: number;
+        /** Above this: no jobs */
+        shutdown: number;
+    };
+}
+export interface UserProfile {
+    id: string;
+    name: string;
+    /** Communication channels this user is reachable on */
+    channels: UserChannel[];
+    /** What this user is allowed to do */
+    permissions: string[];
+    /** How the agent should interact with this user */
+    preferences: UserPreferences;
+    /** Interaction history summary */
+    context?: string;
+}
+export interface UserChannel {
+    /** Channel type (telegram, slack, discord, email, etc.) */
+    type: string;
+    /** Channel-specific identifier (topic ID, Slack user ID, email address, etc.) */
+    identifier: string;
+}
+export interface UserPreferences {
+    /** Communication style (e.g., "technical and direct", "prefers explanations") */
+    style?: string;
+    /** Whether to auto-execute or confirm with this user */
+    autonomyLevel?: 'full' | 'confirm-destructive' | 'confirm-all';
+    /** Timezone for scheduling */
+    timezone?: string;
+}
+export interface Message {
+    /** Unique message ID */
+    id: string;
+    /** User who sent the message */
+    userId: string;
+    /** The message content */
+    content: string;
+    /** Channel the message came from */
+    channel: UserChannel;
+    /** When the message was received */
+    receivedAt: string;
+    /** Message metadata (platform-specific) */
+    metadata?: Record<string, unknown>;
+}
+export interface OutgoingMessage {
+    /** User to send to */
+    userId: string;
+    /** Message content */
+    content: string;
+    /** Specific channel to use (optional — uses default if omitted) */
+    channel?: UserChannel;
+}
+/**
+ * Messaging adapter interface.
+ * Implement this for each platform (Telegram, Slack, Discord, etc.)
+ */
+export interface MessagingAdapter {
+    /** Platform name (e.g., "telegram", "slack") */
+    platform: string;
+    /** Start listening for messages */
+    start(): Promise<void>;
+    /** Stop listening */
+    stop(): Promise<void>;
+    /** Send a message to a user */
+    send(message: OutgoingMessage): Promise<void>;
+    /** Register a handler for incoming messages */
+    onMessage(handler: (message: Message) => Promise<void>): void;
+    /** Resolve a platform-specific identifier to a user ID */
+    resolveUser(channelIdentifier: string): Promise<string | null>;
+}
+export interface QuotaState {
+    /** Current usage percentage (0-100) */
+    usagePercent: number;
+    /** When usage data was last updated */
+    lastUpdated: string;
+    /** Per-account breakdown if multi-account */
+    accounts?: AccountQuota[];
+    /** Recommended action based on usage */
+    recommendation?: 'normal' | 'reduce' | 'critical' | 'stop';
+}
+export interface AccountQuota {
+    email: string;
+    usagePercent: number;
+    isActive: boolean;
+    lastUpdated: string;
+}
+export interface HealthStatus {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    components: Record<string, ComponentHealth>;
+    timestamp: string;
+}
+export interface ComponentHealth {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    message?: string;
+    lastCheck: string;
+}
+export interface RelationshipRecord {
+    /** Unique identifier for this person */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Known identifiers across platforms */
+    channels: UserChannel[];
+    /** When the agent first interacted with this person */
+    firstInteraction: string;
+    /** When the agent last interacted with this person */
+    lastInteraction: string;
+    /** Total number of interactions */
+    interactionCount: number;
+    /** Key topics discussed across conversations */
+    themes: string[];
+    /** Agent's notes about this person — observations, preferences, context */
+    notes: string;
+    /** Communication style preferences the agent has observed */
+    communicationStyle?: string;
+    /** How significant this relationship is (0-10, auto-derived from frequency and depth) */
+    significance: number;
+    /** Brief summary of the relationship arc */
+    arcSummary?: string;
+    /** Per-interaction log (last N interactions, kept compact) */
+    recentInteractions: InteractionSummary[];
+}
+export interface InteractionSummary {
+    /** When this interaction happened */
+    timestamp: string;
+    /** Which platform/channel */
+    channel: string;
+    /** Brief summary of what was discussed */
+    summary: string;
+    /** Topics touched on */
+    topics?: string[];
+}
+export interface RelationshipManagerConfig {
+    /** Directory to store relationship files */
+    relationshipsDir: string;
+    /** Maximum recent interactions to keep per relationship */
+    maxRecentInteractions: number;
+}
+export interface ActivityEvent {
+    type: string;
+    summary: string;
+    /** Which session generated this event */
+    sessionId?: string;
+    /** Which user triggered this, if any */
+    userId?: string;
+    timestamp: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentKitConfig {
+    /** Project name (used in logging, tmux session names, etc.) */
+    projectName: string;
+    /** Project root directory */
+    projectDir: string;
+    /** Where instar stores its runtime state */
+    stateDir: string;
+    /** HTTP server port */
+    port: number;
+    /** Session manager config */
+    sessions: SessionManagerConfig;
+    /** Job scheduler config */
+    scheduler: JobSchedulerConfig;
+    /** Registered users */
+    users: UserProfile[];
+    /** Messaging adapters to enable */
+    messaging: MessagingAdapterConfig[];
+    /** Monitoring config */
+    monitoring: MonitoringConfig;
+    /** Auth token for API access (generated during setup) */
+    authToken?: string;
+    /** Relationship tracking config */
+    relationships: RelationshipManagerConfig;
+}
+export interface MessagingAdapterConfig {
+    type: string;
+    enabled: boolean;
+    config: Record<string, unknown>;
+}
+export interface MonitoringConfig {
+    /** Enable quota tracking */
+    quotaTracking: boolean;
+    /** Enable memory pressure monitoring */
+    memoryMonitoring: boolean;
+    /** Health check interval in ms */
+    healthCheckIntervalMs: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.js

@@ -0,0 +1,8 @@
+/**
+ * Core type definitions for instar.
+ *
+ * These types define the contracts between all modules.
+ * Everything flows from these — sessions, jobs, users, messaging.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * instar — Persistent autonomy infrastructure for AI agents.
+ *
+ * Public API for programmatic usage.
+ */
+export { SessionManager } from './core/SessionManager.js';
+export { StateManager } from './core/StateManager.js';
+export { RelationshipManager } from './core/RelationshipManager.js';
+export { loadConfig, detectTmuxPath, detectClaudePath, ensureStateDir } from './core/Config.js';
+export { UserManager } from './users/UserManager.js';
+export { JobScheduler } from './scheduler/JobScheduler.js';
+export { loadJobs, validateJob } from './scheduler/JobLoader.js';
+export { AgentServer } from './server/AgentServer.js';
+export { createRoutes } from './server/routes.js';
+export { HealthChecker } from './monitoring/HealthChecker.js';
+export { TelegramAdapter } from './messaging/TelegramAdapter.js';
+export type { Session, SessionStatus, SessionManagerConfig, ModelTier, JobDefinition, JobPriority, JobExecution, JobState, JobSchedulerConfig, UserProfile, UserChannel, UserPreferences, Message, OutgoingMessage, MessagingAdapter, MessagingAdapterConfig, QuotaState, AccountQuota, HealthStatus, ComponentHealth, ActivityEvent, AgentKitConfig, MonitoringConfig, RelationshipRecord, RelationshipManagerConfig, InteractionSummary, } from './core/types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * instar — Persistent autonomy infrastructure for AI agents.
+ *
+ * Public API for programmatic usage.
+ */
+// Core
+export { SessionManager } from './core/SessionManager.js';
+export { StateManager } from './core/StateManager.js';
+export { RelationshipManager } from './core/RelationshipManager.js';
+export { loadConfig, detectTmuxPath, detectClaudePath, ensureStateDir } from './core/Config.js';
+// Users
+export { UserManager } from './users/UserManager.js';
+// Scheduler
+export { JobScheduler } from './scheduler/JobScheduler.js';
+export { loadJobs, validateJob } from './scheduler/JobLoader.js';
+// Server
+export { AgentServer } from './server/AgentServer.js';
+export { createRoutes } from './server/routes.js';
+// Monitoring
+export { HealthChecker } from './monitoring/HealthChecker.js';
+// Messaging
+export { TelegramAdapter } from './messaging/TelegramAdapter.js';
+//# sourceMappingURL=index.js.map

package/dist/messaging/TelegramAdapter.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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 type { MessagingAdapter, Message, OutgoingMessage } 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 LogEntry {
+    messageId: number;
+    topicId: number | null;
+    text: string;
+    fromUser: boolean;
+    timestamp: string;
+    sessionName: string | null;
+}
+export declare class TelegramAdapter implements MessagingAdapter {
+    readonly platform = "telegram";
+    private config;
+    private handler;
+    private polling;
+    private pollTimeout;
+    private lastUpdateId;
+    private topicToSession;
+    private sessionToTopic;
+    private topicToName;
+    private registryPath;
+    private messageLogPath;
+    onTopicMessage: ((message: Message) => void) | null;
+    constructor(config: TelegramConfig, stateDir: string);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    send(message: OutgoingMessage): Promise<void>;
+    /**
+     * Send a message to a specific forum topic.
+     */
+    sendToTopic(topicId: number, text: string): Promise<void>;
+    /**
+     * Create a forum topic in the supergroup.
+     */
+    createForumTopic(name: string, iconColor?: number): Promise<{
+        topicId: number;
+        name: string;
+    }>;
+    onMessage(handler: (message: Message) => Promise<void>): void;
+    resolveUser(channelIdentifier: string): Promise<string | null>;
+    registerTopicSession(topicId: number, sessionName: string): void;
+    getSessionForTopic(topicId: number): string | null;
+    getTopicForSession(sessionName: string): number | null;
+    getTopicName(topicId: number): string | null;
+    /**
+     * Get recent messages for a topic (for thread history on respawn).
+     */
+    getTopicHistory(topicId: number, limit?: number): LogEntry[];
+    private appendToLog;
+    private loadRegistry;
+    private saveRegistry;
+    private poll;
+    private getUpdates;
+    private apiCall;
+}
+export {};
+//# sourceMappingURL=TelegramAdapter.d.ts.map

package/dist/messaging/TelegramAdapter.js

@@ -0,0 +1,288 @@
+/**
+ * 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';
+export class TelegramAdapter {
+    platform = 'telegram';
+    config;
+    handler = null;
+    polling = false;
+    pollTimeout = null;
+    lastUpdateId = 0;
+    // Topic-session registry (persisted to disk)
+    topicToSession = new Map();
+    sessionToTopic = new Map();
+    topicToName = new Map();
+    registryPath;
+    messageLogPath;
+    // Topic message callback — fires on every incoming topic message
+    onTopicMessage = null;
+    constructor(config, stateDir) {
+        this.config = config;
+        this.registryPath = path.join(stateDir, 'topic-session-registry.json');
+        this.messageLogPath = path.join(stateDir, 'telegram-messages.jsonl');
+        this.loadRegistry();
+    }
+    async start() {
+        if (this.polling)
+            return;
+        this.polling = true;
+        console.log(`[telegram] Starting long-polling...`);
+        this.poll();
+    }
+    async stop() {
+        this.polling = false;
+        if (this.pollTimeout) {
+            clearTimeout(this.pollTimeout);
+            this.pollTimeout = null;
+        }
+    }
+    async send(message) {
+        const topicId = message.channel?.identifier;
+        const params = {
+            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, text) {
+        const params = {
+            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, iconColor) {
+        const params = {
+            chat_id: this.config.chatId,
+            name,
+        };
+        if (iconColor !== undefined) {
+            params.icon_color = iconColor;
+        }
+        const result = await this.apiCall('createForumTopic', params);
+        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) {
+        this.handler = handler;
+    }
+    async resolveUser(channelIdentifier) {
+        return null;
+    }
+    // ── Topic-Session Registry ─────────────────────────────────
+    registerTopicSession(topicId, sessionName) {
+        this.topicToSession.set(topicId, sessionName);
+        this.sessionToTopic.set(sessionName, topicId);
+        this.saveRegistry();
+        console.log(`[telegram] Registered topic ${topicId} <-> session "${sessionName}"`);
+    }
+    getSessionForTopic(topicId) {
+        return this.topicToSession.get(topicId) ?? null;
+    }
+    getTopicForSession(sessionName) {
+        return this.sessionToTopic.get(sessionName) ?? null;
+    }
+    getTopicName(topicId) {
+        return this.topicToName.get(topicId) ?? null;
+    }
+    // ── Message Log ────────────────────────────────────────────
+    /**
+     * Get recent messages for a topic (for thread history on respawn).
+     */
+    getTopicHistory(topicId, limit = 20) {
+        if (!fs.existsSync(this.messageLogPath))
+            return [];
+        const lines = fs.readFileSync(this.messageLogPath, 'utf-8')
+            .split('\n')
+            .filter(Boolean);
+        const matching = [];
+        for (const line of lines) {
+            try {
+                const entry = JSON.parse(line);
+                if (entry.topicId === topicId) {
+                    matching.push(entry);
+                }
+            }
+            catch { /* skip malformed */ }
+        }
+        return matching.slice(-limit);
+    }
+    appendToLog(entry) {
+        try {
+            fs.appendFileSync(this.messageLogPath, JSON.stringify(entry) + '\n');
+        }
+        catch (err) {
+            console.error(`[telegram] Failed to append to message log: ${err}`);
+        }
+    }
+    // ── Registry Persistence ───────────────────────────────────
+    loadRegistry() {
+        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);
+                    this.sessionToTopic.set(v, Number(k));
+                }
+            }
+            if (data.topicToName) {
+                for (const [k, v] of Object.entries(data.topicToName)) {
+                    this.topicToName.set(Number(k), v);
+                }
+            }
+            console.log(`[telegram] Loaded ${this.topicToSession.size} topic-session mappings from disk`);
+        }
+        catch {
+            // File doesn't exist yet — start fresh
+        }
+    }
+    saveRegistry() {
+        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 ────────────────────────────────────────────────
+    async poll() {
+        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 = {
+                        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);
+    }
+    async getUpdates() {
+        const result = await this.apiCall('getUpdates', {
+            offset: this.lastUpdateId + 1,
+            timeout: 30,
+            allowed_updates: ['message'],
+        });
+        return result ?? [];
+    }
+    async apiCall(method, params) {
+        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();
+        if (!data.ok) {
+            throw new Error(`Telegram API returned not ok: ${JSON.stringify(data)}`);
+        }
+        return data.result;
+    }
+}
+//# sourceMappingURL=TelegramAdapter.js.map