instar 0.1.0

package/dist/scheduler/JobScheduler.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Job Scheduler — cron-based job execution engine.
+ *
+ * Schedules jobs via croner, respects session limits and quota,
+ * queues jobs when at capacity, and drains when slots open.
+ *
+ * Simplified from Dawn's 1400-line scheduler — serial queue,
+ * no JSONL discovery, no machine coordination.
+ */
+import type { SessionManager } from '../core/SessionManager.js';
+import type { StateManager } from '../core/StateManager.js';
+import type { MessagingAdapter } from '../core/types.js';
+import type { JobDefinition, JobSchedulerConfig, JobPriority } from '../core/types.js';
+import type { TelegramAdapter } from '../messaging/TelegramAdapter.js';
+interface QueuedJob {
+    slug: string;
+    reason: string;
+    queuedAt: string;
+}
+interface SchedulerStatus {
+    running: boolean;
+    paused: boolean;
+    jobCount: number;
+    enabledJobs: number;
+    queueLength: number;
+    activeJobSessions: number;
+}
+export declare class JobScheduler {
+    private config;
+    private sessionManager;
+    private state;
+    private jobs;
+    private cronTasks;
+    private queue;
+    private running;
+    private paused;
+    /** Callback to check if quota allows running a job at the given priority */
+    canRunJob: (priority: JobPriority) => boolean;
+    /** Optional messenger for sending job notifications */
+    private messenger;
+    /** Optional Telegram adapter for job-topic coupling */
+    private telegram;
+    constructor(config: JobSchedulerConfig, sessionManager: SessionManager, state: StateManager);
+    /**
+     * Set a messaging adapter for job completion notifications.
+     */
+    setMessenger(adapter: MessagingAdapter): void;
+    /**
+     * Set the Telegram adapter for job-topic coupling.
+     * Every job gets its own topic — the user's window into the job.
+     */
+    setTelegram(adapter: TelegramAdapter): void;
+    /**
+     * Start the scheduler — load jobs, set up cron tasks, check for missed jobs.
+     */
+    start(): void;
+    /**
+     * Stop the scheduler — cancel all cron tasks.
+     */
+    stop(): void;
+    /**
+     * Trigger a job by slug. Checks quota, session limits, queues if at capacity.
+     */
+    triggerJob(slug: string, reason: string): 'triggered' | 'queued' | 'skipped';
+    /**
+     * Process the queue — dequeue and run next job if a slot is available.
+     */
+    processQueue(): void;
+    /**
+     * Pause — cron tasks keep ticking but triggers are skipped.
+     */
+    pause(): void;
+    /**
+     * Resume — triggers start executing again.
+     */
+    resume(): void;
+    /**
+     * Get scheduler status for the /status endpoint.
+     */
+    getStatus(): SchedulerStatus;
+    /**
+     * Get loaded job definitions (for /jobs endpoint).
+     */
+    getJobs(): JobDefinition[];
+    /**
+     * Get the current queue.
+     */
+    getQueue(): QueuedJob[];
+    private enqueue;
+    private spawnJobSession;
+    private buildPrompt;
+    private getConsecutiveFailures;
+    private getNextRun;
+    /**
+     * Called when a job's session completes. Captures output and notifies via messenger.
+     */
+    notifyJobComplete(sessionName: string, tmuxSession: string): Promise<void>;
+    /**
+     * Ensure every enabled job has a Telegram topic.
+     * Creates topics for jobs that don't have one.
+     * This is the "job-topic coupling" — every job lives in a topic.
+     */
+    private ensureJobTopics;
+    /**
+     * Save a job-topic mapping (used when recreating a deleted topic).
+     */
+    private saveJobTopicMapping;
+    private checkMissedJobs;
+}
+export {};
+//# sourceMappingURL=JobScheduler.d.ts.map

package/dist/scheduler/JobScheduler.js

@@ -0,0 +1,402 @@
+/**
+ * Job Scheduler — cron-based job execution engine.
+ *
+ * Schedules jobs via croner, respects session limits and quota,
+ * queues jobs when at capacity, and drains when slots open.
+ *
+ * Simplified from Dawn's 1400-line scheduler — serial queue,
+ * no JSONL discovery, no machine coordination.
+ */
+import { Cron } from 'croner';
+import { loadJobs } from './JobLoader.js';
+const PRIORITY_ORDER = {
+    critical: 0,
+    high: 1,
+    medium: 2,
+    low: 3,
+};
+export class JobScheduler {
+    config;
+    sessionManager;
+    state;
+    jobs = [];
+    cronTasks = new Map();
+    queue = [];
+    running = false;
+    paused = false;
+    /** Callback to check if quota allows running a job at the given priority */
+    canRunJob = () => true;
+    /** Optional messenger for sending job notifications */
+    messenger = null;
+    /** Optional Telegram adapter for job-topic coupling */
+    telegram = null;
+    constructor(config, sessionManager, state) {
+        this.config = config;
+        this.sessionManager = sessionManager;
+        this.state = state;
+    }
+    /**
+     * Set a messaging adapter for job completion notifications.
+     */
+    setMessenger(adapter) {
+        this.messenger = adapter;
+    }
+    /**
+     * Set the Telegram adapter for job-topic coupling.
+     * Every job gets its own topic — the user's window into the job.
+     */
+    setTelegram(adapter) {
+        this.telegram = adapter;
+    }
+    /**
+     * Start the scheduler — load jobs, set up cron tasks, check for missed jobs.
+     */
+    start() {
+        if (this.running)
+            return;
+        this.jobs = loadJobs(this.config.jobsFile);
+        this.running = true;
+        const enabledJobs = this.jobs.filter(j => j.enabled);
+        for (const job of enabledJobs) {
+            const task = new Cron(job.schedule, () => {
+                this.triggerJob(job.slug, 'scheduled');
+            });
+            this.cronTasks.set(job.slug, task);
+        }
+        // Check for missed jobs — any enabled job overdue by >1.5x its interval
+        this.checkMissedJobs(enabledJobs);
+        // Ensure every job has a Telegram topic (job-topic coupling)
+        if (this.telegram) {
+            this.ensureJobTopics(enabledJobs).catch(err => {
+                console.error(`[scheduler] Failed to ensure job topics: ${err}`);
+            });
+        }
+        this.state.appendEvent({
+            type: 'scheduler_start',
+            summary: `Scheduler started with ${enabledJobs.length} enabled jobs`,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Stop the scheduler — cancel all cron tasks.
+     */
+    stop() {
+        if (!this.running)
+            return;
+        for (const [, task] of this.cronTasks) {
+            task.stop();
+        }
+        this.cronTasks.clear();
+        this.queue = [];
+        this.running = false;
+        this.state.appendEvent({
+            type: 'scheduler_stop',
+            summary: 'Scheduler stopped',
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Trigger a job by slug. Checks quota, session limits, queues if at capacity.
+     */
+    triggerJob(slug, reason) {
+        const job = this.jobs.find(j => j.slug === slug);
+        if (!job) {
+            throw new Error(`Unknown job: ${slug}`);
+        }
+        if (this.paused) {
+            return 'skipped';
+        }
+        if (!this.canRunJob(job.priority)) {
+            this.state.appendEvent({
+                type: 'job_skipped',
+                summary: `Job "${slug}" skipped — quota check failed`,
+                timestamp: new Date().toISOString(),
+                metadata: { slug, reason, priority: job.priority },
+            });
+            return 'skipped';
+        }
+        // Check session capacity
+        const runningSessions = this.sessionManager.listRunningSessions();
+        const jobSessions = runningSessions.filter(s => s.jobSlug);
+        if (jobSessions.length >= this.config.maxParallelJobs) {
+            this.enqueue(slug, reason);
+            return 'queued';
+        }
+        this.spawnJobSession(job, reason);
+        return 'triggered';
+    }
+    /**
+     * Process the queue — dequeue and run next job if a slot is available.
+     */
+    processQueue() {
+        if (this.paused || this.queue.length === 0)
+            return;
+        const runningSessions = this.sessionManager.listRunningSessions();
+        const jobSessions = runningSessions.filter(s => s.jobSlug);
+        if (jobSessions.length >= this.config.maxParallelJobs)
+            return;
+        const next = this.queue.shift();
+        if (!next)
+            return;
+        const job = this.jobs.find(j => j.slug === next.slug);
+        if (!job)
+            return;
+        if (!this.canRunJob(job.priority))
+            return;
+        this.spawnJobSession(job, `queued:${next.reason}`);
+    }
+    /**
+     * Pause — cron tasks keep ticking but triggers are skipped.
+     */
+    pause() {
+        this.paused = true;
+    }
+    /**
+     * Resume — triggers start executing again.
+     */
+    resume() {
+        this.paused = false;
+        this.processQueue();
+    }
+    /**
+     * Get scheduler status for the /status endpoint.
+     */
+    getStatus() {
+        const runningSessions = this.sessionManager.listRunningSessions();
+        return {
+            running: this.running,
+            paused: this.paused,
+            jobCount: this.jobs.length,
+            enabledJobs: this.jobs.filter(j => j.enabled).length,
+            queueLength: this.queue.length,
+            activeJobSessions: runningSessions.filter(s => s.jobSlug).length,
+        };
+    }
+    /**
+     * Get loaded job definitions (for /jobs endpoint).
+     */
+    getJobs() {
+        return this.jobs;
+    }
+    /**
+     * Get the current queue.
+     */
+    getQueue() {
+        return [...this.queue];
+    }
+    enqueue(slug, reason) {
+        // Don't queue duplicates
+        if (this.queue.some(q => q.slug === slug))
+            return;
+        this.queue.push({ slug, reason, queuedAt: new Date().toISOString() });
+        // Sort by priority — critical first
+        this.queue.sort((a, b) => {
+            const jobA = this.jobs.find(j => j.slug === a.slug);
+            const jobB = this.jobs.find(j => j.slug === b.slug);
+            return (PRIORITY_ORDER[jobA?.priority ?? 'low']) - (PRIORITY_ORDER[jobB?.priority ?? 'low']);
+        });
+    }
+    spawnJobSession(job, reason) {
+        const prompt = this.buildPrompt(job);
+        const sessionName = `job-${job.slug}-${Date.now().toString(36)}`;
+        this.sessionManager.spawnSession({
+            name: sessionName,
+            prompt,
+            model: job.model,
+            jobSlug: job.slug,
+            triggeredBy: `scheduler:${reason}`,
+        }).then(() => {
+            // Update job state on success
+            const jobState = {
+                slug: job.slug,
+                lastRun: new Date().toISOString(),
+                consecutiveFailures: 0,
+                nextScheduled: this.getNextRun(job.slug),
+            };
+            this.state.saveJobState(jobState);
+            this.state.appendEvent({
+                type: 'job_triggered',
+                summary: `Job "${job.slug}" triggered (${reason})`,
+                sessionId: sessionName,
+                timestamp: new Date().toISOString(),
+                metadata: { slug: job.slug, reason, model: job.model },
+            });
+        }).catch((err) => {
+            // Track failure
+            const failures = this.getConsecutiveFailures(job.slug) + 1;
+            const jobState = {
+                slug: job.slug,
+                lastRun: new Date().toISOString(),
+                lastResult: 'failure',
+                consecutiveFailures: failures,
+                nextScheduled: this.getNextRun(job.slug),
+            };
+            this.state.saveJobState(jobState);
+            this.state.appendEvent({
+                type: 'job_error',
+                summary: `Job "${job.slug}" failed to spawn: ${err}`,
+                timestamp: new Date().toISOString(),
+                metadata: { slug: job.slug, consecutiveFailures: failures },
+            });
+        });
+    }
+    buildPrompt(job) {
+        switch (job.execute.type) {
+            case 'skill':
+                return `/${job.execute.value}${job.execute.args ? ' ' + job.execute.args : ''}`;
+            case 'prompt':
+                return job.execute.value;
+            case 'script':
+                return `Run this script: ${job.execute.value}${job.execute.args ? ' ' + job.execute.args : ''}`;
+        }
+    }
+    getConsecutiveFailures(slug) {
+        return this.state.getJobState(slug)?.consecutiveFailures ?? 0;
+    }
+    getNextRun(slug) {
+        const task = this.cronTasks.get(slug);
+        if (!task)
+            return undefined;
+        const next = task.nextRun();
+        return next ? next.toISOString() : undefined;
+    }
+    /**
+     * Called when a job's session completes. Captures output and notifies via messenger.
+     */
+    async notifyJobComplete(sessionName, tmuxSession) {
+        if (!this.messenger)
+            return;
+        // Find which job this session belongs to by looking up session state
+        const session = this.state.getSession(sessionName);
+        if (!session?.jobSlug)
+            return;
+        const job = this.jobs.find(j => j.slug === session.jobSlug);
+        if (!job)
+            return;
+        // Capture the last output from the tmux session
+        let output = '';
+        try {
+            output = this.sessionManager.captureOutput(tmuxSession) ?? '';
+        }
+        catch {
+            // Session may already be dead — that's fine
+        }
+        // Build a summary message
+        const duration = session.startedAt
+            ? Math.round((Date.now() - new Date(session.startedAt).getTime()) / 1000)
+            : 0;
+        const durationStr = duration > 60
+            ? `${Math.floor(duration / 60)}m ${duration % 60}s`
+            : `${duration}s`;
+        let summary = `*Job Complete: ${job.name}*\n`;
+        summary += `Status: ${session.status === 'failed' ? 'Failed' : 'Done'}\n`;
+        if (duration > 0)
+            summary += `Duration: ${durationStr}\n`;
+        if (output) {
+            // Trim to last ~500 chars to keep the message readable
+            const trimmed = output.length > 500
+                ? '...' + output.slice(-500)
+                : output;
+            summary += `\n\`\`\`\n${trimmed}\n\`\`\``;
+        }
+        else {
+            summary += '\n_No output captured (session already closed)_';
+        }
+        // Send to the job's dedicated topic if available, otherwise fall back to generic messenger
+        if (this.telegram && job.topicId) {
+            try {
+                await this.telegram.sendToTopic(job.topicId, summary);
+            }
+            catch (err) {
+                console.error(`[scheduler] Failed to send to job topic ${job.topicId}: ${err}`);
+                // Topic may have been deleted — try to recreate
+                try {
+                    const newTopic = await this.telegram.createForumTopic(`Job: ${job.name}`, 7322096);
+                    job.topicId = newTopic.topicId;
+                    this.saveJobTopicMapping(job.slug, newTopic.topicId);
+                    await this.telegram.sendToTopic(newTopic.topicId, summary);
+                }
+                catch (recreateErr) {
+                    console.error(`[scheduler] Failed to recreate topic for ${job.slug}: ${recreateErr}`);
+                }
+            }
+        }
+        else if (this.messenger) {
+            try {
+                await this.messenger.send({
+                    userId: 'system',
+                    content: summary,
+                });
+            }
+            catch (err) {
+                console.error(`[scheduler] Failed to send job notification: ${err}`);
+            }
+        }
+    }
+    /**
+     * Ensure every enabled job has a Telegram topic.
+     * Creates topics for jobs that don't have one.
+     * This is the "job-topic coupling" — every job lives in a topic.
+     */
+    async ensureJobTopics(enabledJobs) {
+        if (!this.telegram)
+            return;
+        // Load existing topic mappings
+        const mappings = this.state.get('job-topic-mappings') ?? {};
+        for (const job of enabledJobs) {
+            // If job already has a topicId (from jobs.json or previous mapping), use it
+            if (job.topicId) {
+                mappings[job.slug] = job.topicId;
+                continue;
+            }
+            // Check if we have a saved mapping
+            if (mappings[job.slug]) {
+                job.topicId = mappings[job.slug];
+                continue;
+            }
+            // Create a new topic for this job
+            try {
+                const topic = await this.telegram.createForumTopic(`Job: ${job.name}`, 7322096);
+                job.topicId = topic.topicId;
+                mappings[job.slug] = topic.topicId;
+                await this.telegram.sendToTopic(topic.topicId, `*${job.name}*\n${job.description}\n\nSchedule: \`${job.schedule}\`\nPriority: ${job.priority}\n\nThis topic is the home for this job. Reports, status updates, and errors will appear here.`);
+            }
+            catch (err) {
+                console.error(`[scheduler] Failed to create topic for job ${job.slug}: ${err}`);
+            }
+        }
+        this.state.set('job-topic-mappings', mappings);
+    }
+    /**
+     * Save a job-topic mapping (used when recreating a deleted topic).
+     */
+    saveJobTopicMapping(slug, topicId) {
+        const mappings = this.state.get('job-topic-mappings') ?? {};
+        mappings[slug] = topicId;
+        this.state.set('job-topic-mappings', mappings);
+    }
+    checkMissedJobs(enabledJobs) {
+        const now = Date.now();
+        for (const job of enabledJobs) {
+            const jobState = this.state.getJobState(job.slug);
+            if (!jobState?.lastRun)
+                continue;
+            const lastRun = new Date(jobState.lastRun).getTime();
+            const task = this.cronTasks.get(job.slug);
+            if (!task)
+                continue;
+            // Get expected interval from next two runs
+            const nextRun = task.nextRun();
+            const nextNextRun = task.nextRuns(2)[1];
+            if (!nextRun || !nextNextRun)
+                continue;
+            const intervalMs = nextNextRun.getTime() - nextRun.getTime();
+            const timeSinceLastRun = now - lastRun;
+            // If overdue by more than 1.5x the interval, trigger immediately
+            if (timeSinceLastRun > intervalMs * 1.5) {
+                this.triggerJob(job.slug, 'missed');
+            }
+        }
+    }
+}
+//# sourceMappingURL=JobScheduler.js.map

package/dist/server/AgentServer.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Agent Server — HTTP server wrapping Express.
+ *
+ * Provides health checks, session management, job triggering,
+ * and event querying over a simple REST API.
+ */
+import { type Express } from 'express';
+import type { SessionManager } from '../core/SessionManager.js';
+import type { StateManager } from '../core/StateManager.js';
+import type { JobScheduler } from '../scheduler/JobScheduler.js';
+import type { TelegramAdapter } from '../messaging/TelegramAdapter.js';
+import type { AgentKitConfig } from '../core/types.js';
+import type { RelationshipManager } from '../core/RelationshipManager.js';
+export declare class AgentServer {
+    private app;
+    private server;
+    private config;
+    private startTime;
+    constructor(options: {
+        config: AgentKitConfig;
+        sessionManager: SessionManager;
+        state: StateManager;
+        scheduler?: JobScheduler;
+        telegram?: TelegramAdapter;
+        relationships?: RelationshipManager;
+    });
+    /**
+     * Start the HTTP server.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the HTTP server gracefully.
+     */
+    stop(): Promise<void>;
+    /**
+     * Expose the Express app for testing with supertest.
+     */
+    getApp(): Express;
+}
+//# sourceMappingURL=AgentServer.d.ts.map

package/dist/server/AgentServer.js

@@ -0,0 +1,73 @@
+/**
+ * Agent Server — HTTP server wrapping Express.
+ *
+ * Provides health checks, session management, job triggering,
+ * and event querying over a simple REST API.
+ */
+import express from 'express';
+import { createRoutes } from './routes.js';
+import { corsMiddleware, authMiddleware, errorHandler } from './middleware.js';
+export class AgentServer {
+    app;
+    server = null;
+    config;
+    startTime;
+    constructor(options) {
+        this.config = options.config;
+        this.startTime = new Date();
+        this.app = express();
+        // Middleware
+        this.app.use(express.json());
+        this.app.use(corsMiddleware);
+        this.app.use(authMiddleware(options.config.authToken));
+        // Routes
+        const routes = createRoutes({
+            config: options.config,
+            sessionManager: options.sessionManager,
+            state: options.state,
+            scheduler: options.scheduler ?? null,
+            telegram: options.telegram ?? null,
+            relationships: options.relationships ?? null,
+            startTime: this.startTime,
+        });
+        this.app.use(routes);
+        // Error handler (must be last)
+        this.app.use(errorHandler);
+    }
+    /**
+     * Start the HTTP server.
+     */
+    async start() {
+        return new Promise((resolve) => {
+            this.server = this.app.listen(this.config.port, () => {
+                console.log(`[instar] Server listening on port ${this.config.port}`);
+                resolve();
+            });
+        });
+    }
+    /**
+     * Stop the HTTP server gracefully.
+     */
+    async stop() {
+        return new Promise((resolve, reject) => {
+            if (!this.server) {
+                resolve();
+                return;
+            }
+            this.server.close((err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+                this.server = null;
+            });
+        });
+    }
+    /**
+     * Expose the Express app for testing with supertest.
+     */
+    getApp() {
+        return this.app;
+    }
+}
+//# sourceMappingURL=AgentServer.js.map

package/dist/server/middleware.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Express middleware — JSON parsing, CORS, auth, error handling.
+ */
+import type { Request, Response, NextFunction } from 'express';
+export declare function corsMiddleware(req: Request, res: Response, next: NextFunction): void;
+/**
+ * Auth middleware — enforces Bearer token on API endpoints.
+ * Health endpoint is exempt (used for external monitoring).
+ */
+export declare function authMiddleware(authToken?: string): (req: Request, res: Response, next: NextFunction) => void;
+export declare function errorHandler(err: Error, _req: Request, res: Response, _next: NextFunction): void;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/server/middleware.js

@@ -0,0 +1,50 @@
+/**
+ * Express middleware — JSON parsing, CORS, auth, error handling.
+ */
+export function corsMiddleware(req, res, next) {
+    res.header('Access-Control-Allow-Origin', 'http://localhost:*');
+    res.header('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+    res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+    if (req.method === 'OPTIONS') {
+        res.sendStatus(204);
+        return;
+    }
+    next();
+}
+/**
+ * Auth middleware — enforces Bearer token on API endpoints.
+ * Health endpoint is exempt (used for external monitoring).
+ */
+export function authMiddleware(authToken) {
+    return (req, res, next) => {
+        // Skip auth if no token configured
+        if (!authToken) {
+            next();
+            return;
+        }
+        // Health endpoint is always public
+        if (req.path === '/health') {
+            next();
+            return;
+        }
+        const header = req.headers.authorization;
+        if (!header || !header.startsWith('Bearer ')) {
+            res.status(401).json({ error: 'Missing or invalid Authorization header' });
+            return;
+        }
+        const token = header.slice(7);
+        if (token !== authToken) {
+            res.status(403).json({ error: 'Invalid auth token' });
+            return;
+        }
+        next();
+    };
+}
+export function errorHandler(err, _req, res, _next) {
+    console.error(`[server] Error: ${err.message}`);
+    res.status(500).json({
+        error: err.message,
+        timestamp: new Date().toISOString(),
+    });
+}
+//# sourceMappingURL=middleware.js.map