instar 0.1.0

package/tests/integration/server-full.test.ts

@@ -0,0 +1,284 @@
+/**
+ * Integration test — full server with all Tier 1 systems wired.
+ *
+ * Tests the server with relationships, auth, scheduler, and
+ * mocked Telegram running together. Verifies cross-system interactions.
+ */
+
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import request from 'supertest';
+import { AgentServer } from '../../src/server/AgentServer.js';
+import { RelationshipManager } from '../../src/core/RelationshipManager.js';
+import { JobScheduler } from '../../src/scheduler/JobScheduler.js';
+import {
+  createTempProject,
+  createMockSessionManager,
+  createSampleJobsFile,
+} from '../helpers/setup.js';
+import type { TempProject, MockSessionManager } from '../helpers/setup.js';
+import type { AgentKitConfig } from '../../src/core/types.js';
+
+describe('Full server integration', () => {
+  let project: TempProject;
+  let relationships: RelationshipManager;
+  let scheduler: JobScheduler;
+  let mockSM: MockSessionManager;
+  let server: AgentServer;
+  let app: ReturnType<AgentServer['getApp']>;
+  const AUTH_TOKEN = 'test-auth-token-integration';
+
+  beforeAll(() => {
+    project = createTempProject();
+
+    // Set up relationships
+    const relDir = path.join(project.stateDir, 'relationships');
+    fs.mkdirSync(relDir, { recursive: true });
+    relationships = new RelationshipManager({
+      relationshipsDir: relDir,
+      maxRecentInteractions: 20,
+    });
+
+    // Seed relationship data
+    const alice = relationships.findOrCreate('Alice', { type: 'telegram', identifier: '111' });
+    relationships.recordInteraction(alice.id, {
+      timestamp: new Date().toISOString(),
+      channel: 'telegram',
+      summary: 'Integration test chat',
+      topics: ['testing', 'CI'],
+    });
+
+    const bob = relationships.findOrCreate('Bob', { type: 'email', identifier: 'bob@test.com' });
+    relationships.recordInteraction(bob.id, {
+      timestamp: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(), // 30 days ago
+      channel: 'email',
+      summary: 'Old email exchange',
+      topics: ['philosophy'],
+    });
+    // Boost Bob's significance enough to appear in stale
+    for (let i = 0; i < 5; i++) {
+      relationships.recordInteraction(bob.id, {
+        timestamp: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(),
+        channel: 'email',
+        summary: `Discussion ${i}`,
+        topics: [`topic-${i}`],
+      });
+    }
+
+    // Set up scheduler
+    mockSM = createMockSessionManager();
+    const jobsFile = createSampleJobsFile(project.stateDir);
+    scheduler = new JobScheduler(
+      {
+        jobsFile,
+        enabled: true,
+        maxParallelJobs: 3,
+        quotaThresholds: { normal: 50, elevated: 70, critical: 85, shutdown: 95 },
+      },
+      mockSM as any,
+      project.state,
+    );
+    scheduler.start();
+
+    const config: AgentKitConfig = {
+      projectName: 'integration-test',
+      projectDir: project.dir,
+      stateDir: project.stateDir,
+      port: 0,
+      authToken: AUTH_TOKEN,
+      sessions: {
+        tmuxPath: '/usr/bin/tmux',
+        claudePath: '/usr/bin/claude',
+        projectDir: project.dir,
+        maxSessions: 5,
+        protectedSessions: [],
+        completionPatterns: [],
+      },
+      scheduler: {
+        jobsFile,
+        enabled: true,
+        maxParallelJobs: 3,
+        quotaThresholds: { normal: 50, elevated: 70, critical: 85, shutdown: 95 },
+      },
+      users: [],
+      messaging: [],
+      monitoring: {
+        quotaTracking: false,
+        memoryMonitoring: false,
+        healthCheckIntervalMs: 30000,
+      },
+      relationships: {
+        relationshipsDir: relDir,
+        maxRecentInteractions: 20,
+      },
+    };
+
+    server = new AgentServer({
+      config,
+      sessionManager: mockSM as any,
+      state: project.state,
+      scheduler,
+      relationships,
+    });
+    app = server.getApp();
+  });
+
+  afterAll(() => {
+    scheduler?.stop();
+    project.cleanup();
+  });
+
+  // ── Auth enforcement ─────────────────────────────────────────
+
+  describe('auth enforcement across all endpoints', () => {
+    it('allows /health without auth', async () => {
+      const res = await request(app).get('/health');
+      expect(res.status).toBe(200);
+    });
+
+    it('blocks /status without auth', async () => {
+      const res = await request(app).get('/status');
+      expect(res.status).toBe(401);
+    });
+
+    it('blocks /sessions without auth', async () => {
+      const res = await request(app).get('/sessions');
+      expect(res.status).toBe(401);
+    });
+
+    it('blocks /jobs without auth', async () => {
+      const res = await request(app).get('/jobs');
+      expect(res.status).toBe(401);
+    });
+
+    it('blocks /relationships without auth', async () => {
+      const res = await request(app).get('/relationships');
+      expect(res.status).toBe(401);
+    });
+
+    it('blocks /events without auth', async () => {
+      const res = await request(app).get('/events');
+      expect(res.status).toBe(401);
+    });
+
+    it('allows all with valid auth', async () => {
+      const auth = { Authorization: `Bearer ${AUTH_TOKEN}` };
+
+      const [health, status, sessions, jobs, rels, events] = await Promise.all([
+        request(app).get('/health'),
+        request(app).get('/status').set(auth),
+        request(app).get('/sessions').set(auth),
+        request(app).get('/jobs').set(auth),
+        request(app).get('/relationships').set(auth),
+        request(app).get('/events').set(auth),
+      ]);
+
+      expect(health.status).toBe(200);
+      expect(status.status).toBe(200);
+      expect(sessions.status).toBe(200);
+      expect(jobs.status).toBe(200);
+      expect(rels.status).toBe(200);
+      expect(events.status).toBe(200);
+    });
+  });
+
+  // ── Cross-system: status includes scheduler ──────────────────
+
+  describe('cross-system status', () => {
+    it('includes scheduler status with job counts', async () => {
+      const res = await request(app)
+        .get('/status')
+        .set('Authorization', `Bearer ${AUTH_TOKEN}`);
+
+      expect(res.status).toBe(200);
+      expect(res.body.scheduler).not.toBeNull();
+      expect(res.body.scheduler.running).toBe(true);
+      expect(res.body.scheduler.enabledJobs).toBe(2);
+    });
+  });
+
+  // ── Cross-system: job trigger + session spawn ────────────────
+
+  describe('job trigger via API', () => {
+    it('triggers a job and creates a session', async () => {
+      const res = await request(app)
+        .post('/jobs/health-check/trigger')
+        .set('Authorization', `Bearer ${AUTH_TOKEN}`)
+        .send({ reason: 'integration-test' });
+
+      expect(res.status).toBe(200);
+      expect(res.body.result).toBe('triggered');
+      expect(mockSM._spawnCount).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  // ── Cross-system: relationships + API ────────────────────────
+
+  describe('relationship API with persistence', () => {
+    it('GET /relationships returns seeded data with auth', async () => {
+      const res = await request(app)
+        .get('/relationships')
+        .set('Authorization', `Bearer ${AUTH_TOKEN}`);
+
+      expect(res.status).toBe(200);
+      expect(res.body.relationships).toHaveLength(2);
+      const names = res.body.relationships.map((r: any) => r.name);
+      expect(names).toContain('Alice');
+      expect(names).toContain('Bob');
+    });
+
+    it('GET /relationships/:id/context returns enriched context', async () => {
+      const alice = relationships.getAll().find(r => r.name === 'Alice')!;
+      const res = await request(app)
+        .get(`/relationships/${alice.id}/context`)
+        .set('Authorization', `Bearer ${AUTH_TOKEN}`);
+
+      expect(res.status).toBe(200);
+      expect(res.body.context).toContain('testing');
+      expect(res.body.context).toContain('CI');
+      expect(res.body.context).toContain('Integration test chat');
+    });
+
+    it('stale endpoint correctly identifies old relationships', async () => {
+      const res = await request(app)
+        .get('/relationships/stale?days=14')
+        .set('Authorization', `Bearer ${AUTH_TOKEN}`);
+
+      expect(res.status).toBe(200);
+      // Bob's last interaction was 30 days ago and significance >= 3
+      expect(res.body.stale.length).toBeGreaterThanOrEqual(1);
+      expect(res.body.stale.some((r: any) => r.name === 'Bob')).toBe(true);
+    });
+
+    it('relationship data persists to new manager instance', async () => {
+      const relDir = path.join(project.stateDir, 'relationships');
+
+      // Create a fresh manager from the same directory
+      const manager2 = new RelationshipManager({
+        relationshipsDir: relDir,
+        maxRecentInteractions: 20,
+      });
+
+      expect(manager2.getAll()).toHaveLength(2);
+      const alice = manager2.resolveByChannel({ type: 'telegram', identifier: '111' });
+      expect(alice).not.toBeNull();
+      expect(alice!.name).toBe('Alice');
+      expect(alice!.recentInteractions).toHaveLength(1);
+    });
+  });
+
+  // ── Cross-system: events capture scheduler activity ──────────
+
+  describe('event log captures cross-system activity', () => {
+    it('events include scheduler_start and job_triggered', async () => {
+      const res = await request(app)
+        .get('/events?since=1')
+        .set('Authorization', `Bearer ${AUTH_TOKEN}`);
+
+      expect(res.status).toBe(200);
+      const types = res.body.map((e: any) => e.type);
+      expect(types).toContain('scheduler_start');
+    });
+  });
+});

package/tests/integration/session-lifecycle.test.ts

@@ -0,0 +1,181 @@
+/**
+ * Integration test — real tmux sessions with a mock claude script.
+ *
+ * Requires tmux to be installed. Skips if not available.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { execSync } from 'node:child_process';
+import { SessionManager } from '../../src/core/SessionManager.js';
+import { detectTmuxPath } from '../../src/core/Config.js';
+import {
+  createTempProject,
+  createMockClaude,
+  cleanupTmuxSessions,
+  waitFor,
+} from '../helpers/setup.js';
+import type { TempProject } from '../helpers/setup.js';
+
+const TMUX_PREFIX = 'akit-integ-';
+
+// Skip entire suite if tmux is not available
+const tmuxPath = detectTmuxPath();
+const describeMaybe = tmuxPath ? describe : describe.skip;
+
+describeMaybe('Session Lifecycle (integration)', () => {
+  let project: TempProject;
+  let mockClaudePath: string;
+  let sm: SessionManager;
+
+  beforeAll(() => {
+    project = createTempProject();
+    mockClaudePath = createMockClaude(project.dir);
+
+    sm = new SessionManager(
+      {
+        tmuxPath: tmuxPath!,
+        claudePath: mockClaudePath,
+        projectDir: project.dir,
+        maxSessions: 3,
+        protectedSessions: [],
+        completionPatterns: ['Session ended'],
+      },
+      project.state,
+    );
+  });
+
+  afterAll(() => {
+    sm.stopMonitoring();
+    cleanupTmuxSessions(TMUX_PREFIX);
+    project.cleanup();
+  });
+
+  it('spawns a session and tracks it', async () => {
+    const session = await sm.spawnSession({
+      name: `${TMUX_PREFIX}basic`,
+      prompt: 'echo hello',
+    });
+
+    expect(session.status).toBe('running');
+    expect(session.tmuxSession).toContain(TMUX_PREFIX);
+
+    // Give tmux a moment to start
+    await new Promise(r => setTimeout(r, 500));
+
+    // Session should be alive
+    expect(sm.isSessionAlive(session.tmuxSession)).toBe(true);
+
+    // State should be persisted
+    const saved = project.state.getSession(session.id);
+    expect(saved).not.toBeNull();
+    expect(saved!.status).toBe('running');
+  });
+
+  it('captures output from session', async () => {
+    const session = await sm.spawnSession({
+      name: `${TMUX_PREFIX}output`,
+      prompt: 'echo hello',
+    });
+
+    await new Promise(r => setTimeout(r, 1000));
+
+    const output = sm.captureOutput(session.tmuxSession);
+    expect(output).not.toBeNull();
+    // Mock claude echoes its prompt
+    expect(output).toContain('Mock Claude session started');
+  });
+
+  it('detects completed sessions via reaping', async () => {
+    const session = await sm.spawnSession({
+      name: `${TMUX_PREFIX}complete`,
+      prompt: 'echo done',
+    });
+
+    // Mock claude exits after ~2s — wait for tmux session to disappear
+    await waitFor(
+      () => !sm.isSessionAlive(session.tmuxSession),
+      8000,
+    );
+
+    // Reap should detect and mark it completed
+    const reaped = sm.reapCompletedSessions();
+    // Session was already marked completed by listRunningSessions or monitor
+    const saved = project.state.getSession(session.id);
+    expect(saved!.status).toBe('completed');
+    expect(saved!.endedAt).toBeTruthy();
+  });
+
+  it('kills a session', async () => {
+    const session = await sm.spawnSession({
+      name: `${TMUX_PREFIX}kill`,
+      prompt: 'sleep 60', // Would run forever
+    });
+
+    await new Promise(r => setTimeout(r, 500));
+    expect(sm.isSessionAlive(session.tmuxSession)).toBe(true);
+
+    const killed = sm.killSession(session.id);
+    expect(killed).toBe(true);
+
+    // Give tmux a moment to clean up
+    await new Promise(r => setTimeout(r, 200));
+    expect(sm.isSessionAlive(session.tmuxSession)).toBe(false);
+
+    const saved = project.state.getSession(session.id);
+    expect(saved!.status).toBe('killed');
+  });
+
+  it('enforces max sessions', async () => {
+    // Use a separate project to avoid interference from other tests
+    const limitProject = createTempProject();
+    const limitSM = new SessionManager(
+      {
+        tmuxPath: tmuxPath!,
+        claudePath: mockClaudePath,
+        projectDir: limitProject.dir,
+        maxSessions: 1,
+        protectedSessions: [],
+        completionPatterns: [],
+      },
+      limitProject.state,
+    );
+
+    const s1 = await limitSM.spawnSession({
+      name: `${TMUX_PREFIX}limit1`,
+      prompt: 'sleep 30',
+    });
+
+    await expect(limitSM.spawnSession({
+      name: `${TMUX_PREFIX}limit2`,
+      prompt: 'sleep 30',
+    })).rejects.toThrow('Max sessions');
+
+    // Cleanup
+    limitSM.killSession(s1.id);
+    limitProject.cleanup();
+  });
+
+  it('emits sessionComplete via monitoring', async () => {
+    const completedSessions: string[] = [];
+    sm.on('sessionComplete', (session) => {
+      completedSessions.push(session.id);
+    });
+
+    const session = await sm.spawnSession({
+      name: `${TMUX_PREFIX}monitor`,
+      prompt: 'echo test',
+    });
+
+    // Start monitoring with fast interval
+    sm.startMonitoring(500);
+
+    // Mock claude exits after ~2s, monitoring should detect it
+    await waitFor(
+      () => completedSessions.includes(session.id),
+      8000,
+    );
+
+    expect(completedSessions).toContain(session.id);
+    sm.stopMonitoring();
+  });
+});

package/tests/unit/Config.test.ts

@@ -0,0 +1,22 @@
+import { describe, it, expect } from 'vitest';
+import { detectTmuxPath, detectClaudePath } from '../../src/core/Config.js';
+
+describe('Config', () => {
+  describe('detectTmuxPath', () => {
+    it('finds tmux on this system', () => {
+      const tmuxPath = detectTmuxPath();
+      // tmux should be installed on the dev machine
+      expect(tmuxPath).toBeTruthy();
+      expect(tmuxPath).toContain('tmux');
+    });
+  });
+
+  describe('detectClaudePath', () => {
+    it('finds Claude CLI on this system', () => {
+      const claudePath = detectClaudePath();
+      // Claude CLI should be installed on the dev machine
+      expect(claudePath).toBeTruthy();
+      expect(claudePath).toContain('claude');
+    });
+  });
+});

package/tests/unit/HealthChecker.test.ts

@@ -0,0 +1,168 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { HealthChecker } from '../../src/monitoring/HealthChecker.js';
+import { createTempProject, createMockSessionManager } from '../helpers/setup.js';
+import type { TempProject, MockSessionManager } from '../helpers/setup.js';
+import type { AgentKitConfig } from '../../src/core/types.js';
+
+describe('HealthChecker', () => {
+  let project: TempProject;
+  let mockSM: MockSessionManager;
+  let checker: HealthChecker;
+
+  const makeConfig = (overrides?: Partial<AgentKitConfig>): AgentKitConfig => ({
+    projectName: 'test-project',
+    projectDir: '/tmp/test',
+    stateDir: '', // set in beforeEach
+    port: 4040,
+    sessions: {
+      tmuxPath: '/opt/homebrew/bin/tmux',
+      claudePath: '/usr/bin/claude',
+      projectDir: '/tmp/test',
+      maxSessions: 3,
+      protectedSessions: [],
+      completionPatterns: [],
+    },
+    scheduler: {
+      jobsFile: '',
+      enabled: false,
+      maxParallelJobs: 2,
+      quotaThresholds: { normal: 50, elevated: 70, critical: 85, shutdown: 95 },
+    },
+    users: [],
+    messaging: [],
+    monitoring: {
+      quotaTracking: false,
+      memoryMonitoring: false,
+      healthCheckIntervalMs: 5000,
+    },
+    ...overrides,
+  });
+
+  beforeEach(() => {
+    project = createTempProject();
+    mockSM = createMockSessionManager();
+  });
+
+  afterEach(() => {
+    checker?.stopPeriodicChecks();
+    project.cleanup();
+  });
+
+  it('returns healthy when everything is ok', () => {
+    const config = makeConfig({ stateDir: project.stateDir });
+    checker = new HealthChecker(config, mockSM as any);
+
+    const status = checker.check();
+    expect(status.status).toBe('healthy');
+    expect(status.components.tmux).toBeDefined();
+    expect(status.components.sessions).toBeDefined();
+    expect(status.components.stateDir).toBeDefined();
+    expect(status.timestamp).toBeTruthy();
+  });
+
+  it('reports degraded when sessions at capacity', async () => {
+    const config = makeConfig({ stateDir: project.stateDir });
+    config.sessions.maxSessions = 1;
+
+    // Add a running session to the mock
+    await mockSM.spawnSession({ name: 'fill', prompt: 'test' });
+
+    checker = new HealthChecker(config, mockSM as any);
+
+    const status = checker.check();
+    expect(status.components.sessions.status).toBe('degraded');
+    expect(status.components.sessions.message).toContain('capacity');
+  });
+
+  it('reports unhealthy when state dir missing', () => {
+    const config = makeConfig({ stateDir: '/nonexistent/path' });
+    checker = new HealthChecker(config, mockSM as any);
+
+    const status = checker.check();
+    expect(status.components.stateDir.status).toBe('unhealthy');
+    expect(status.status).toBe('unhealthy');
+  });
+
+  it('does not include scheduler when none provided', () => {
+    const config = makeConfig({ stateDir: project.stateDir });
+    checker = new HealthChecker(config, mockSM as any);
+
+    const status = checker.check();
+    expect(status.components.scheduler).toBeUndefined();
+  });
+
+  it('includes scheduler status when provided', () => {
+    const config = makeConfig({ stateDir: project.stateDir });
+    const mockScheduler = {
+      getStatus: () => ({
+        running: true,
+        paused: false,
+        jobCount: 3,
+        enabledJobs: 2,
+        queueLength: 0,
+        activeJobSessions: 0,
+      }),
+    };
+    checker = new HealthChecker(config, mockSM as any, mockScheduler as any);
+
+    const status = checker.check();
+    expect(status.components.scheduler).toBeDefined();
+    expect(status.components.scheduler.status).toBe('healthy');
+  });
+
+  it('reports degraded scheduler when paused', () => {
+    const config = makeConfig({ stateDir: project.stateDir });
+    const mockScheduler = {
+      getStatus: () => ({
+        running: true,
+        paused: true,
+        jobCount: 3,
+        enabledJobs: 2,
+        queueLength: 0,
+        activeJobSessions: 0,
+      }),
+    };
+    checker = new HealthChecker(config, mockSM as any, mockScheduler as any);
+
+    const status = checker.check();
+    expect(status.components.scheduler.status).toBe('degraded');
+  });
+
+  it('getLastStatus returns null before first check', () => {
+    const config = makeConfig({ stateDir: project.stateDir });
+    checker = new HealthChecker(config, mockSM as any);
+
+    expect(checker.getLastStatus()).toBeNull();
+  });
+
+  it('getLastStatus returns result after check', () => {
+    const config = makeConfig({ stateDir: project.stateDir });
+    checker = new HealthChecker(config, mockSM as any);
+
+    checker.check();
+    expect(checker.getLastStatus()).not.toBeNull();
+    expect(checker.getLastStatus()!.status).toBe('healthy');
+  });
+
+  it('periodic checks update status', async () => {
+    const config = makeConfig({ stateDir: project.stateDir });
+    checker = new HealthChecker(config, mockSM as any);
+
+    checker.startPeriodicChecks(100);
+
+    // Should run immediately
+    expect(checker.getLastStatus()).not.toBeNull();
+
+    // Wait for another check
+    await new Promise(r => setTimeout(r, 250));
+    const ts1 = checker.getLastStatus()!.timestamp;
+
+    await new Promise(r => setTimeout(r, 200));
+    const ts2 = checker.getLastStatus()!.timestamp;
+
+    // Timestamps should differ (multiple checks ran)
+    expect(ts2).not.toBe(ts1);
+
+    checker.stopPeriodicChecks();
+  });
+});