git:20260323.178cb00 to git:20260725.c9691fc

- # Event Bus Skill

-

- ## Version

- **Version:** 1.0.0

- **Status:** OPERATIONAL

-

- ## Overview

- Event Bus provides a centralized event-driven communication system for agent coordination, system events, and lifecycle tracking. Built on the QEEventBus architecture, it enables decoupled, asynchronous messaging between agents and system components.

-

- ## Features

- - Event Publishing and Subscription

- - Agent Lifecycle Tracking

- - Event Filtering and Statistics

- - Type-Safe Event Handling

- - WASM JSON Integration (Placeholder)

-

- ## Core Components

-

- ### 1. Event Router and Dispatcher

- The Event Bus uses a pub/sub architecture with the following key components:

-

- **Event Emitter**: Core EventBus class from `.claude/core/cfn-event-bus.js`

- - `emit(event, data)` - Publish an event

- - `on(event, handler)` - Subscribe to an event

- - `once(event, handler)` - Subscribe to one-time event

- - `off(event, handler)` - Unsubscribe from event

- - `waitFor(event, timeoutMs)` - Async wait for event

-

- **Event Statistics**:

- - `getEventStats()` - Get event metrics (count, last emitted)

- - `resetStats()` - Clear event statistics

-

- ### 2. Agent Lifecycle Events

- Track agent state transitions across the execution lifecycle:

-

- **Lifecycle Stages**:

- - `spawn` - Agent created and initialized

- - `complete` - Agent successfully finished task

- - `fail` - Agent encountered critical error

- - `timeout` - Agent exceeded execution time limit

-

- **Lifecycle Metadata**:

- ```json

- {

- "agentId": "backend-dev-1",

- "taskId": "auth-system",

- "timestamp": 1729311234,

- "metadata": {

- "reason": "Task completed successfully",

- "confidence": 0.92,

- "duration": 45000

- }

- }

- ```

-

- ### 3. System Events

- Pre-defined system-wide events for cross-agent coordination:

-

- **Common System Events**:

- - `agent:spawned` - New agent created

- - `agent:completed` - Agent finished

- - `agent:failed` - Agent error

- - `task:started` - Task execution begins

- - `task:completed` - Task finished

- - `consensus:reached` - CFN Loop consensus achieved

- - `validation:passed` - Validation gate passed

- - `validation:failed` - Validation gate failed

-

- ### 4. WASM JSON Integration

- **Status:** Placeholder for future implementation

-

- Future integration with WASM-based JSON processing for:

- - High-performance event serialization

- - Schema validation

- - Binary event encoding

- - Cross-platform event format

-

- ## Agent Integration Examples

-

- ### 1. Publishing Events

-

- #### Basic Event Publishing

- ```bash

- # Publish task completion event

- ./.claude/skills/event-bus/invoke-event-publish.sh \

- --topic "task:completed" \

- --payload '{

- "taskId": "auth-system",

- "agentId": "backend-dev-1",

- "confidence": 0.92,

- "timestamp": '$(date +%s)'

- }'

- ```

-

- #### Publishing with Trace ID

- ```bash

- # Publish with distributed tracing

- ./.claude/skills/event-bus/invoke-event-publish.sh \

- --topic "validation:passed" \

- --payload '{

- "taskId": "deploy-feature",

- "validator": "security-agent",

- "checks": ["input-validation", "auth-check", "rate-limiting"]

- }' \

- --trace-id "trace-123-abc"

- ```

-

- ### 2. Subscribing to Events

-

- #### Subscribe to Single Event

- ```bash

- # Subscribe to agent completion events

- ./.claude/skills/event-bus/invoke-event-subscribe.sh \

- --topic "agent:completed" \

- --callback "handle_agent_complete"

-

- # Callback function definition

- handle_agent_complete() {

- local event_data="$1"

- echo "Agent completed: $(echo "$event_data" | jq -r '.agentId')"

- # Process event...

- }

- ```

-

- #### Filtered Event Subscription

- ```bash

- # Subscribe only to high-confidence completions

- ./.claude/skills/event-bus/invoke-event-subscribe.sh \

- --topic "agent:completed" \

- --filter 'select(.confidence >= 0.90)' \

- --callback "handle_high_confidence_completion"

- ```

-

- ### 3. Agent Lifecycle Tracking

-

- #### Track Agent Spawn

- ```bash

- # Record agent creation

- ./.claude/skills/event-bus/invoke-lifecycle-track.sh \

- --agent-id "backend-dev-1" \

- --event "spawn" \

- --metadata '{

- "taskId": "auth-system",

- "role": "backend-developer",

- "timestamp": '$(date +%s)'

- }'

- ```

-

- #### Track Agent Completion

- ```bash

- # Record successful completion

- ./.claude/skills/event-bus/invoke-lifecycle-track.sh \

- --agent-id "backend-dev-1" \

- --event "complete" \

- --metadata '{

- "taskId": "auth-system",

- "confidence": 0.92,

- "duration": 45000,

- "filesModified": 12

- }'

- ```

-

- #### Track Agent Failure

- ```bash

- # Record agent failure

- ./.claude/skills/event-bus/invoke-lifecycle-track.sh \

- --agent-id "backend-dev-1" \

- --event "fail" \

- --metadata '{

- "taskId": "auth-system",

- "error": "TypeScript compilation failed",

- "stage": "post-edit-validation",

- "timestamp": '$(date +%s)'

- }'

- ```

-

- #### Track Agent Timeout

- ```bash

- # Record timeout

- ./.claude/skills/event-bus/invoke-lifecycle-track.sh \

- --agent-id "backend-dev-1" \

- --event "timeout" \

- --metadata '{

- "taskId": "auth-system",

- "timeLimit": 300000,

- "elapsed": 305000

- }'

- ```

-

- ## Integration Patterns

-

- ### Pattern 1: Event-Driven Coordination

- Use events to coordinate agent workflows without tight coupling:

-

- ```bash

- # Agent A publishes completion

- ./.claude/skills/event-bus/invoke-event-publish.sh \

- --topic "code:ready" \

- --payload '{"taskId": "auth", "status": "ready-for-review"}'

-

- # Agent B subscribes and auto-triggers

- ./.claude/skills/event-bus/invoke-event-subscribe.sh \

- --topic "code:ready" \

- --callback "start_review_process"

- ```

-

- ### Pattern 2: Lifecycle Monitoring

- Track agent progress across CFN Loop iterations:

-

- ```bash

- # Iteration 1 start

- ./.claude/skills/event-bus/invoke-lifecycle-track.sh \

- --agent-id "coder-1" \

- --event "spawn" \

- --metadata '{"iteration": 1, "taskId": "auth"}'

-

- # Iteration 1 complete

- ./.claude/skills/event-bus/invoke-lifecycle-track.sh \

- --agent-id "coder-1" \

- --event "complete" \

- --metadata '{"iteration": 1, "confidence": 0.75}'

-

- # Iteration 2 start (after feedback)

- ./.claude/skills/event-bus/invoke-lifecycle-track.sh \

- --agent-id "coder-1" \

- --event "spawn" \

- --metadata '{"iteration": 2, "taskId": "auth"}'

- ```

-

- ### Pattern 3: Consensus Broadcasting

- Broadcast consensus events to all waiting agents:

-

- ```bash

- # Coordinator publishes consensus

- ./.claude/skills/event-bus/invoke-event-publish.sh \

- --topic "consensus:reached" \

- --payload '{

- "taskId": "auth-system",

- "avgConfidence": 0.93,

- "iteration": 3,

- "agents": ["coder-1", "reviewer-1", "tester-1"]

- }'

-

- # All agents subscribe and receive notification

- ./.claude/skills/event-bus/invoke-event-subscribe.sh \

- --topic "consensus:reached" \

- --callback "handle_consensus"

- ```

-

- ## Event Schema Guidelines

-

- ### Standard Event Format

- All events should follow this structure:

-

- ```json

- {

- "eventType": "agent:completed",

- "timestamp": 1729311234,

- "source": {

- "agentId": "backend-dev-1",

- "taskId": "auth-system"

- },

- "payload": {

- "confidence": 0.92,

- "metrics": {

- "duration": 45000,

- "filesModified": 12

- }

- },

- "traceId": "trace-123-abc"

- }

- ```

-

- ### Lifecycle Event Format

- ```json

- {

- "eventType": "lifecycle",

- "stage": "complete",

- "agentId": "backend-dev-1",

- "taskId": "auth-system",

- "timestamp": 1729311234,

- "metadata": {

- "confidence": 0.92,

- "duration": 45000

- }

- }

- ```

-

- ## Available Invoke Scripts

-

- ### 1. invoke-event-publish.sh

- Publish events to the event bus.

-

- **Arguments**:

- - `--topic` (required) - Event topic/channel

- - `--payload` (required) - JSON event payload

- - `--trace-id` (optional) - Distributed tracing ID

-

- **Returns**: JSON with publish status and event ID

-

- ### 2. invoke-event-subscribe.sh

- Subscribe to event topics.

-

- **Arguments**:

- - `--topic` (required) - Event topic to subscribe to

- - `--callback` (required) - Callback function name

- - `--filter` (optional) - JQ filter expression

-

- **Returns**: Subscription ID

-

- ### 3. invoke-lifecycle-track.sh

- Track agent lifecycle events.

-

- **Arguments**:

- - `--agent-id` (required) - Agent identifier

- - `--event` (required) - Lifecycle event (spawn|complete|fail|timeout)

- - `--metadata` (required) - JSON metadata object

-

- **Returns**: JSON with tracking confirmation

-

- ### 4. test-event-bus.sh

- Comprehensive test suite for Event Bus functionality.

-

- **Tests**:

- - Event publishing

- - Event subscription

- - Lifecycle tracking

- - Event filtering

- - Statistics collection

-

- ## Event Bus vs Redis Coordination

-

- **Use Event Bus When**:

- - Decoupled communication needed

- - Multiple subscribers per event

- - Event history/statistics required

- - System-wide notifications

-

- **Use Redis Coordination When**:

- - Agent synchronization required

- - Blocking operations needed (BLPOP)

- - CFN Loop dependencies

- - Consensus collection

-

- **Combined Usage**:

- Use both for comprehensive coordination:

- ```bash

- # Redis: Block until agent ready

- ./.claude/skills/redis-coordination/invoke-waiting-mode.sh enter \

- --task-id "auth" --agent-id "coder-1" --context "waiting"

-

- # Event Bus: Notify all watchers

- ./.claude/skills/event-bus/invoke-event-publish.sh \

- --topic "agent:waiting" \

- --payload '{"agentId": "coder-1", "status": "blocked"}'

- ```

-

- ## Future Enhancements

-

- ### WASM JSON Processing

- Future implementation will include:

- - Binary event encoding via WASM

- - Schema validation at native speed

- - Cross-language event serialization

- - Performance optimization for high-throughput scenarios

-

- ### Advanced Features (Roadmap)

- - Event replay and time-travel debugging

- - Persistent event store integration

- - Event sourcing for agent state

- - Real-time event streaming API

-

- ## Configuration

-

- Event Bus behavior can be configured via:

- - `EVENTBUS_DEBUG=true` - Enable verbose event logging

- - `EVENTBUS_STATS=true` - Collect detailed statistics

- - `EVENTBUS_MAX_LISTENERS=100` - Set max listeners per event

-

- ## Troubleshooting

-

- ### High Memory Usage

- ```bash

- # Reset event statistics to free memory

- node -e "

- const { eventBus } = require('./.claude/core/cfn-event-bus.js');

- eventBus.resetStats();

- console.log('Stats reset');

- "

- ```

-

- ### Event Not Received

- 1. Verify topic name matches exactly

- 2. Check callback function is defined

- 3. Enable debug mode: `EVENTBUS_DEBUG=true`

- 4. Check event statistics for publish confirmation

-

- ### Lifecycle Events Missing

- 1. Ensure invoke-lifecycle-track.sh is called

- 2. Verify JSON metadata is valid

- 3. Check agent-id matches expected format

-

- ## Related Skills

- - **Redis Coordination** (`.claude/skills/redis-coordination/SKILL.md`) - Blocking coordination

- - **Agent Spawning** (`.claude/skills/agent-spawning/SKILL.md`) - Agent creation

- - **CFN Loop Validation** (`.claude/skills/cfn-loop-validation/SKILL.md`) - Consensus loops

-

- ## Support

- For issues or questions:

- 1. Check test suite: `.claude/skills/event-bus/test-event-bus.sh`

- 2. Review event statistics via `getEventStats()`

- 3. Enable debug logging with `EVENTBUS_DEBUG=true`