@mosesaic/core

TypeScript actor runtime for the Mosesaic agent framework.

npm install @mosesaic/core

Quick Start

import { defineAgent, AgentRuntime } from "@mosesaic/core";

// Define agents
const echo = defineAgent({ name: "echo" }, async (ctx) => {
  const msg = await ctx.receive();
  await ctx.send("upper", msg.payload);
});

const upper = defineAgent({ name: "upper" }, async (ctx) => {
  const msg = await ctx.receive();
  console.log(String(msg.payload).toUpperCase()); // "HELLO MOSESAIC"
});

// Wire up the runtime
const runtime = new AgentRuntime();
runtime.register(echo);
runtime.register(upper);

// Send a message and run until all agents finish
await runtime.sendExternal("echo", "hello mosesaic");
await runtime.runUntilComplete(5000);

// Inspect the full message history
console.log(runtime.eventLog);

API

defineAgent(opts, fn)

const myAgent = defineAgent({ name: "my-agent" }, async (ctx) => {
  const msg = await ctx.receive();     // wait for next message
  await ctx.send("other", "payload");  // send to another agent
  await ctx.checkpoint();              // pause/stop point
});

AgentRuntime

const runtime = new AgentRuntime();

runtime.register(myAgent);              // add agent
await runtime.sendExternal("name", p); // queue message before start
await runtime.runUntilComplete(ms);    // run until all agents exit
runtime.eventLog                        // all messages (readonly)

// Lifecycle (call during runtime.run())
runtime.pause("name");
runtime.resume("name");
runtime.stop("name");

AgentContext (ctx)

| Method | Description | |---|---| | ctx.receive() | Wait for next message in this agent's inbox | | ctx.send(to, payload) | Send a message to another agent | | ctx.reply(original, payload) | Reply, preserving trace_id | | ctx.checkpoint() | Cooperative pause/stop point | | ctx.isStopped | True after runtime.stop() was called |

Messages

Each message has:

{
  id: string;           // UUID
  type: "task" | "result" | "error" | "control";
  from_agent: string;
  to_agent: string;
  payload?: unknown;
  trace_id?: string;    // propagated across a call chain
  parent_message_id?: string;
  timestamp: string;    // ISO 8601
}

Concepts

Actor model — each agent runs concurrently in its own loop, communicating only via typed messages. No shared mutable state.

Event sourcing — every message is written to the event log before delivery. runtime.eventLog is always the complete history of what happened.

Lifecycle — pause() suspends at the next ctx.checkpoint(). stop() cancels execution. resume() unblocks a paused agent.

Trace IDs — messages sent by ctx.send() carry the agent's trace_id, making it easy to follow a request across multiple agents.

Python SDK

The full framework is available in Python with additional packages:

pip install mosesaic-core mosesaic-llm mosesaic-tools mosesaic-workflow mosesaic-mcp mosesaic-server

See the main README for the full feature set including LLM routing, MCP tool integration, workflow DSL, REST API server, and CLI.