instar 0.1.0

package/dist/commands/status.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `instar status` — Show agent infrastructure status.
+ *
+ * Checks for: config, tmux, server, sessions, scheduler.
+ */
+interface StatusOptions {
+    dir?: string;
+}
+export declare function showStatus(options: StatusOptions): Promise<void>;
+export {};
+//# sourceMappingURL=status.d.ts.map

package/dist/commands/status.js

@@ -0,0 +1,114 @@
+/**
+ * `instar status` — Show agent infrastructure status.
+ *
+ * Checks for: config, tmux, server, sessions, scheduler.
+ */
+import { execSync } from 'node:child_process';
+import pc from 'picocolors';
+import { loadConfig, detectTmuxPath } from '../core/Config.js';
+import { StateManager } from '../core/StateManager.js';
+export async function showStatus(options) {
+    let config;
+    try {
+        config = loadConfig(options.dir);
+    }
+    catch (err) {
+        console.log(pc.red(`Not initialized: ${err.message}`));
+        console.log(`Run ${pc.cyan('instar init')} first.`);
+        return;
+    }
+    console.log(pc.bold(`\nInstar Status: ${pc.cyan(config.projectName)}`));
+    console.log(`  Project: ${config.projectDir}`);
+    console.log(`  State:   ${config.stateDir}`);
+    console.log();
+    // Server status
+    const serverSessionName = `${config.projectName}-server`;
+    const tmuxPath = detectTmuxPath();
+    let serverRunning = false;
+    if (tmuxPath) {
+        try {
+            execSync(`${tmuxPath} has-session -t '=${serverSessionName}' 2>/dev/null`);
+            serverRunning = true;
+        }
+        catch {
+            // not running
+        }
+    }
+    console.log(pc.bold('  Server:'));
+    if (serverRunning) {
+        console.log(`    ${pc.green('●')} Running (tmux: ${serverSessionName}, port: ${config.port})`);
+        // Try to hit health endpoint
+        try {
+            const resp = execSync(`curl -s http://localhost:${config.port}/health`, { encoding: 'utf-8', timeout: 3000 });
+            const health = JSON.parse(resp);
+            console.log(`    Uptime: ${health.uptimeHuman}`);
+        }
+        catch {
+            console.log(`    ${pc.yellow('Could not reach health endpoint')}`);
+        }
+    }
+    else {
+        console.log(`    ${pc.red('●')} Not running`);
+    }
+    // Sessions
+    const state = new StateManager(config.stateDir);
+    const runningSessions = state.listSessions({ status: 'running' });
+    const allSessions = state.listSessions();
+    console.log();
+    console.log(pc.bold('  Sessions:'));
+    console.log(`    Running: ${runningSessions.length} / ${config.sessions.maxSessions} max`);
+    console.log(`    Total:   ${allSessions.length}`);
+    if (runningSessions.length > 0) {
+        for (const s of runningSessions) {
+            const age = timeSince(new Date(s.startedAt));
+            console.log(`    ${pc.green('●')} ${s.name} (${age}${s.jobSlug ? `, job: ${s.jobSlug}` : ''})`);
+        }
+    }
+    // Scheduler
+    console.log();
+    console.log(pc.bold('  Scheduler:'));
+    console.log(`    Enabled: ${config.scheduler.enabled ? pc.green('yes') : pc.dim('no')}`);
+    // Jobs
+    try {
+        const { loadJobs } = await import('../scheduler/JobLoader.js');
+        const jobs = loadJobs(config.scheduler.jobsFile);
+        const enabled = jobs.filter(j => j.enabled);
+        console.log(`    Jobs: ${enabled.length} enabled / ${jobs.length} total`);
+        if (jobs.length > 0) {
+            for (const job of jobs) {
+                const jobState = state.getJobState(job.slug);
+                const icon = job.enabled ? pc.green('●') : pc.dim('○');
+                const lastRun = jobState?.lastRun ? timeSince(new Date(jobState.lastRun)) + ' ago' : 'never';
+                console.log(`    ${icon} ${job.slug} [${job.priority}] — last: ${lastRun}`);
+            }
+        }
+    }
+    catch {
+        console.log(`    ${pc.dim('No jobs configured')}`);
+    }
+    // Recent activity
+    const recentEvents = state.queryEvents({ limit: 5 });
+    if (recentEvents.length > 0) {
+        console.log();
+        console.log(pc.bold('  Recent Activity:'));
+        for (const event of recentEvents) {
+            const age = timeSince(new Date(event.timestamp));
+            console.log(`    ${pc.dim(age + ' ago')} ${event.type}: ${event.summary}`);
+        }
+    }
+    console.log();
+}
+function timeSince(date) {
+    const seconds = Math.floor((Date.now() - date.getTime()) / 1000);
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h`;
+    const days = Math.floor(hours / 24);
+    return `${days}d`;
+}
+//# sourceMappingURL=status.js.map

package/dist/commands/user.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `instar user add|list` — Manage user profiles.
+ */
+interface UserAddOptions {
+    id: string;
+    name: string;
+    telegram?: string;
+    email?: string;
+    slack?: string;
+    permissions?: string[];
+}
+export declare function addUser(options: UserAddOptions): Promise<void>;
+export declare function listUsers(_options: {
+    dir?: string;
+}): Promise<void>;
+export {};
+//# sourceMappingURL=user.d.ts.map

package/dist/commands/user.js

@@ -0,0 +1,53 @@
+/**
+ * `instar user add|list` — Manage user profiles.
+ */
+import pc from 'picocolors';
+import { loadConfig, ensureStateDir } from '../core/Config.js';
+import { UserManager } from '../users/UserManager.js';
+export async function addUser(options) {
+    const config = loadConfig();
+    ensureStateDir(config.stateDir);
+    const userManager = new UserManager(config.stateDir);
+    const channels = [];
+    if (options.telegram) {
+        channels.push({ type: 'telegram', identifier: options.telegram });
+    }
+    if (options.email) {
+        channels.push({ type: 'email', identifier: options.email });
+    }
+    if (options.slack) {
+        channels.push({ type: 'slack', identifier: options.slack });
+    }
+    const profile = {
+        id: options.id,
+        name: options.name,
+        channels,
+        permissions: options.permissions || ['user'],
+        preferences: {},
+    };
+    userManager.upsertUser(profile);
+    console.log(pc.green(`User "${options.name}" (${options.id}) added.`));
+    if (channels.length > 0) {
+        console.log(`  Channels: ${channels.map(c => `${c.type}:${c.identifier}`).join(', ')}`);
+    }
+    console.log(`  Permissions: ${profile.permissions.join(', ')}`);
+}
+export async function listUsers(_options) {
+    const config = loadConfig();
+    const userManager = new UserManager(config.stateDir);
+    const users = userManager.listUsers();
+    if (users.length === 0) {
+        console.log(pc.dim('No users configured.'));
+        console.log(`Add one: ${pc.cyan('instar user add --id justin --name Justin')}`);
+        return;
+    }
+    console.log(pc.bold(`Users (${users.length}):\n`));
+    for (const user of users) {
+        console.log(`  ${pc.bold(user.name)} (${pc.dim(user.id)})`);
+        if (user.channels.length > 0) {
+            console.log(`    Channels: ${user.channels.map(c => `${c.type}:${c.identifier}`).join(', ')}`);
+        }
+        console.log(`    Permissions: ${user.permissions.join(', ')}`);
+    }
+}
+//# sourceMappingURL=user.js.map

package/dist/core/Config.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Auto-detection and configuration management.
+ *
+ * Finds tmux, Claude CLI, and project structure automatically.
+ * Adapted from dawn-server's config.ts — the battle-tested version.
+ */
+import type { AgentKitConfig } from './types.js';
+export declare function detectTmuxPath(): string | null;
+export declare function detectClaudePath(): string | null;
+export declare function detectProjectDir(startDir?: string): string;
+export declare function loadConfig(projectDir?: string): AgentKitConfig;
+/**
+ * Ensure the state directory structure exists.
+ */
+export declare function ensureStateDir(stateDir: string): void;
+//# sourceMappingURL=Config.d.ts.map

package/dist/core/Config.js

@@ -0,0 +1,144 @@
+/**
+ * Auto-detection and configuration management.
+ *
+ * Finds tmux, Claude CLI, and project structure automatically.
+ * Adapted from dawn-server's config.ts — the battle-tested version.
+ */
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+const DEFAULT_PORT = 4040;
+const DEFAULT_MAX_SESSIONS = 3;
+const DEFAULT_MAX_PARALLEL_JOBS = 2;
+export function detectTmuxPath() {
+    const candidates = [
+        '/opt/homebrew/bin/tmux', // macOS ARM (Homebrew)
+        '/usr/local/bin/tmux', // macOS Intel / Linux
+        '/usr/bin/tmux', // Linux system
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    // Fallback: check PATH
+    try {
+        const result = execSync('which tmux', { encoding: 'utf-8' }).trim();
+        if (result && fs.existsSync(result))
+            return result;
+    }
+    catch {
+        // tmux not found
+    }
+    return null;
+}
+export function detectClaudePath() {
+    const candidates = [
+        path.join(process.env.HOME || '', '.claude', 'local', 'claude'),
+        '/usr/local/bin/claude',
+        '/opt/homebrew/bin/claude',
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    // Fallback: check PATH
+    try {
+        const result = execSync('which claude', { encoding: 'utf-8' }).trim();
+        if (result && fs.existsSync(result))
+            return result;
+    }
+    catch {
+        // claude not found
+    }
+    return null;
+}
+export function detectProjectDir(startDir) {
+    let dir = startDir || process.cwd();
+    // Walk up to find a directory with CLAUDE.md or .git
+    while (dir !== path.dirname(dir)) {
+        if (fs.existsSync(path.join(dir, 'CLAUDE.md')) || fs.existsSync(path.join(dir, '.git'))) {
+            return dir;
+        }
+        dir = path.dirname(dir);
+    }
+    return process.cwd();
+}
+export function loadConfig(projectDir) {
+    const resolvedProjectDir = projectDir || detectProjectDir();
+    const configPath = path.join(resolvedProjectDir, '.instar', 'config.json');
+    const stateDir = path.join(resolvedProjectDir, '.instar');
+    // Load config file if it exists
+    let fileConfig = {};
+    if (fs.existsSync(configPath)) {
+        fileConfig = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    }
+    const tmuxPath = detectTmuxPath();
+    const claudePath = detectClaudePath();
+    if (!tmuxPath) {
+        throw new Error('tmux not found. Install with: brew install tmux (macOS) or apt install tmux (Linux)');
+    }
+    if (!claudePath) {
+        throw new Error('Claude CLI not found. Install from: https://docs.anthropic.com/en/docs/claude-code');
+    }
+    const projectName = fileConfig.projectName || path.basename(resolvedProjectDir);
+    const sessions = {
+        tmuxPath,
+        claudePath,
+        projectDir: resolvedProjectDir,
+        maxSessions: fileConfig.sessions?.maxSessions || DEFAULT_MAX_SESSIONS,
+        protectedSessions: fileConfig.sessions?.protectedSessions || [`${projectName}-server`],
+        completionPatterns: fileConfig.sessions?.completionPatterns || [
+            'has been automatically paused',
+            'Session ended',
+            'Interrupted by user',
+        ],
+    };
+    const scheduler = {
+        jobsFile: fileConfig.scheduler?.jobsFile || path.join(stateDir, 'jobs.json'),
+        enabled: fileConfig.scheduler?.enabled ?? false,
+        maxParallelJobs: fileConfig.scheduler?.maxParallelJobs ?? DEFAULT_MAX_PARALLEL_JOBS,
+        quotaThresholds: fileConfig.scheduler?.quotaThresholds || {
+            normal: 50,
+            elevated: 70,
+            critical: 85,
+            shutdown: 95,
+        },
+    };
+    return {
+        projectName,
+        projectDir: resolvedProjectDir,
+        stateDir,
+        port: fileConfig.port || DEFAULT_PORT,
+        sessions,
+        scheduler,
+        users: fileConfig.users || [],
+        messaging: fileConfig.messaging || [],
+        monitoring: fileConfig.monitoring || {
+            quotaTracking: true,
+            memoryMonitoring: true,
+            healthCheckIntervalMs: 30000,
+        },
+        authToken: fileConfig.authToken,
+        relationships: fileConfig.relationships || {
+            relationshipsDir: path.join(stateDir, 'relationships'),
+            maxRecentInteractions: 20,
+        },
+    };
+}
+/**
+ * Ensure the state directory structure exists.
+ */
+export function ensureStateDir(stateDir) {
+    const dirs = [
+        stateDir,
+        path.join(stateDir, 'state'),
+        path.join(stateDir, 'state', 'sessions'),
+        path.join(stateDir, 'state', 'jobs'),
+        path.join(stateDir, 'relationships'),
+        path.join(stateDir, 'logs'),
+    ];
+    for (const dir of dirs) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+//# sourceMappingURL=Config.js.map

package/dist/core/Prerequisites.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Prerequisite detection and installation guidance.
+ *
+ * Checks for required software (tmux, Claude CLI, Node.js)
+ * and provides clear installation instructions when something is missing.
+ */
+export interface PrerequisiteResult {
+    name: string;
+    found: boolean;
+    path?: string;
+    version?: string;
+    installHint: string;
+}
+export interface PrerequisiteCheck {
+    allMet: boolean;
+    results: PrerequisiteResult[];
+    missing: PrerequisiteResult[];
+}
+/**
+ * Check all prerequisites and return a structured result.
+ */
+export declare function checkPrerequisites(): PrerequisiteCheck;
+/**
+ * Print prerequisite check results to console.
+ * Returns true if all prerequisites are met.
+ */
+export declare function printPrerequisiteCheck(check: PrerequisiteCheck): boolean;
+//# sourceMappingURL=Prerequisites.d.ts.map

package/dist/core/Prerequisites.js

@@ -0,0 +1,159 @@
+/**
+ * Prerequisite detection and installation guidance.
+ *
+ * Checks for required software (tmux, Claude CLI, Node.js)
+ * and provides clear installation instructions when something is missing.
+ */
+import { execSync } from 'node:child_process';
+import pc from 'picocolors';
+import { detectTmuxPath, detectClaudePath } from './Config.js';
+/**
+ * Detect the current platform for install guidance.
+ */
+function detectPlatform() {
+    const platform = process.platform;
+    if (platform === 'darwin') {
+        const arch = process.arch;
+        return arch === 'arm64' ? 'macos-arm' : 'macos-intel';
+    }
+    if (platform === 'linux')
+        return 'linux';
+    return 'unknown';
+}
+/**
+ * Check if Homebrew is available (macOS).
+ */
+function hasHomebrew() {
+    try {
+        execSync('which brew', { encoding: 'utf-8', stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get tmux version if installed.
+ */
+function getTmuxVersion(tmuxPath) {
+    try {
+        const output = execSync(`${tmuxPath} -V`, { encoding: 'utf-8', stdio: 'pipe' }).trim();
+        return output.replace('tmux ', '');
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Get Claude CLI version if installed.
+ */
+function getClaudeVersion(claudePath) {
+    try {
+        const output = execSync(`${claudePath} --version 2>/dev/null || echo unknown`, {
+            encoding: 'utf-8',
+            stdio: 'pipe',
+            timeout: 5000,
+        }).trim();
+        return output || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Get Node.js version.
+ */
+function getNodeVersion() {
+    const version = process.version; // e.g., "v20.11.0"
+    const major = parseInt(version.slice(1).split('.')[0], 10);
+    return { version, major };
+}
+/**
+ * Build install hint for tmux based on platform.
+ */
+function tmuxInstallHint() {
+    const platform = detectPlatform();
+    switch (platform) {
+        case 'macos-arm':
+        case 'macos-intel':
+            return hasHomebrew()
+                ? 'Install with: brew install tmux'
+                : 'Install Homebrew first (https://brew.sh), then: brew install tmux';
+        case 'linux':
+            return 'Install with: sudo apt install tmux (Debian/Ubuntu) or sudo yum install tmux (RHEL/CentOS)';
+        default:
+            return 'Install tmux: https://github.com/tmux/tmux/wiki/Installing';
+    }
+}
+/**
+ * Build install hint for Claude CLI based on platform.
+ */
+function claudeInstallHint() {
+    return 'Install Claude Code: npm install -g @anthropic-ai/claude-code\n  Docs: https://docs.anthropic.com/en/docs/claude-code';
+}
+/**
+ * Check all prerequisites and return a structured result.
+ */
+export function checkPrerequisites() {
+    const results = [];
+    // 1. Node.js >= 18
+    const node = getNodeVersion();
+    results.push({
+        name: 'Node.js',
+        found: node.major >= 18,
+        version: node.version,
+        installHint: node.major < 18
+            ? `Node.js 18+ required (found ${node.version}). Update: https://nodejs.org`
+            : '',
+    });
+    // 2. tmux
+    const tmuxPath = detectTmuxPath();
+    results.push({
+        name: 'tmux',
+        found: !!tmuxPath,
+        path: tmuxPath || undefined,
+        version: tmuxPath ? getTmuxVersion(tmuxPath) : undefined,
+        installHint: tmuxInstallHint(),
+    });
+    // 3. Claude CLI
+    const claudePath = detectClaudePath();
+    results.push({
+        name: 'Claude CLI',
+        found: !!claudePath,
+        path: claudePath || undefined,
+        version: claudePath ? getClaudeVersion(claudePath) : undefined,
+        installHint: claudeInstallHint(),
+    });
+    const missing = results.filter(r => !r.found);
+    return {
+        allMet: missing.length === 0,
+        results,
+        missing,
+    };
+}
+/**
+ * Print prerequisite check results to console.
+ * Returns true if all prerequisites are met.
+ */
+export function printPrerequisiteCheck(check) {
+    console.log(pc.bold('  Checking prerequisites...'));
+    console.log();
+    for (const result of check.results) {
+        if (result.found) {
+            const versionStr = result.version ? ` (${result.version})` : '';
+            const pathStr = result.path ? pc.dim(` ${result.path}`) : '';
+            console.log(`  ${pc.green('✓')} ${result.name}${versionStr}${pathStr}`);
+        }
+        else {
+            console.log(`  ${pc.red('✗')} ${result.name} — not found`);
+            console.log(`    ${result.installHint}`);
+        }
+    }
+    console.log();
+    if (!check.allMet) {
+        console.log(pc.red(`  ${check.missing.length} prerequisite(s) missing. Install them and try again.`));
+        console.log();
+    }
+    return check.allMet;
+}
+//# sourceMappingURL=Prerequisites.js.map

package/dist/core/RelationshipManager.d.ts

@@ -0,0 +1,73 @@
+/**
+ * RelationshipManager — Core system for tracking everyone the agent interacts with.
+ *
+ * Relationships are fundamental, not a plugin. Same tier as identity and memory.
+ * Every person the agent interacts with — across any channel/platform — gets a
+ * relationship record that grows over time.
+ *
+ * Architecture:
+ * - One JSON file per person in .instar/relationships/
+ * - Cross-platform identity resolution via channel index
+ * - Auto-enrichment from every interaction
+ * - Context injection before any interaction with a known person
+ */
+import type { RelationshipRecord, RelationshipManagerConfig, InteractionSummary, UserChannel } from './types.js';
+export declare class RelationshipManager {
+    private relationships;
+    /** Maps "channel_type:identifier" -> relationship ID for cross-platform resolution */
+    private channelIndex;
+    private config;
+    constructor(config: RelationshipManagerConfig);
+    /**
+     * Find or create a relationship from an incoming interaction.
+     * Resolves cross-platform: if the same person messages from Telegram and email,
+     * this returns the same relationship.
+     */
+    findOrCreate(name: string, channel: UserChannel): RelationshipRecord;
+    /**
+     * Resolve a channel identifier to an existing relationship, or null.
+     */
+    resolveByChannel(channel: UserChannel): RelationshipRecord | null;
+    /**
+     * Get a relationship by ID.
+     */
+    get(id: string): RelationshipRecord | null;
+    /**
+     * Get all relationships, optionally sorted by significance or recency.
+     */
+    getAll(sortBy?: 'significance' | 'recent' | 'name'): RelationshipRecord[];
+    /**
+     * Record an interaction with a person. Updates recency, count, and interaction log.
+     */
+    recordInteraction(id: string, interaction: InteractionSummary): void;
+    /**
+     * Update notes or other metadata for a relationship.
+     */
+    updateNotes(id: string, notes: string): void;
+    /**
+     * Update the arc summary for a relationship.
+     */
+    updateArcSummary(id: string, arcSummary: string): void;
+    /**
+     * Link a new channel to an existing relationship (cross-platform identity merge).
+     */
+    linkChannel(id: string, channel: UserChannel): void;
+    /**
+     * Merge two relationship records (when we discover two channels are the same person).
+     */
+    mergeRelationships(keepId: string, mergeId: string): void;
+    /**
+     * Generate context string for injection into a Claude session before interacting
+     * with a known person. This is what makes the agent "know" who it's talking to.
+     */
+    getContextForPerson(id: string): string | null;
+    /**
+     * Find relationships that haven't been contacted in a while.
+     */
+    getStaleRelationships(daysThreshold?: number): RelationshipRecord[];
+    private loadAll;
+    private save;
+    private deleteFile;
+    private calculateSignificance;
+}
+//# sourceMappingURL=RelationshipManager.d.ts.map