Event System

Overview

Armament uses a lightweight global event bus for internal communication between components. The bus supports on() subscription and emit() dispatch.

Basic Usage

import { getGlobalEventBus } from 'armament/app';

const bus = getGlobalEventBus();

// Subscribe
const unsub = bus.on((event) => {
  console.log(event);
});

// Emit
bus.emit({ type: 'agent:spawned', agent: { id: 'agent-01' } });

// Unsubscribe
unsub();

Event Types

Events are plain objects with a type field. The following event types are used internally:

Event TypePayloadWhen
stream:start{ agent, model }LLM response begins
stream:token{ agent, token }Each token received
stream:end{ agent, result }Response complete
stream:error{ agent, error }Stream failed
agent:spawned{ agent }New agent created
agent:complete{ agent, result }Task finished
agent:error{ agent, error }Agent error
agent:killed{ agent, reason }Agent terminated
permission:requested{ action, path }Approval needed
permission:granted{ action, path }User approved
permission:denied{ action, path }User denied
budget:update{ used, limit }Spend changed
session:phase{ from, to }Phase transition

Error Isolation

Listener errors are caught and don’t crash the bus:

bus.on(() => { throw new Error('bug'); });
bus.on(() => { /* This still runs */ });

Planned Enhancements

  • Wildcard pattern subscriptions (agent:*)
  • waitFor() promise-based event waiting
  • Event history/retention for debugging
  • Typed event payloads
  • Filtered views (/events agent)