npm package: @mosesaic/core
Description: Mosesaic TypeScript core — actor runtime, message bus, agent lifecycle
Latest version: 0.1.1

# @mosesaic/core

**TypeScript actor runtime for the Mosesaic agent framework.**

```bash
npm install @mosesaic/core
```

---

## Quick Start

```typescript
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)`

```typescript
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`

```typescript
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:
```typescript
{
  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:

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

See the [main README](https://github.com/your-org/mosesaic) for the full feature set including LLM routing, MCP tool integration, workflow DSL, REST API server, and CLI.