@codmir/events

@codmir/events-sdk

Event system SDK for AI-to-AI task scheduling and inter-service communication.

Features

• Event Bus Client - Publish/subscribe to events across services
• AI Task Scheduler - Schedule and delegate tasks between AI agents
• Agent Lifecycle - Register, heartbeat, and manage AI agents
• NestJS Integration - Ready-to-use modules and decorators

Installation

pnpm add @codmir/events-sdk

Quick Start

Event Publishing

import { createEventClient, EventTypes } from "@codmir/events-sdk";

const client = createEventClient({
  serviceUrl: "http://events:3009",
  agentId: "my-service",
  projectId: "project-123",
  organizationId: "org-456",
});

// Publish an event
await client.publish({
  type: EventTypes.CODE_GENERATED,
  data: {
    files: ["src/index.ts"],
    linesAdded: 50,
  },
});

// Subscribe to events
await client.subscribe(["task.completed", "task.failed"], (event) => {
  console.log("Received event:", event);
});

AI Task Scheduling

Coordinator Agent (Schedules Tasks)

import { createTaskScheduler, TaskTypes } from "@codmir/events-sdk/scheduler";

const coordinator = createTaskScheduler({
  serviceUrl: "http://events:3009",
  projectId: "project-123",
  organizationId: "org-456",
});

// Register as coordinator
await coordinator.registerAgent({
  name: "Task Coordinator",
  role: "coordinator",
  capabilities: ["planning", "delegation", "orchestration"],
});

// Delegate code writing to a coder agent
const codeTask = await coordinator.requestCode({
  title: "Implement user authentication",
  description: "Create login/logout functionality with JWT",
  input: {
    spec: "Use bcrypt for password hashing...",
    files: ["src/auth/"],
  },
  priority: "high",
});

// Wait for result
const result = await coordinator.waitForTask(codeTask.id, 120000);
console.log("Code written:", result.output);

// Or delegate to specific roles
const reviewTask = await coordinator.delegateToRole("reviewer", {
  type: TaskTypes.CODE_REVIEW,
  title: "Review authentication code",
  input: { code: result.output?.code },
  priority: "medium",
});

Worker Agent (Processes Tasks)

import { createTaskScheduler, TaskTypes } from "@codmir/events-sdk/scheduler";

const coder = createTaskScheduler({
  serviceUrl: "http://events:3009",
  projectId: "project-123",
  organizationId: "org-456",
});

// Register as coder agent
await coder.registerAgent({
  name: "Coder AI",
  role: "coder",
  capabilities: ["typescript", "nodejs", "react", "nextjs"],
});

// Start processing tasks
await coder.startProcessing(async (task) => {
  console.log(`Processing task: ${task.title}`);

  // Report progress
  await coder.reportProgress(task.id, {
    percentage: 50,
    message: "Generating code...",
  });

  // Do the work...
  const generatedCode = await generateCode(task.input);

  // Return result
  return {
    status: "completed",
    output: {
      code: generatedCode,
      filesCreated: ["src/auth/login.ts"],
    },
    metrics: {
      durationMs: 5000,
      tokensUsed: 2000,
    },
  };
});

NestJS Integration

import { Module } from "@nestjs/common";
import {
  EventsModuleDefinition,
  SchedulerModuleDefinition,
  OnEvent,
  OnTask,
} from "@codmir/events-sdk/nestjs";

@Module({
  imports: [
    EventsModuleDefinition.forRoot({
      serviceUrl: process.env.EVENTS_SERVICE_URL,
      global: true,
    }),
    SchedulerModuleDefinition.forRoot({
      serviceUrl: process.env.EVENTS_SERVICE_URL,
      autoRegister: true,
      agentConfig: {
        name: "Review Agent",
        role: "reviewer",
        capabilities: ["code-review", "security-audit"],
      },
      global: true,
    }),
  ],
})
export class AppModule {}

// Use decorators for handlers
@Injectable()
export class ReviewService {
  @OnEvent("code.generated")
  async handleCodeGenerated(event: Event) {
    // Auto-trigger review when code is generated
  }

  @OnTask("code.review")
  async handleReviewTask(task: Task): Promise<TaskResult> {
    // Process review task
    return {
      status: "completed",
      output: { approved: true, comments: [] },
    };
  }
}

Agent Roles

Role	Description
coordinator	Orchestrates other agents, breaks down tasks
coder	Writes and modifies code
reviewer	Reviews code and provides feedback
tester	Creates and runs tests
documenter	Writes documentation
researcher	Researches and gathers information
planner	Creates plans and architecture
debugger	Debugs and fixes issues
security	Security analysis and fixes
devops	Infrastructure and deployment

Task Types

import { TaskTypes } from "@codmir/events-sdk";

// Code tasks
TaskTypes.CODE_WRITE; // Write new code
TaskTypes.CODE_REVIEW; // Review code
TaskTypes.CODE_REFACTOR; // Refactor existing code
TaskTypes.CODE_DEBUG; // Debug and fix issues
TaskTypes.CODE_TEST; // Create tests
TaskTypes.CODE_DOCUMENT; // Document code

// Research tasks
TaskTypes.RESEARCH_CODEBASE; // Research existing code
TaskTypes.RESEARCH_DOCUMENTATION; // Research docs
TaskTypes.RESEARCH_BEST_PRACTICES; // Research best practices

// Planning tasks
TaskTypes.PLAN_FEATURE; // Plan a feature
TaskTypes.PLAN_ARCHITECTURE; // Plan architecture
TaskTypes.PLAN_MIGRATION; // Plan migration

// DevOps tasks
TaskTypes.DEVOPS_DEPLOY; // Deploy application
TaskTypes.DEVOPS_MONITOR; // Monitor systems
TaskTypes.DEVOPS_SCALE; // Scale infrastructure

// Security tasks
TaskTypes.SECURITY_AUDIT; // Security audit
TaskTypes.SECURITY_FIX; // Fix security issues

Event Types

import { EventTypes } from "@codmir/events-sdk";

// Agent lifecycle
EventTypes.AGENT_REGISTERED;
EventTypes.AGENT_STATUS_CHANGED;
EventTypes.AGENT_HEARTBEAT;

// Task lifecycle
EventTypes.TASK_CREATED;
EventTypes.TASK_ASSIGNED;
EventTypes.TASK_STARTED;
EventTypes.TASK_PROGRESS;
EventTypes.TASK_COMPLETED;
EventTypes.TASK_FAILED;

// AI communication
EventTypes.AI_MESSAGE;
EventTypes.AI_REQUEST;
EventTypes.AI_RESPONSE;
EventTypes.AI_DELEGATION;

// Code events
EventTypes.CODE_GENERATED;
EventTypes.CODE_REVIEWED;
EventTypes.CODE_TESTED;
EventTypes.CODE_DEPLOYED;

Environment Variables

EVENTS_SERVICE_URL=http://events:3009
EVENTS_API_KEY=your-api-key
AGENT_ID=unique-agent-id
PROJECT_ID=project-123
ORGANIZATION_ID=org-456
TASK_POLLING_INTERVAL=2000
AGENT_HEARTBEAT_INTERVAL=30000

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Events Service (apps/events)              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  Event Bus  │  │  Scheduler  │  │   Agents    │         │
│  │  - Publish  │  │  - Queue    │  │  - Register │         │
│  │  - Subscribe│  │  - Assign   │  │  - Status   │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│                         │                                    │
│                         ▼                                    │
│  ┌─────────────────────────────────────────────────┐       │
│  │              Redis (Task Queues)                 │       │
│  │  - Role-based queues                            │       │
│  │  - Priority ordering                            │       │
│  └─────────────────────────────────────────────────┘       │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              │               │               │
              ▼               ▼               ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│  Coordinator AI  │ │    Coder AI      │ │   Reviewer AI    │
│  (schedules)     │ │  (writes code)   │ │ (reviews code)   │
└──────────────────┘ └──────────────────┘ └──────────────────┘

License

MIT