@oni.bot/core

The graph execution engine for agent swarms — build single agents or orchestrate multi-agent systems in TypeScript. Zero dependencies. Full TypeScript generics. Pregel-based superstep engine. 7 swarm templates.

Part of the ONI Platform (Open Neural Infrastructure).

What It Is

@oni.bot/core is a graph execution framework in TypeScript with production-ready swarm orchestration. Build single agents or multi-agent swarms with:

• State management — typed channels with pluggable reducers (lastValue, appendList, mergeObject, ephemeralValue)
• Graph execution — Pregel superstep model with parallel node execution, fan-out/fan-in, map-reduce
• 5 stream modes — values, updates, debug, messages (token-level), and custom events
• Checkpointing — Memory, SQLite, PostgreSQL, or custom backends with time travel and fork
• Human-in-the-loop — compile-time interrupts + runtime interrupt() with resume, typed input, approval, selection
• Messages — smart reducer with deduplication, RemoveMessage, UpdateMessage, filtering, trimming
• Cross-thread Store — namespaced KV store with semantic search for agent long-term memory
• Runtime context — getConfig(), getStore(), getStreamWriter() via AsyncLocalStorage
• Swarm orchestration — 7 swarm templates: hierarchical, fan-out, pipeline, peer-network, map-reduce, debate, hierarchical-mesh
• Functional API — task(), entrypoint(), pipe(), branch() as alternatives to the builder pattern
• Prebuilt agents — createReactAgent() with bring-your-own LLM
• Injected tools — tools that auto-receive state + store from runtime context
• Graph inspection — topology descriptors, Mermaid diagrams, cycle detection

Installation

npm install @oni.bot/core

Optional peer dependencies:

npm install better-sqlite3          # for SqliteCheckpointer
npm install pg                      # for PostgresCheckpointer

Quick Start

Minimal graph

import { StateGraph, START, END, lastValue, appendList } from "@oni.bot/core";

type MyState = { query: string; answer: string; log: string[] };

const graph = new StateGraph<MyState>({
  channels: {
    query:  lastValue(() => ""),
    answer: lastValue(() => ""),
    log:    appendList(() => []),
  },
});

graph.addNode("agent", async (state) => {
  return { answer: `Response to: ${state.query}`, log: ["agent ran"] };
});

graph.addEdge(START, "agent");
graph.addEdge("agent", END);

const app = graph.compile();
const result = await app.invoke({ query: "What is ONI?" });

Streaming

for await (const event of app.stream({ query: "hello" }, { streamMode: "updates" })) {
  console.log(event.node, event.data);
}

// Multiple modes simultaneously
for await (const evt of app.stream(input, { streamMode: ["values", "messages"] })) {
  if (evt.mode === "messages") process.stdout.write(evt.data.chunk);
}

Functional API

import { entrypoint, lastValue } from "@oni.bot/core";

const app = entrypoint(
  { channels: { query: lastValue(() => ""), answer: lastValue(() => "") } },
  async (state) => ({ answer: await myLLM(state.query) })
);

const result = await app.invoke({ query: "hello" });

Swarm Templates

Build multi-agent systems with pre-wired templates. Each template configures routing, coordination, and error handling automatically.

Hierarchical (Supervisor -> Workers)

import { SwarmGraph } from "@oni.bot/core/swarm";

const swarm = SwarmGraph.hierarchical<MyState>({
  supervisor: { model: myModel, strategy: "llm", maxRounds: 10 },
  agents: [researcher, writer, critic],
  onError: "fallback",
});

const app = swarm.compile();
const result = await app.invoke({ task: "Write a blog post about AI" });

All 7 Templates

See examples/swarm/ for complete runnable examples of each template.

Single Agent — No Swarm Required

The swarm layer is purely additive. If you just need one agent:

import { defineAgent } from "@oni.bot/core/agents";
import { anthropic } from "@oni.bot/core/models";

const agent = defineAgent({
  name: "assistant",
  model: anthropic("claude-sonnet-4-6"),
  tools: [webSearch],
  systemPrompt: "You are a helpful assistant.",
});

const result = await agent.invoke({ messages: [{ role: "user", content: "Hello!" }] });

Entry points at every level: ONIModel -> defineAgent() -> StateGraph -> SwarmGraph.

Features at a Glance

Core Concepts

Channels

Every state field has a channel — a reducer + default factory that controls how concurrent updates merge.

import { lastValue, appendList, mergeObject, ephemeralValue } from "@oni.bot/core";

const channels = {
  query:    lastValue(() => ""),          // last write wins
  messages: appendList(() => []),         // arrays concatenate
  context:  mergeObject(() => ({})),      // shallow merge
  scratch:  ephemeralValue(() => null),   // resets each superstep
};

Nodes, edges, compile

graph.addNode("agent", async (state, config?) => {
  return { answer: "partial update" };  // or Command, or void
});

graph.addEdge(START, "agent");
graph.addConditionalEdges("agent", (state) => state.done ? END : "tools");

const app = graph.compile({ checkpointer, store });

Invoke / Stream / Batch

const result  = await app.invoke(input, { threadId: "t1" });
const stream  = app.stream(input, { streamMode: "updates" });
const results = await app.batch([input1, input2]);

For the full progressive tutorial, see docs/GUIDE.md.

Sub-module Exports

Tree-shakeable sub-module imports for bundle optimization:

Architecture

@oni.bot/core v0.6.0
├── StateGraph / MessageGraph     ← fluent graph builder
│   ├── addNode / addSubgraph     ← nodes are async functions or compiled skeletons
│   ├── addEdge / addConditional  ← static + dynamic routing
│   └── compile()
│       └── ONIPregelRunner       ← superstep execution engine
│           ├── parallel node execution (Promise.all per superstep)
│           ├── channel reducers (state merging)
│           ├── edge resolution + Command routing
│           ├── Send API (dynamic fan-out)
│           ├── checkpointing (Memory / SQLite / Postgres / custom)
│           ├── interrupt handling (boundary + in-node)
│           ├── retry engine (exponential backoff)
│           ├── runtime context (AsyncLocalStorage)
│           └── stream writer (tokens + custom events + messages)
│
├── Messages         ← smart reducer, dedup, RemoveMessage, UpdateMessage
├── HITL             ← interrupt(), getUserInput, sessions, resume
├── Store            ← BaseStore, InMemoryStore, NamespacedStore, AgentMemoryStore
├── Swarm            ← SwarmGraph (7 templates), Supervisor, Handoff, AgentPool, coordination
│   ├── Templates    ← hierarchical, fanOut, pipeline, peerNetwork, mapReduce, debate, hierarchicalMesh
│   ├── Coordination ← RequestReplyBroker, PubSub (lazy auto-wired)
│   └── Retry        ← retry-then-fallback error recovery
├── Functional       ← task, entrypoint, pipe, branch
├── Prebuilt         ← createReactAgent, createToolNode, toolsCondition
├── Inspect          ← graph descriptors, Mermaid, cycle detection
├── Injected Tools   ← createInjectedTool (state + store auto-injected)
├── Stream Events    ← streamEvents v2 protocol
└── Errors           ← ONIError hierarchy, ONIInterrupt

ONI Platform

@oni.bot/core is the foundation layer. Other ONI packages build on top:

Documentation

• Developer Guide — Progressive tutorial from zero to advanced (19 sections)
• API Reference — Complete reference for all 116+ public exports
• Examples — 30+ runnable example files covering every feature

License

MIT — ONI Platform