events-plugins.md

Events & Plugins API

Event system and plugin management.

EventEmitter

import { EventEmitter } from 'agentforge';

const events = new EventEmitter();

Methods

on()

Subscribe to an event:

on<E extends EventName>(event: E, listener: EventListener<E>): () => void

Returns an unsubscribe function.

once()

Subscribe once:

once<E extends EventName>(event: E, listener: EventListener<E>): () => void

off()

Unsubscribe:

off<E extends EventName>(event: E, listener: EventListener<E>): void

emit()

Emit an event:

async emit<E extends EventName>(event: E, payload: EventPayload<E>): Promise<void>

removeAllListeners()

Remove all listeners:

removeAllListeners(event?: EventName): void

listenerCount()

Get listener count:

listenerCount(event: EventName): number

eventNames()

Get all events with listeners:

eventNames(): EventName[]

Event Types

interface AgentEvents {
  'request:start': { messages: Message[]; timestamp: number };
  'request:end': { response: CompletionResponse; durationMs: number; timestamp: number };
  'request:error': { error: Error; timestamp: number };
  'tool:start': { toolCall: ToolCall; timestamp: number };
  'tool:end': { toolCall: ToolCall; result: ToolResult; durationMs: number; timestamp: number };
  'tool:error': { toolCall: ToolCall; error: Error; timestamp: number };
  'stream:chunk': { content: string; timestamp: number };
  'stream:end': { fullContent: string; timestamp: number };
  'memory:trim': { before: number; after: number; strategy: string; timestamp: number };
  'agent:start': { input: string | Message[]; timestamp: number };
  'agent:end': { iterations: number; durationMs: number; timestamp: number };
  'plugin:event': { pluginName: string; eventName: string; data: unknown; timestamp: number };
}

globalEventBus

Shared global event bus:

import { globalEventBus } from 'agentforge';

globalEventBus.on('request:end', handler);

waitForEvent()

Wait for an event:

import { waitForEvent } from 'agentforge';

const payload = await waitForEvent(emitter, 'request:end', timeoutMs?);

eventIterator()

Create async iterator from events:

import { eventIterator } from 'agentforge';

for await (const event of eventIterator(emitter, 'tool:start')) {
  // Handle each event
}

---

PluginManager

import { PluginManager, EventEmitter, Agent } from 'agentforge';

const manager = new PluginManager(agent: Agent, events: EventEmitter);

Methods

register()

async register(plugin: Plugin): Promise<void>

unregister()

async unregister(name: string): Promise<void>

get()

get(name: string): Plugin | undefined

has()

has(name: string): boolean

getAll()

getAll(): Plugin[]

getContext()

getContext(name: string): PluginContext | undefined

Plugin Interface

interface Plugin {
  metadata: PluginMetadata;
  onRegister?: (context: PluginContext) => void | Promise<void>;
  onUnregister?: (context: PluginContext) => void | Promise<void>;
  tools?: Tool[];
  middleware?: Middleware[];
  events?: PluginEventHandlers;
}

interface PluginMetadata {
  name: string;
  version: string;
  description?: string;
  author?: string;
  dependencies?: string[];
}

interface PluginContext {
  agent: Agent;
  events: EventEmitter;
  storage: Map<string, unknown>;
  logger: PluginLogger;
}

definePlugin()

import { definePlugin } from 'agentforge';

const myPlugin = definePlugin({
  metadata: { name: 'my-plugin', version: '1.0.0' },
  onRegister: (ctx) => {},
  tools: [],
  events: {},
});

Built-in Plugins

analyticsPlugin

import { analyticsPlugin } from 'agentforge';

telemetryPlugin

import { telemetryPlugin } from 'agentforge';