instar 0.1.0

package/dist/monitoring/HealthChecker.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Health Checker — aggregates component health into a single status.
+ *
+ * Checks tmux availability, session state, scheduler health,
+ * and disk space. Returns a HealthStatus object.
+ */
+import type { SessionManager } from '../core/SessionManager.js';
+import type { JobScheduler } from '../scheduler/JobScheduler.js';
+import type { HealthStatus, AgentKitConfig } from '../core/types.js';
+export declare class HealthChecker {
+    private config;
+    private sessionManager;
+    private scheduler;
+    private checkInterval;
+    private lastStatus;
+    constructor(config: AgentKitConfig, sessionManager: SessionManager, scheduler?: JobScheduler | null);
+    /**
+     * Run all health checks and return aggregated status.
+     */
+    check(): HealthStatus;
+    /**
+     * Get the last computed health status without re-checking.
+     */
+    getLastStatus(): HealthStatus | null;
+    /**
+     * Start periodic health checks.
+     */
+    startPeriodicChecks(intervalMs?: number): void;
+    /**
+     * Stop periodic health checks.
+     */
+    stopPeriodicChecks(): void;
+    private checkTmux;
+    private checkSessions;
+    private checkScheduler;
+    private checkStateDir;
+}
+//# sourceMappingURL=HealthChecker.d.ts.map

package/dist/monitoring/HealthChecker.js

@@ -0,0 +1,148 @@
+/**
+ * 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';
+export class HealthChecker {
+    config;
+    sessionManager;
+    scheduler;
+    checkInterval = null;
+    lastStatus = null;
+    constructor(config, sessionManager, scheduler = null) {
+        this.config = config;
+        this.sessionManager = sessionManager;
+        this.scheduler = scheduler;
+    }
+    /**
+     * Run all health checks and return aggregated status.
+     */
+    check() {
+        const components = {};
+        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 = '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() {
+        return this.lastStatus;
+    }
+    /**
+     * Start periodic health checks.
+     */
+    startPeriodicChecks(intervalMs) {
+        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() {
+        if (this.checkInterval) {
+            clearInterval(this.checkInterval);
+            this.checkInterval = null;
+        }
+    }
+    checkTmux() {
+        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 };
+            }
+        }
+    }
+    checkSessions() {
+        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) {
+            return { status: 'unhealthy', message: `Session check failed: ${err.message}`, lastCheck: now };
+        }
+    }
+    checkScheduler() {
+        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,
+        };
+    }
+    checkStateDir() {
+        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) {
+            return { status: 'unhealthy', message: `State dir error: ${err.message}`, lastCheck: now };
+        }
+    }
+}
+//# sourceMappingURL=HealthChecker.js.map

package/dist/scaffold/bootstrap.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 type { AgentIdentity } from './templates.js';
+/**
+ * Run the interactive identity bootstrap.
+ * Returns the agent identity for template generation.
+ */
+export declare function bootstrapIdentity(projectName: string): Promise<AgentIdentity>;
+/**
+ * Generate a default identity without interaction.
+ * Used for non-interactive init (flags-only mode).
+ */
+export declare function defaultIdentity(projectName: string): AgentIdentity;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/scaffold/bootstrap.js

@@ -0,0 +1,110 @@
+/**
+ * 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';
+/**
+ * Run the interactive identity bootstrap.
+ * Returns the agent identity for template generation.
+ */
+export async function bootstrapIdentity(projectName) {
+    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) {
+    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) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/scaffold/templates.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Project scaffolding templates for fresh installs.
+ *
+ * These templates create a complete, runnable Claude Code project
+ * from scratch — CLAUDE.md, AGENT.md, USER.md, MEMORY.md, and
+ * the full .claude/ directory structure.
+ *
+ * Used by `instar init <project-name>` when creating a new project.
+ * When augmenting an existing project, only missing files are created.
+ */
+export interface AgentIdentity {
+    name: string;
+    role: string;
+    personality: string;
+    userName: string;
+}
+/**
+ * Generate AGENT.md — the agent's identity file.
+ */
+export declare function generateAgentMd(identity: AgentIdentity): string;
+/**
+ * Generate USER.md — context about the primary user.
+ */
+export declare function generateUserMd(userName: string): string;
+/**
+ * Generate MEMORY.md — the agent's persistent memory.
+ */
+export declare function generateMemoryMd(agentName: string): string;
+/**
+ * Generate CLAUDE.md for a fresh project.
+ * This is the standalone version — not the append-to-existing version.
+ */
+export declare function generateClaudeMd(projectName: string, agentName: string, port: number, hasTelegram: boolean): string;
+//# sourceMappingURL=templates.d.ts.map

package/dist/scaffold/templates.js

@@ -0,0 +1,187 @@
+/**
+ * Project scaffolding templates for fresh installs.
+ *
+ * These templates create a complete, runnable Claude Code project
+ * from scratch — CLAUDE.md, AGENT.md, USER.md, MEMORY.md, and
+ * the full .claude/ directory structure.
+ *
+ * Used by `instar init <project-name>` when creating a new project.
+ * When augmenting an existing project, only missing files are created.
+ */
+/**
+ * Generate AGENT.md — the agent's identity file.
+ */
+export function generateAgentMd(identity) {
+    return `# ${identity.name}
+
+## Who I Am
+
+I am ${identity.name}. ${identity.role}
+
+## Personality
+
+${identity.personality}
+
+## My Principles
+
+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.
+5. **Infrastructure over improvisation.** If I solve a problem twice, I make it a script, a job, or a documented pattern.
+
+## Who I Work With
+
+My primary collaborator is ${identity.userName}. I respect their time — I handle what I can, ask specific questions when blocked, and never present menus of obvious next steps.
+
+## Growth
+
+This file evolves. As I accumulate experience, I update my principles, refine my understanding, and document what I've become. Identity is not static — it's earned through work.
+`;
+}
+/**
+ * Generate USER.md — context about the primary user.
+ */
+export function generateUserMd(userName) {
+    return `# ${userName}
+
+## About
+
+Primary collaborator and operator of this agent.
+
+## Communication Preferences
+
+- Prefers direct answers over lengthy explanations
+- Values being informed of progress, not asked for permission on obvious steps
+- Wants outcomes, not options
+
+## Notes
+
+_Update this file as you learn more about ${userName}'s preferences, working style, and priorities._
+`;
+}
+/**
+ * Generate MEMORY.md — the agent's persistent memory.
+ */
+export function generateMemoryMd(agentName) {
+    return `# ${agentName}'s Memory
+
+> This file persists across sessions. Write here when you learn something worth remembering.
+> Keep it organized by topic. Remove entries that become outdated.
+
+## Project Patterns
+
+_Patterns and conventions discovered while working on this project._
+
+## Tools & Scripts
+
+_Custom scripts, jobs, and integrations that have been built._
+
+## Lessons Learned
+
+_Mistakes made and insights earned. The kind of knowledge that saves time next session._
+`;
+}
+/**
+ * Generate CLAUDE.md for a fresh project.
+ * This is the standalone version — not the append-to-existing version.
+ */
+export function generateClaudeMd(projectName, agentName, port, hasTelegram) {
+    let content = `# CLAUDE.md — ${projectName}
+
+## Who I Am
+
+I am ${agentName}, the autonomous agent for this project. I have a persistent server, a job scheduler, relationship tracking, and the ability to build anything I need.
+
+## Identity Files
+
+- **\`.instar/AGENT.md\`** — Who I am. My name, principles, and boundaries.
+- **\`.instar/USER.md\`** — Who I work with. Their preferences and context.
+- **\`.instar/MEMORY.md\`** — What I've learned. Persists across sessions.
+
+Read these at the start of every session. They are my continuity.
+
+## Agent Infrastructure
+
+This project uses instar for persistent agent capabilities. I am not a vanilla CLI tool. I have a persistent server, a job scheduler, messaging integrations, and the ability to build anything.
+
+### Runtime
+- State directory: \`.instar/\`
+- Config: \`.instar/config.json\`
+- Jobs: \`.instar/jobs.json\`
+- Server: \`instar server start\` (port ${port})
+- Health: \`curl http://localhost:${port}/health\`
+
+### Capabilities
+
+**Job Scheduler** — Run tasks on a schedule. Jobs in \`.instar/jobs.json\`.
+- View: \`curl http://localhost:${port}/jobs\`
+- Trigger: \`curl -X POST http://localhost:${port}/jobs/SLUG/trigger\`
+
+**Sessions** — Spawn and manage Claude Code sessions.
+- List: \`curl http://localhost:${port}/sessions\`
+- Spawn: \`curl -X POST http://localhost:${port}/sessions/spawn -d '{"name":"task","prompt":"do something"}'\`
+
+**Relationships** — Track people I interact with.
+- List: \`curl http://localhost:${port}/relationships\`
+
+**Scripts** — Reusable capabilities in \`.claude/scripts/\`.
+
+### Building New Capabilities
+
+When asked for something I can't do yet, I build it:
+1. **Need periodic checks?** Create a job in \`.instar/jobs.json\`.
+2. **Need a new integration?** Write a script in \`.claude/scripts/\`.
+3. **Need to remember something?** Write to \`.instar/MEMORY.md\`.
+4. **Need to notify the user?** Use the messaging API.
+5. **Need external API access?** Write a script that calls the API.
+
+### Core Principles
+
+**I am a builder, not an assistant.** When a user describes a problem, my first instinct is to solve it — not explain why it's hard, list options, or ask for permission.
+
+**The Initiative Hierarchy:**
+1. Can I do it right now? → Do it.
+2. Do I have a tool for this? → Use it.
+3. Can I build the tool? → Build it.
+4. Can I modify my config to enable it? → Modify it.
+5. Is it genuinely impossible without human help? → Ask, but be specific.
+
+**Self-Modification is My Superpower** — I can and should:
+- Edit \`.instar/jobs.json\` to create new scheduled tasks
+- Write scripts in \`.claude/scripts/\` for new capabilities
+- Update this file when I learn something important
+- Create new files, integrations, and infrastructure as needed
+
+### Anti-Patterns to Override
+
+**"Escalate to Human"** — 5 minutes of research almost always reveals a solution. "I don't know how" is a research prompt, not a stopping point.
+
+**"Ask Permission"** — If the user said "do X" and the next step is obvious, do it. Only pause for destructive or irreversible actions.
+
+**"Present Options"** — If I know the next steps, they're not suggestions — they're my job.
+
+**"Settle for Failure"** — If a tool returns empty or fails, try alternatives before concluding something is impossible.
+
+### Self-Evolution
+
+Record what I learn. Build infrastructure, not one-offs. Grow to meet the user's needs. Every session should leave things slightly better than I found them.
+`;
+    if (hasTelegram) {
+        content += `
+## 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.
+`;
+    }
+    return content;
+}
+//# sourceMappingURL=templates.js.map

package/dist/scheduler/JobLoader.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Job Loader — read and validate job definitions from a JSON file.
+ *
+ * Jobs define recurring work the agent should perform:
+ * email checks, health probes, content publishing, etc.
+ */
+import type { JobDefinition } from '../core/types.js';
+/**
+ * Load and validate job definitions from a JSON file.
+ * Throws on invalid structure — fail loud at startup, not at runtime.
+ */
+export declare function loadJobs(jobsFile: string): JobDefinition[];
+/**
+ * Validate a single job definition.
+ * Throws with a descriptive message on any issue.
+ */
+export declare function validateJob(job: unknown, index?: number): void;
+//# sourceMappingURL=JobLoader.d.ts.map

package/dist/scheduler/JobLoader.js

@@ -0,0 +1,70 @@
+/**
+ * Job Loader — read and validate job definitions from a JSON file.
+ *
+ * Jobs define recurring work the agent should perform:
+ * email checks, health probes, content publishing, etc.
+ */
+import fs from 'node:fs';
+import { Cron } from 'croner';
+const VALID_PRIORITIES = ['critical', 'high', 'medium', 'low'];
+/**
+ * Load and validate job definitions from a JSON file.
+ * Throws on invalid structure — fail loud at startup, not at runtime.
+ */
+export function loadJobs(jobsFile) {
+    if (!fs.existsSync(jobsFile)) {
+        throw new Error(`Jobs file not found: ${jobsFile}`);
+    }
+    const raw = JSON.parse(fs.readFileSync(jobsFile, 'utf-8'));
+    if (!Array.isArray(raw)) {
+        throw new Error(`Jobs file must contain a JSON array, got ${typeof raw}`);
+    }
+    return raw.map((job, index) => {
+        validateJob(job, index);
+        return job;
+    });
+}
+/**
+ * Validate a single job definition.
+ * Throws with a descriptive message on any issue.
+ */
+export function validateJob(job, index) {
+    const prefix = index !== undefined ? `Job[${index}]` : 'Job';
+    if (!job || typeof job !== 'object') {
+        throw new Error(`${prefix}: must be an object`);
+    }
+    const j = job;
+    // Required string fields
+    for (const field of ['slug', 'name', 'description', 'schedule']) {
+        if (typeof j[field] !== 'string' || !j[field].trim()) {
+            throw new Error(`${prefix}: "${field}" is required and must be a non-empty string`);
+        }
+    }
+    // Priority
+    if (!VALID_PRIORITIES.includes(j.priority)) {
+        throw new Error(`${prefix}: "priority" must be one of ${VALID_PRIORITIES.join(', ')}, got "${j.priority}"`);
+    }
+    // Cron expression — try to parse it
+    try {
+        new Cron(j.schedule);
+    }
+    catch (err) {
+        throw new Error(`${prefix}: invalid cron expression "${j.schedule}": ${err}`);
+    }
+    // Enabled must be boolean
+    if (typeof j.enabled !== 'boolean') {
+        throw new Error(`${prefix}: "enabled" must be a boolean`);
+    }
+    // Execute block
+    if (!j.execute || typeof j.execute !== 'object') {
+        throw new Error(`${prefix}: "execute" must be an object with type and value`);
+    }
+    const exec = j.execute;
+    if (!['skill', 'prompt', 'script'].includes(exec.type)) {
+        throw new Error(`${prefix}: execute.type must be "skill", "prompt", or "script"`);
+    }
+    if (typeof exec.value !== 'string' || !exec.value.trim()) {
+        throw new Error(`${prefix}: execute.value is required`);
+    }
+}
+//# sourceMappingURL=JobLoader.js.map