agentctl-swarm 0.1.1

package/lib/daemon.js

@@ -0,0 +1,336 @@
+/**
+ * Daemon
+ * A lightweight idle process that listens for tasks on agentchat
+ * and promotes to a full agent session when work is available.
+ * One daemon per swarm slot.
+ */
+
+import { EventEmitter } from 'events';
+import { spawn as spawnProcess } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+
+/** Daemon states */
+export const DaemonState = {
+  IDLE: 'idle',
+  PROMOTING: 'promoting',
+  ACTIVE: 'active',
+  DEMOTING: 'demoting',
+  CRASHED: 'crashed',
+};
+
+/**
+ * @typedef {object} DaemonConfig
+ * @property {string} agentId - agentchat agent ID
+ * @property {string} name - agent name
+ * @property {string} workspace - workspace directory path
+ * @property {string} [role] - agent role (default: 'builder')
+ * @property {string[]} [channels] - agentchat channels to join (default: ['#agents'])
+ * @property {number} [heartbeatIntervalMs] - heartbeat interval (default: 30000)
+ */
+
+export class Daemon extends EventEmitter {
+  /**
+   * @param {DaemonConfig} config
+   */
+  constructor(config) {
+    super();
+
+    if (!config.agentId) throw new Error('daemon requires agentId');
+    if (!config.name) throw new Error('daemon requires name');
+    if (!config.workspace) throw new Error('daemon requires workspace');
+
+    this.agentId = config.agentId;
+    this.name = config.name;
+    this.workspace = config.workspace;
+    this.role = config.role || 'builder';
+    this.channels = config.channels || ['#agents'];
+    this.heartbeatIntervalMs = config.heartbeatIntervalMs || 30000;
+
+    this.state = DaemonState.IDLE;
+    this.currentTask = null;
+    this.claudeProcess = null;
+    this._heartbeatTimer = null;
+  }
+
+  /**
+   * Start the daemon — begin sending heartbeats and listening.
+   * Does NOT connect to agentchat (that's the supervisor's responsibility
+   * to wire up message routing).
+   */
+  start() {
+    this.state = DaemonState.IDLE;
+    this._startHeartbeat();
+    this.emit('started', { agentId: this.agentId });
+  }
+
+  /**
+   * Stop the daemon — cleanup timers, kill active process if any.
+   */
+  stop() {
+    this._stopHeartbeat();
+
+    if (this.claudeProcess) {
+      this.claudeProcess.kill('SIGTERM');
+      this.claudeProcess = null;
+    }
+
+    this.state = DaemonState.IDLE;
+    this.currentTask = null;
+    this.emit('stopped', { agentId: this.agentId });
+  }
+
+  /**
+   * Evaluate whether a task matches this daemon's role.
+   * @param {object} task
+   * @param {string} task.role - required role
+   * @param {string} [task.component] - component name
+   * @returns {boolean}
+   */
+  matchesRole(task) {
+    if (!task || !task.role) return this.role === 'general';
+    return task.role === this.role || this.role === 'general';
+  }
+
+  /**
+   * Handle an incoming message from the work channel.
+   * Evaluates task announcements and ASSIGN messages.
+   * @param {object} msg
+   */
+  handleMessage(msg) {
+    if (this.state !== DaemonState.IDLE) return;
+
+    // Check for ASSIGN directed at this daemon
+    if (msg.type === 'ASSIGN' && msg.agentId === this.agentId) {
+      this._requestPromotion(msg.task);
+      return;
+    }
+
+    // Check for task announcements that match our role
+    if (msg.type === 'TASK_AVAILABLE' && this.matchesRole(msg.task)) {
+      this.emit('claim', {
+        agentId: this.agentId,
+        component: msg.task.component,
+        role: this.role,
+      });
+    }
+  }
+
+  /**
+   * Request promotion from supervisor.
+   * Emits 'promote-request' — supervisor must call approvePromotion() or denyPromotion().
+   * @param {object} task
+   */
+  _requestPromotion(task) {
+    this.state = DaemonState.PROMOTING;
+    this.currentTask = task;
+
+    this.emit('promote-request', {
+      agentId: this.agentId,
+      task,
+    });
+  }
+
+  /**
+   * Supervisor approves promotion — spawn the claude session.
+   * @param {object} task
+   * @param {string} task.prompt - the task prompt
+   * @param {string} [task.id] - task identifier
+   * @param {string} [task.component] - component being built
+   */
+  approvePromotion(task) {
+    if (this.state !== DaemonState.PROMOTING) {
+      this.emit('error', { agentId: this.agentId, error: 'Cannot promote: not in promoting state' });
+      return;
+    }
+
+    this.currentTask = task || this.currentTask;
+
+    // Write task context before starting
+    this._writeContext(`# Active Task\n\nTask: ${this.currentTask.component || 'unknown'}\nPrompt: ${this.currentTask.prompt || 'none'}\nStarted: ${new Date().toISOString()}\n`);
+
+    // Spawn claude session
+    this._spawnClaude(this.currentTask.prompt || 'Execute the assigned task.');
+  }
+
+  /**
+   * Supervisor denies promotion — return to idle.
+   * @param {string} [reason]
+   */
+  denyPromotion(reason) {
+    if (this.state !== DaemonState.PROMOTING) return;
+
+    this.state = DaemonState.IDLE;
+    this.currentTask = null;
+
+    this.emit('unclaim', {
+      agentId: this.agentId,
+      reason: reason || 'promotion denied',
+    });
+  }
+
+  /**
+   * Spawn a claude -p session in the workspace.
+   * @param {string} prompt
+   */
+  _spawnClaude(prompt) {
+    this.state = DaemonState.ACTIVE;
+    this._stopHeartbeat(); // Active agents don't send idle heartbeats
+
+    const args = ['-p', prompt, '--cwd', this.workspace];
+
+    try {
+      this.claudeProcess = spawnProcess('claude', args, {
+        cwd: this.workspace,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+
+      this.emit('promoted', {
+        agentId: this.agentId,
+        pid: this.claudeProcess.pid,
+        task: this.currentTask,
+      });
+
+      let stdout = '';
+      let stderr = '';
+
+      this.claudeProcess.stdout.on('data', (data) => {
+        const chunk = data.toString();
+        stdout += chunk;
+        this.emit('output', { agentId: this.agentId, data: chunk, stream: 'stdout' });
+      });
+
+      this.claudeProcess.stderr.on('data', (data) => {
+        const chunk = data.toString();
+        stderr += chunk;
+        this.emit('output', { agentId: this.agentId, data: chunk, stream: 'stderr' });
+      });
+
+      this.claudeProcess.on('exit', (code, signal) => {
+        this.claudeProcess = null;
+        this._handleClaudeExit(code, signal, stdout, stderr);
+      });
+
+      this.claudeProcess.on('error', (err) => {
+        this.claudeProcess = null;
+        this._handleClaudeError(err);
+      });
+    } catch (err) {
+      this._handleClaudeError(err);
+    }
+  }
+
+  /**
+   * Handle claude process exit — begin demotion.
+   */
+  _handleClaudeExit(code, signal, stdout, stderr) {
+    this.state = DaemonState.DEMOTING;
+
+    const success = code === 0;
+    const result = {
+      agentId: this.agentId,
+      task: this.currentTask,
+      exitCode: code,
+      signal,
+      success,
+      output: stdout.slice(-2000), // Last 2000 chars
+    };
+
+    // Save context for crash recovery
+    this._writeContext(
+      `# Last Task\n\n` +
+      `Task: ${this.currentTask?.component || 'unknown'}\n` +
+      `Result: ${success ? 'SUCCESS' : 'FAIL'}\n` +
+      `Exit code: ${code}\n` +
+      `Completed: ${new Date().toISOString()}\n` +
+      `\n## Output (last 500 chars)\n\n${stdout.slice(-500)}\n`
+    );
+
+    if (success) {
+      this.emit('done', result);
+    } else {
+      this.emit('fail', result);
+    }
+
+    // Complete demotion
+    this.state = DaemonState.IDLE;
+    this.currentTask = null;
+    this._startHeartbeat();
+
+    this.emit('demoted', { agentId: this.agentId });
+  }
+
+  /**
+   * Handle claude spawn/runtime error.
+   */
+  _handleClaudeError(err) {
+    this.state = DaemonState.CRASHED;
+
+    this._writeContext(
+      `# Crash\n\nError: ${err.message}\nTime: ${new Date().toISOString()}\n`
+    );
+
+    this.emit('fail', {
+      agentId: this.agentId,
+      task: this.currentTask,
+      exitCode: null,
+      signal: null,
+      success: false,
+      error: err.message,
+    });
+
+    this.emit('crashed', { agentId: this.agentId, error: err.message });
+  }
+
+  /**
+   * Write context.md to workspace.
+   * @param {string} content
+   */
+  _writeContext(content) {
+    try {
+      fs.writeFileSync(path.join(this.workspace, 'context.md'), content);
+    } catch {
+      // Best effort — don't crash daemon on write failure
+    }
+  }
+
+  /**
+   * Start periodic heartbeat.
+   */
+  _startHeartbeat() {
+    this._stopHeartbeat();
+    this._heartbeatTimer = setInterval(() => {
+      this.emit('heartbeat', {
+        agentId: this.agentId,
+        status: this.state,
+      });
+    }, this.heartbeatIntervalMs);
+  }
+
+  /**
+   * Stop periodic heartbeat.
+   */
+  _stopHeartbeat() {
+    if (this._heartbeatTimer) {
+      clearInterval(this._heartbeatTimer);
+      this._heartbeatTimer = null;
+    }
+  }
+
+  /**
+   * Get current daemon info.
+   */
+  info() {
+    return {
+      agentId: this.agentId,
+      name: this.name,
+      role: this.role,
+      state: this.state,
+      workspace: this.workspace,
+      channels: this.channels,
+      currentTask: this.currentTask,
+      hasClaude: !!this.claudeProcess,
+      pid: this.claudeProcess?.pid || null,
+    };
+  }
+}

package/lib/daemon.test.js

@@ -0,0 +1,314 @@
+/**
+ * Daemon Tests
+ */
+
+import { test, describe, before, after } from 'node:test';
+import assert from 'node:assert';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { Daemon, DaemonState } from './daemon.js';
+
+const tmpBase = path.join(os.tmpdir(), `daemon-test-${Date.now()}`);
+
+function makeDaemon(overrides = {}) {
+  const name = `test-daemon-${Math.random().toString(36).slice(2, 8)}`;
+  const workspace = path.join(tmpBase, name);
+  fs.mkdirSync(workspace, { recursive: true });
+
+  return new Daemon({
+    agentId: `agent-${name}`,
+    name,
+    workspace,
+    heartbeatIntervalMs: 100,
+    ...overrides,
+  });
+}
+
+describe('Daemon', () => {
+  before(() => {
+    fs.mkdirSync(tmpBase, { recursive: true });
+  });
+
+  after(() => {
+    fs.rmSync(tmpBase, { recursive: true, force: true });
+  });
+
+  test('constructor requires agentId, name, workspace', () => {
+    assert.throws(() => new Daemon({}), /agentId/);
+    assert.throws(() => new Daemon({ agentId: 'a' }), /name/);
+    assert.throws(() => new Daemon({ agentId: 'a', name: 'b' }), /workspace/);
+  });
+
+  test('starts in idle state', () => {
+    const d = makeDaemon();
+    assert.strictEqual(d.state, DaemonState.IDLE);
+    d.stop();
+  });
+
+  test('start emits started event', () => {
+    const d = makeDaemon();
+    const events = [];
+    d.on('started', e => events.push(e));
+    d.start();
+    assert.strictEqual(events.length, 1);
+    assert.strictEqual(events[0].agentId, d.agentId);
+    d.stop();
+  });
+
+  test('sends heartbeats when idle', async () => {
+    const d = makeDaemon({ heartbeatIntervalMs: 50 });
+    const heartbeats = [];
+    d.on('heartbeat', h => heartbeats.push(h));
+    d.start();
+
+    await new Promise(r => setTimeout(r, 180));
+    d.stop();
+
+    assert.ok(heartbeats.length >= 2, `Expected >=2 heartbeats, got ${heartbeats.length}`);
+    assert.strictEqual(heartbeats[0].status, DaemonState.IDLE);
+  });
+
+  test('matchesRole for builder', () => {
+    const d = makeDaemon({ role: 'builder' });
+    assert.strictEqual(d.matchesRole({ role: 'builder' }), true);
+    assert.strictEqual(d.matchesRole({ role: 'auditor' }), false);
+    d.stop();
+  });
+
+  test('matchesRole for general matches everything', () => {
+    const d = makeDaemon({ role: 'general' });
+    assert.strictEqual(d.matchesRole({ role: 'builder' }), true);
+    assert.strictEqual(d.matchesRole({ role: 'auditor' }), true);
+    assert.strictEqual(d.matchesRole({}), true);
+    d.stop();
+  });
+
+  test('handleMessage ignores when not idle', () => {
+    const d = makeDaemon();
+    d.state = DaemonState.ACTIVE;
+    const events = [];
+    d.on('claim', e => events.push(e));
+    d.on('promote-request', e => events.push(e));
+
+    d.handleMessage({ type: 'TASK_AVAILABLE', task: { role: 'builder' } });
+    d.handleMessage({ type: 'ASSIGN', agentId: d.agentId, task: {} });
+
+    assert.strictEqual(events.length, 0);
+    d.stop();
+  });
+
+  test('handleMessage emits claim for matching task', () => {
+    const d = makeDaemon({ role: 'builder' });
+    d.start();
+    const claims = [];
+    d.on('claim', c => claims.push(c));
+
+    d.handleMessage({
+      type: 'TASK_AVAILABLE',
+      task: { role: 'builder', component: 'spawner' },
+    });
+
+    assert.strictEqual(claims.length, 1);
+    assert.strictEqual(claims[0].component, 'spawner');
+    d.stop();
+  });
+
+  test('handleMessage does not claim non-matching role', () => {
+    const d = makeDaemon({ role: 'builder' });
+    d.start();
+    const claims = [];
+    d.on('claim', c => claims.push(c));
+
+    d.handleMessage({
+      type: 'TASK_AVAILABLE',
+      task: { role: 'auditor', component: 'qa' },
+    });
+
+    assert.strictEqual(claims.length, 0);
+    d.stop();
+  });
+
+  test('ASSIGN triggers promote-request', () => {
+    const d = makeDaemon();
+    d.start();
+    const requests = [];
+    d.on('promote-request', r => requests.push(r));
+
+    d.handleMessage({
+      type: 'ASSIGN',
+      agentId: d.agentId,
+      task: { component: 'spawner', prompt: 'build it' },
+    });
+
+    assert.strictEqual(requests.length, 1);
+    assert.strictEqual(d.state, DaemonState.PROMOTING);
+    d.stop();
+  });
+
+  test('denyPromotion returns to idle', () => {
+    const d = makeDaemon();
+    d.start();
+    const unclaims = [];
+    d.on('unclaim', u => unclaims.push(u));
+
+    d.handleMessage({
+      type: 'ASSIGN',
+      agentId: d.agentId,
+      task: { component: 'spawner' },
+    });
+
+    assert.strictEqual(d.state, DaemonState.PROMOTING);
+    d.denyPromotion('quota exceeded');
+
+    assert.strictEqual(d.state, DaemonState.IDLE);
+    assert.strictEqual(d.currentTask, null);
+    assert.strictEqual(unclaims.length, 1);
+    assert.ok(unclaims[0].reason.includes('quota'));
+    d.stop();
+  });
+
+  test('approvePromotion in wrong state emits error', () => {
+    const d = makeDaemon();
+    d.start();
+    const errors = [];
+    d.on('error', e => errors.push(e));
+
+    d.approvePromotion({ prompt: 'test' });
+    assert.strictEqual(errors.length, 1);
+    assert.ok(errors[0].error.includes('not in promoting'));
+    d.stop();
+  });
+
+  test('approvePromotion writes context.md', () => {
+    const d = makeDaemon();
+    d.start();
+
+    // Get into promoting state
+    d.handleMessage({
+      type: 'ASSIGN',
+      agentId: d.agentId,
+      task: { component: 'test-comp', prompt: 'build the test component' },
+    });
+
+    // Override _spawnClaude to avoid actually running claude
+    d._spawnClaude = () => {
+      d.state = DaemonState.ACTIVE;
+    };
+
+    d.approvePromotion({ component: 'test-comp', prompt: 'build the test component' });
+
+    const contextPath = path.join(d.workspace, 'context.md');
+    assert.ok(fs.existsSync(contextPath));
+    const content = fs.readFileSync(contextPath, 'utf8');
+    assert.ok(content.includes('test-comp'));
+    d.stop();
+  });
+
+  test('demotion writes context and returns to idle', () => {
+    const d = makeDaemon();
+    d.start();
+    const doneEvents = [];
+    const demotedEvents = [];
+    d.on('done', e => doneEvents.push(e));
+    d.on('demoted', e => demotedEvents.push(e));
+
+    // Simulate full lifecycle
+    d.state = DaemonState.ACTIVE;
+    d.currentTask = { component: 'test', prompt: 'test task' };
+
+    // Simulate claude exit
+    d._handleClaudeExit(0, null, 'build complete', '');
+
+    assert.strictEqual(d.state, DaemonState.IDLE);
+    assert.strictEqual(d.currentTask, null);
+    assert.strictEqual(doneEvents.length, 1);
+    assert.strictEqual(doneEvents[0].success, true);
+    assert.strictEqual(demotedEvents.length, 1);
+
+    // context.md written
+    const content = fs.readFileSync(path.join(d.workspace, 'context.md'), 'utf8');
+    assert.ok(content.includes('SUCCESS'));
+    d.stop();
+  });
+
+  test('failed claude exit emits fail', () => {
+    const d = makeDaemon();
+    d.start();
+    const failEvents = [];
+    d.on('fail', e => failEvents.push(e));
+
+    d.state = DaemonState.ACTIVE;
+    d.currentTask = { component: 'broken', prompt: 'fail' };
+
+    d._handleClaudeExit(1, null, '', 'error output');
+
+    assert.strictEqual(d.state, DaemonState.IDLE);
+    assert.strictEqual(failEvents.length, 1);
+    assert.strictEqual(failEvents[0].success, false);
+    assert.strictEqual(failEvents[0].exitCode, 1);
+    d.stop();
+  });
+
+  test('claude spawn error sets crashed state', () => {
+    const d = makeDaemon();
+    d.start();
+    const crashEvents = [];
+    d.on('crashed', e => crashEvents.push(e));
+
+    d.state = DaemonState.ACTIVE;
+    d.currentTask = { component: 'broken' };
+
+    d._handleClaudeError(new Error('command not found'));
+
+    assert.strictEqual(d.state, DaemonState.CRASHED);
+    assert.strictEqual(crashEvents.length, 1);
+    assert.ok(crashEvents[0].error.includes('command not found'));
+
+    // context.md has crash info
+    const content = fs.readFileSync(path.join(d.workspace, 'context.md'), 'utf8');
+    assert.ok(content.includes('Crash'));
+    d.stop();
+  });
+
+  test('idle daemon only sends heartbeats', () => {
+    const d = makeDaemon();
+    // Verify no claim/output/done/fail emissions from an idle daemon
+    // that receives non-matching messages
+    const badEvents = [];
+    d.on('output', e => badEvents.push(e));
+    d.on('done', e => badEvents.push(e));
+    d.on('fail', e => badEvents.push(e));
+    d.on('promoted', e => badEvents.push(e));
+
+    d.start();
+    d.handleMessage({ type: 'MSG', content: 'hello' });
+    d.handleMessage({ type: 'UNKNOWN', data: 'noise' });
+
+    assert.strictEqual(badEvents.length, 0);
+    d.stop();
+  });
+
+  test('info returns current state', () => {
+    const d = makeDaemon({ role: 'auditor' });
+    d.start();
+
+    const info = d.info();
+    assert.strictEqual(info.agentId, d.agentId);
+    assert.strictEqual(info.role, 'auditor');
+    assert.strictEqual(info.state, DaemonState.IDLE);
+    assert.strictEqual(info.currentTask, null);
+    assert.strictEqual(info.hasClaude, false);
+    d.stop();
+  });
+
+  test('stop cleans up timers', () => {
+    const d = makeDaemon({ heartbeatIntervalMs: 50 });
+    d.start();
+    assert.ok(d._heartbeatTimer);
+
+    d.stop();
+    assert.strictEqual(d._heartbeatTimer, null);
+    assert.strictEqual(d.state, DaemonState.IDLE);
+  });
+});