@9d9/pulsemcp-core

Core utilities for PulseMCP — Model Context Protocol automation framework

Why PulseMCP?

Building AI agent systems? You need reliable primitives. PulseMCP provides:

• Type-safe error handling — Result pattern instead of try/catch everywhere
• Resilient async — Retry with exponential backoff, timeouts, promises
• Event-driven architecture — Lightweight EventEmitter for agent coordination
• Task management — Track task lifecycle with auto-generated IDs
• Zero dependencies — Pure TypeScript, tiny bundle

Install

npm install @9d9/pulsemcp-core

Quick Start

import { ok, err, retry, withTimeout, EventEmitter, createTask, DefaultLogger } from "@9d9/pulsemcp-core";

// Type-safe error handling
function divide(a: number, b: number) {
  if (b === 0) return err("DIV_ZERO", "Cannot divide by zero");
  return ok(a / b);
}

const result = divide(10, 2);
if (result.ok) console.log(result.value); // 5

// Retry with exponential backoff
const data = await retry(() => fetchData(), {
  maxAttempts: 3,
  baseDelay: 1000,
  maxDelay: 30000,
});

// Timeout wrapper
const response = await withTimeout(fetch(url), 5000);

// Event system for agent coordination
const emitter = new EventEmitter();
emitter.on("task:complete", (data) => console.log("Done:", data));
emitter.emit("task:complete", { id: "123" });

// Task management
const task = createTask("process-data", { items: [1, 2, 3] });
// task.id → "task_m3x7kq_abc123"
// task.status → "pending"

// Logging
const logger = new DefaultLogger(LogLevel.Info);
logger.info("Server started on port 3000");

API Reference

Result Pattern

Function	Description
ok(value)	Create a success result
err(code, message, details?)	Create an error result

const result: Result<number> = ok(42);
const failure: Result<number> = err("NOT_FOUND", "Item not found");

Async Utilities

Function	Description
sleep(ms)	Promise-based delay
withTimeout(promise, ms)	Reject if promise doesn't resolve in time
retry(fn, opts?)	Retry with exponential backoff

// Retry options
interface RetryOptions {
  maxAttempts?: number;  // default: 3
  baseDelay?: number;    // default: 1000ms
  maxDelay?: number;     // default: 30000ms
}

Task Management

Function	Description
createTask(name, data?)	Create a new task with auto-generated ID
generateId(prefix?)	Generate unique IDs (e.g., pulse_m3x7kq_abc123)

const task = createTask("sync-database");
// { id: "task_...", name: "sync-database", status: "pending", createdAt: Date, updatedAt: Date }

EventEmitter

Lightweight pub/sub for agent coordination.

const emitter = new EventEmitter();
const unsubscribe = emitter.on("event", (data) => console.log(data));
emitter.emit("event", { foo: "bar" });
unsubscribe(); // Clean up

Logger

Method	Level
debug(msg, ...args)	Debug
info(msg, ...args)	Info
warn(msg, ...args)	Warn
error(msg, ...args)	Error

const logger = new DefaultLogger(LogLevel.Debug); // Show all levels

Utilities

Function	Description
validateNotNull(value, name)	Throw if null/undefined
formatDuration(ms)	Human-readable duration ("1.5s", "2m 30s")

Types

enum TaskStatus { Pending, Running, Completed, Failed, Cancelled }
enum LogLevel { Debug, Info, Warn, Error }

interface PulseMCPError { code: string; message: string; details?: unknown }
type Result<T> = { ok: true; value: T } | { ok: false; error: PulseMCPError }
interface Task<T> { id: string; name: string; status: TaskStatus; data?: T; createdAt: Date; updatedAt: Date }

Ecosystem

Package	Description
@9d9/pulsemcp-core	Core utilities (this package)
@9d9/openclaw-utils	OpenClaw plugin/skill utilities
@9d9/mcp-automation	MCP workflow automation

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT © 9d9 LLC