@oni.bot/core 0.6.2 → 0.8.0

package/README.md

@@ -1,57 +1,48 @@
-# @oni.bot/core
+<p align="center">
+  <strong>@oni.bot/core</strong>
+</p>
 
-> 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.
+<h3 align="center">The graph execution engine for agent swarms.</h3>
 
-Part of the **ONI Platform** (Open Neural Infrastructure).
+<p align="center">
+  Production-grade orchestration with zero dependencies.
+</p>
 
----
-
-## 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
+<p align="center">
+  <a href="https://www.npmjs.com/package/@oni.bot/core"><img src="https://img.shields.io/npm/v/@oni.bot/core.svg" alt="npm version" /></a>
+  <a href="https://github.com/oni-bot/core/actions"><img src="https://img.shields.io/github/actions/workflow/status/oni-bot/core/ci.yml?label=tests" alt="tests" /></a>
+  <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="zero dependencies" />
+  <img src="https://img.shields.io/badge/TypeScript-strict-blue" alt="TypeScript strict" />
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License" /></a>
+</p>
 
 ---
 
-## Installation
+## Why ONI
 
-```bash
-npm install @oni.bot/core
-```
+Most agent frameworks make the easy things easy and the hard things impossible. You can spin up a chatbot in ten lines, but the moment you need four agents coordinating with retries, circuit breakers, and human approval gates, you're writing glue code from scratch.
 
-**Optional peer dependencies:**
+ONI was built for the hard things:
 
-```bash
-npm install better-sqlite3          # for SqliteCheckpointer
-npm install pg                      # for PostgresCheckpointer
-```
+- **Multi-agent orchestration is a first-class primitive.** Seven swarm templates ship out of the box -- hierarchical, fan-out, pipeline, peer-network, map-reduce, debate, and hierarchical-mesh. Pick one, plug in your agents, and go.
+- **Zero runtime dependencies.** The entire engine is self-contained TypeScript. No framework lock-in, no transitive supply-chain risk. Runs in Node, serverless functions, and edge runtimes without adaptation.
+- **Production-grade from day one.** Circuit breakers, node timeouts, dead letter queues, retry with exponential backoff, OpenTelemetry tracing, and checkpointing with time-travel debugging. These aren't afterthoughts -- they're wired into the execution engine.
+- **Type-safe end to end.** Full generics on state, channels, and node returns. TypeScript strict mode. If your graph compiles, it runs.
 
 ---
 
 ## Quick Start
 
-### Minimal graph
+```bash
+npm install @oni.bot/core
+```
 
 ```ts
 import { StateGraph, START, END, lastValue, appendList } from "@oni.bot/core";
 
-type MyState = { query: string; answer: string; log: string[] };
+type State = { query: string; answer: string; log: string[] };
 
-const graph = new StateGraph<MyState>({
+const graph = new StateGraph<State>({
   channels: {
     query:  lastValue(() => ""),
     answer: lastValue(() => ""),
@@ -59,250 +50,374 @@ const graph = new StateGraph<MyState>({
   },
 });
 
-graph.addNode("agent", async (state) => {
-  return { answer: `Response to: ${state.query}`, log: ["agent ran"] };
+graph.addNode("think", async (state) => {
+  return { answer: `Processed: ${state.query}`, log: ["think ran"] };
 });
 
-graph.addEdge(START, "agent");
-graph.addEdge("agent", END);
+graph.addEdge(START, "think");
+graph.addEdge("think", END);
 
 const app = graph.compile();
 const result = await app.invoke({ query: "What is ONI?" });
+console.log(result.answer); // "Processed: What is ONI?"
 ```
 
-### Streaming
+---
+
+## Multi-Agent Swarm
+
+Build coordinated agent teams with a single function call:
 
 ```ts
-for await (const event of app.stream({ query: "hello" }, { streamMode: "updates" })) {
-  console.log(event.node, event.data);
-}
+import { SwarmGraph } from "@oni.bot/core/swarm";
+import { defineAgent } from "@oni.bot/core/agents";
+import { anthropic } from "@oni.bot/core/models";
 
-// Multiple modes simultaneously
-for await (const evt of app.stream(input, { streamMode: ["values", "messages"] })) {
-  if (evt.mode === "messages") process.stdout.write(evt.data.chunk);
-}
+const researcher = defineAgent({
+  name: "researcher",
+  model: anthropic("claude-sonnet-4-6"),
+  systemPrompt: "You research topics thoroughly.",
+  tools: [webSearch],
+});
+
+const writer = defineAgent({
+  name: "writer",
+  model: anthropic("claude-sonnet-4-6"),
+  systemPrompt: "You write compelling content from research notes.",
+});
+
+const swarm = SwarmGraph.hierarchical({
+  supervisor: { model: anthropic("claude-sonnet-4-6"), strategy: "llm", maxRounds: 10 },
+  agents: [researcher, writer],
+});
+
+const app = swarm.compile();
+const result = await app.invoke({ task: "Write a technical brief on quantum error correction" });
 ```
 
-### Functional API
+No boilerplate routing, no manual state plumbing. The supervisor decides which agent runs next, results flow back through typed channels, and the swarm terminates when the task is complete.
 
-```ts
-import { entrypoint, lastValue } from "@oni.bot/core";
+---
 
-const app = entrypoint(
-  { channels: { query: lastValue(() => ""), answer: lastValue(() => "") } },
-  async (state) => ({ answer: await myLLM(state.query) })
-);
+## Features
 
-const result = await app.invoke({ query: "hello" });
-```
+| Category | Feature | Description |
+|---|---|---|
+| **Engine** | Pregel execution | Superstep-parallel graph engine with deterministic state merging |
+| | Typed channels | `lastValue`, `appendList`, `mergeObject`, `ephemeralValue` reducers |
+| | Command routing | State update + routing in a single return value |
+| | Send API | Dynamic fan-out to nodes with per-instance payloads |
+| | Subgraphs | Nested compiled graphs with `Command.PARENT` state bridging |
+| **Swarm** | 7 templates | Hierarchical, fan-out, pipeline, peer-network, map-reduce, debate, mesh |
+| | Supervisor | LLM-based or rule-based routing strategies |
+| | Handoff | Agent-to-agent delegation with context transfer |
+| | Coordination | `RequestReplyBroker`, `PubSub` for inter-agent messaging |
+| **Models** | 5 LLM adapters | Anthropic, OpenAI, Google, Ollama, OpenRouter |
+| | Unified interface | `ONIModel` with chat, streaming, and tool calling |
+| | Mock model | Deterministic test doubles with call history |
+| **Streaming** | 5 modes | `values`, `updates`, `debug`, `messages`, `custom` |
+| | Token streaming | Character-level LLM output via `messages` mode |
+| | Custom events | Emit named events from any node via `StreamWriter` |
+| | Multi-mode | Subscribe to multiple stream modes simultaneously |
+| **Reliability** | Circuit breakers | Automatic failure detection with configurable thresholds |
+| | Node timeouts | Per-node deadline enforcement |
+| | Dead letter queues | Capture and inspect failed executions |
+| | Retry + backoff | Configurable per-node retry with exponential backoff |
+| **Persistence** | Checkpointing | Memory, SQLite, PostgreSQL backends |
+| | Time travel | `getHistory`, `getStateAt`, `forkFrom` |
+| | Cross-thread store | Namespaced KV with semantic search for agent memory |
+| **HITL** | Interrupts | `interrupt()`, `getUserInput()`, `getUserApproval()` |
+| | Session management | Typed resume values, multi-step approval flows |
+| **Guardrails** | Budget tracking | Token and cost limits with automatic enforcement |
+| | Content filters | PII detection, topic filtering, custom validators |
+| | Permissions | Per-tool permission checks with audit logging |
+| | Audit log | Structured logging of all guardrail decisions |
+| **Observability** | OpenTelemetry | Zero-dep adapter -- bring your own tracer |
+| | Graph inspection | Topology descriptors, Mermaid diagrams, cycle detection |
+| **Testing** | `mockModel()` | Deterministic model stubs with call history tracking |
+| | `assertGraph()` | Structural assertions on graph topology |
+| | `createTestHarness()` | Pre-wired test runner with auto-checkpointing |
+| **API Styles** | Builder pattern | `StateGraph` + `addNode` + `addEdge` + `compile` |
+| | Functional | `task()`, `entrypoint()`, `pipe()`, `branch()` |
+| | Prebuilt | `createReactAgent()`, `defineAgent()` |
 
 ---
 
 ## Swarm Templates
 
-Build multi-agent systems with pre-wired templates. Each template configures routing, coordination, and error handling automatically.
+| Template | Pattern | When to use it |
+|---|---|---|
+| `SwarmGraph.hierarchical()` | Supervisor routes to workers | General multi-agent tasks with centralized control |
+| `SwarmGraph.fanOut()` | Parallel execution + aggregation | Independent subtasks that can run concurrently |
+| `SwarmGraph.pipeline()` | Sequential A -> B -> C chain | Ordered processing stages (ETL, content pipelines) |
+| `SwarmGraph.peerNetwork()` | Dynamic peer-to-peer handoff | Agents self-organize based on capabilities |
+| `SwarmGraph.mapReduce()` | Split -> Pool -> Reduce | Distributing N items across a worker pool |
+| `SwarmGraph.debate()` | Judge -> Debaters -> Consensus | Multi-perspective reasoning, red-teaming |
+| `SwarmGraph.hierarchicalMesh()` | Coordinator -> Team subgraphs | Nested teams with inter-team coordination |
 
-### Hierarchical (Supervisor -> Workers)
+Each template handles routing, error recovery, and termination automatically. See `examples/swarm/` for runnable examples.
 
-```ts
-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",
-});
+## Architecture
 
-const app = swarm.compile();
-const result = await app.invoke({ task: "Write a blog post about AI" });
+```
+@oni.bot/core v0.7.0
+
+                           +--------------------------+
+                           |      Your Application    |
+                           +--------------------------+
+                                       |
+                  +--------------------+--------------------+
+                  |                    |                    |
+           defineAgent()         StateGraph           SwarmGraph
+           (single agent)       (custom graph)       (7 templates)
+                  |                    |                    |
+                  +--------------------+--------------------+
+                                       |
+                           +-----------+-----------+
+                           |   ONIPregelRunner     |
+                           |   (execution engine)  |
+                           +-----------+-----------+
+                                       |
+         +----------+----------+-------+-------+----------+----------+
+         |          |          |               |          |          |
+     Channels   Streaming  Checkpoint    Circuit     Runtime    Telemetry
+     (reducers) (5 modes)  (3 backends)  Breaker    Context     (OTel)
+                                         + Retry   (AsyncLocal)
+                                         + DLQ
 ```
 
-### All 7 Templates
+Entry points at every level of abstraction:
 
-| Template | Use case | Pattern |
-|---|---|---|
-| `SwarmGraph.hierarchical()` | Supervisor routes to workers | Supervisor -> Agent -> Supervisor -> END |
-| `SwarmGraph.fanOut()` | Parallel execution + aggregation | Send to all -> Collect -> Reduce |
-| `SwarmGraph.pipeline()` | Sequential processing chain | A -> B -> C -> END |
-| `SwarmGraph.peerNetwork()` | Agents hand off to each other | Dynamic peer-to-peer routing |
-| `SwarmGraph.mapReduce()` | Distribute N items across pool | Split -> AgentPool -> Collect -> Reduce |
-| `SwarmGraph.debate()` | Multi-round argumentation | Judge -> Debaters -> Judge -> consensus? |
-| `SwarmGraph.hierarchicalMesh()` | Nested supervisor teams | Coordinator -> Team subgraphs -> Coordinator |
+- **`ONIModel`** -- Call an LLM directly
+- **`defineAgent()`** -- Single agent with tools and system prompt
+- **`StateGraph`** -- Custom graph with full control over nodes and edges
+- **`SwarmGraph`** -- Multi-agent orchestration from templates
 
-See `examples/swarm/` for complete runnable examples of each template.
+---
 
-### Single Agent — No Swarm Required
+## Sub-module Imports
 
-The swarm layer is purely additive. If you just need one agent:
+Tree-shakeable sub-module imports for bundle optimization:
 
 ```ts
-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!" }] });
+import { StateGraph, START, END } from "@oni.bot/core";             // Core engine
+import { createReactAgent }       from "@oni.bot/core/prebuilt";     // Prebuilt agents
+import { SwarmGraph }             from "@oni.bot/core/swarm";        // Swarm templates
+import { interrupt }              from "@oni.bot/core/hitl";         // Human-in-the-loop
+import { InMemoryStore }          from "@oni.bot/core/store";        // Cross-thread store
+import { messagesChannel }        from "@oni.bot/core/messages";     // Message handling
+import { SqliteCheckpointer }     from "@oni.bot/core/checkpointers";// Persistence
+import { entrypoint, task }       from "@oni.bot/core/functional";   // Functional API
+import { buildGraphDescriptor }   from "@oni.bot/core/inspect";      // Graph inspection
+import { emitToken }              from "@oni.bot/core/streaming";    // Token streaming
+import { anthropic, openai }      from "@oni.bot/core/models";       // LLM adapters
+import { defineAgent }            from "@oni.bot/core/agents";       // Agent builder
+import { RequestReplyBroker }     from "@oni.bot/core/coordination"; // Agent messaging
+import { BudgetTracker }          from "@oni.bot/core/guardrails";   // Safety controls
+import { defineTool }             from "@oni.bot/core/tools";        // Tool definitions
+import { mockModel }              from "@oni.bot/core/testing";      // Test utilities
 ```
 
-Entry points at every level: `ONIModel` -> `defineAgent()` -> `StateGraph` -> `SwarmGraph`.
+16 entry points. Import only what you use.
 
 ---
 
-## Features at a Glance
-
-| Feature | Description | Example | Guide |
-|---|---|---|---|
-| Channels | Typed state with pluggable reducers | `examples/ephemeral-channels.ts` | [Section 2](docs/GUIDE.md#2-channels-deep-dive) |
-| Command routing | State update + routing in one return | `examples/command-routing.ts` | [Section 3](docs/GUIDE.md#3-edges-and-routing) |
-| Token streaming | `messages` mode + `getStreamWriter()` | `examples/messages-stream.ts` | [Section 4](docs/GUIDE.md#4-streaming) |
-| Multi-stream | Multiple stream modes simultaneously | `examples/multi-stream.ts` | [Section 4](docs/GUIDE.md#4-streaming) |
-| Custom events | Emit named events via StreamWriter | `examples/custom-stream.ts` | [Section 4](docs/GUIDE.md#4-streaming) |
-| Messages | Smart reducer, helpers, RemoveMessage | `examples/messages-reducer.ts` | [Section 5](docs/GUIDE.md#5-messages) |
-| Checkpointing | Memory, SQLite, PostgreSQL backends | `examples/time-travel.ts` | [Section 6](docs/GUIDE.md#6-checkpointing) |
-| HITL interrupts | `interrupt()`, `getUserApproval()` | `examples/hitl/` | [Section 7](docs/GUIDE.md#7-human-in-the-loop) |
-| Dynamic interrupts | Runtime breakpoint conditions | `examples/dynamic-interrupt.ts` | [Section 7](docs/GUIDE.md#7-human-in-the-loop) |
-| Cross-thread Store | Namespaced KV with semantic search | `examples/store-memory.ts` | [Section 8](docs/GUIDE.md#8-cross-thread-store) |
-| Subgraphs | Nested skeletons + Command.PARENT | `examples/subgraph.ts` | [Section 9](docs/GUIDE.md#9-subgraphs) |
-| Parallel fan-out | Static + dynamic (Send API) | `examples/parallel-fanout.ts` | [Section 10](docs/GUIDE.md#10-parallel-execution) |
-| Map-reduce | Send + fan-in barrier | `examples/map-reduce.ts` | [Section 10](docs/GUIDE.md#10-parallel-execution) |
-| Runtime context | `getConfig()`, `getStore()`, etc. | `examples/runtime-context.ts` | [Section 11](docs/GUIDE.md#11-runtime-context) |
-| Retry + cache | Per-node retry policy with backoff | `examples/retry-policy.ts` | [Section 12](docs/GUIDE.md#12-retry-and-cache) |
-| Functional API | `task`, `entrypoint`, `pipe`, `branch` | `examples/functional-api.ts` | [Section 13](docs/GUIDE.md#13-functional-api) |
-| ReAct agent | Prebuilt agent loop with tools | `examples/react-agent.ts` | [Section 14](docs/GUIDE.md#14-prebuilt-components) |
-| Graph inspection | Topology, Mermaid, cycle detection | `examples/graph-inspection.ts` | [Section 16](docs/GUIDE.md#16-graph-inspection) |
-| Time travel | `getHistory`, `getStateAt`, `forkFrom` | `examples/time-travel.ts` | [Section 17](docs/GUIDE.md#17-time-travel) |
-| Swarm | 7 templates + Supervisor, Handoff, retry-fallback, coordination | `examples/swarm/` | [Section 18](docs/GUIDE.md#18-swarm-orchestration) |
+## Production Features
 
----
+### Circuit Breakers
 
-## Core Concepts
+```ts
+const app = graph.compile({
+  circuitBreaker: { threshold: 5, resetAfter: 30_000 },
+});
+```
 
-### Channels
+After 5 consecutive failures, the circuit opens and fast-fails all requests. After 30 seconds, it transitions to half-open and lets one request through to test recovery.
 
-Every state field has a **channel** — a reducer + default factory that controls how concurrent updates merge.
+### Node Timeouts
 
 ```ts
-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
-};
+graph.addNode("llm_call", handler, { timeout: 10_000 }); // 10s deadline
 ```
 
-### Nodes, edges, compile
+Nodes that exceed their timeout are killed and routed through the error recovery path.
+
+### Retry with Backoff
 
 ```ts
-graph.addNode("agent", async (state, config?) => {
-  return { answer: "partial update" };  // or Command, or void
+graph.addNode("flaky_api", handler, {
+  retry: { maxAttempts: 3, backoff: "exponential", initialDelay: 1000 },
 });
+```
+
+### Dead Letter Queue
+
+```ts
+const dlq = new DeadLetterQueue();
+const app = graph.compile({ dlq });
+
+// Later: inspect failures
+const failures = dlq.list();
+```
 
-graph.addEdge(START, "agent");
-graph.addConditionalEdges("agent", (state) => state.done ? END : "tools");
+### OpenTelemetry Tracing
 
-const app = graph.compile({ checkpointer, store });
+```ts
+import { ONITracer } from "@oni.bot/core";
+import { trace } from "@opentelemetry/api";
+
+const tracer = new ONITracer(trace.getTracer("my-app"));
+const app = graph.compile({ tracer });
 ```
 
-### Invoke / Stream / Batch
+Zero-dep adapter that wraps any OpenTelemetry-compatible tracer. Emits spans for graph execution, node runs, tool calls, model invocations, and checkpoint operations.
+
+### Checkpointing + Time Travel
 
 ```ts
-const result  = await app.invoke(input, { threadId: "t1" });
-const stream  = app.stream(input, { streamMode: "updates" });
-const results = await app.batch([input1, input2]);
+import { SqliteCheckpointer } from "@oni.bot/core/checkpointers";
+
+const checkpointer = new SqliteCheckpointer("./state.db");
+const app = graph.compile({ checkpointer });
+
+// Resume from any point
+const history = await app.getHistory("thread-1");
+const forked = await app.forkFrom("thread-1", history[2].checkpoint);
 ```
 
-For the full progressive tutorial, see **[docs/GUIDE.md](docs/GUIDE.md)**.
+Three built-in backends: `MemoryCheckpointer` (dev), `SqliteCheckpointer` (single-node), `PostgresCheckpointer` (distributed). Or implement `ONICheckpointer` for your own.
 
 ---
 
-## Sub-module Exports
+## Human-in-the-Loop
 
-Tree-shakeable sub-module imports for bundle optimization:
+```ts
+import { interrupt, getUserApproval } from "@oni.bot/core/hitl";
+
+graph.addNode("review", async (state) => {
+  const approved = await getUserApproval("Publish this draft?", {
+    payload: state.draft,
+  });
+  if (!approved) return { status: "rejected" };
+  return { status: "published" };
+});
+```
 
-| Import path | Contents |
-|---|---|
-| `@oni.bot/core` | Everything (116+ exports) |
-| `@oni.bot/core/prebuilt` | `createReactAgent`, `createToolNode`, `toolsCondition`, types |
-| `@oni.bot/core/swarm` | `SwarmGraph` (7 templates), `AgentRegistry`, `AgentPool`, `Handoff`, `Supervisor`, `Mailbox`, coordination |
-| `@oni.bot/core/hitl` | `interrupt`, `getUserInput`, `getUserApproval`, `getUserSelection`, session store |
-| `@oni.bot/core/store` | `BaseStore`, `InMemoryStore`, `NamespacedStore`, `AgentMemoryStore` |
-| `@oni.bot/core/messages` | `messagesChannel`, `messagesReducer`, helpers, `RemoveMessage`, `UpdateMessage` |
-| `@oni.bot/core/checkpointers` | `SqliteCheckpointer`, `PostgresCheckpointer`, `NamespacedCheckpointer` |
-| `@oni.bot/core/functional` | `task`, `entrypoint`, `pipe`, `branch` |
-| `@oni.bot/core/inspect` | `buildGraphDescriptor`, `toMermaidDetailed` |
-| `@oni.bot/core/streaming` | `emitToken`, `TokenStreamWriter`, `StreamWriterImpl` |
-| `@oni.bot/core/models` | `ONIModel`, `anthropic()`, `openai()` model factories |
-| `@oni.bot/core/agents` | `defineAgent`, `agent()`, `AgentContext`, types |
-| `@oni.bot/core/coordination` | `RequestReplyBroker`, `PubSub` coordination primitives |
-| `@oni.bot/core/guardrails` | `InputGuardrail`, `OutputGuardrail`, guardrail types |
-| `@oni.bot/core/tools` | `defineTool`, `createInjectedTool`, tool types |
+Execution pauses, the interrupt is surfaced to your application, and the graph resumes exactly where it left off when the user responds.
 
 ---
 
-## Architecture
+## Streaming
+
+```ts
+// Single mode
+for await (const event of app.stream(input, { streamMode: "updates" })) {
+  console.log(event.node, event.data);
+}
 
+// Multiple modes simultaneously
+for await (const event of app.stream(input, { streamMode: ["values", "messages"] })) {
+  if (event.mode === "messages") {
+    process.stdout.write(event.data.chunk); // Token-by-token LLM output
+  }
+}
+
+// Custom events from inside a node
+import { getStreamWriter } from "@oni.bot/core";
+
+graph.addNode("agent", async (state) => {
+  const writer = getStreamWriter();
+  writer.emit("progress", { step: 1, message: "Searching..." });
+  // ...
+});
 ```
-@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
+
+---
+
+## Functional API
+
+For simpler use cases, skip the builder pattern entirely:
+
+```ts
+import { entrypoint, task } from "@oni.bot/core/functional";
+import { lastValue } from "@oni.bot/core";
+
+const summarize = task("summarize", async (text: string) => {
+  return await llm.chat({ messages: [{ role: "user", content: `Summarize: ${text}` }] });
+});
+
+const app = entrypoint(
+  { channels: { query: lastValue(() => ""), answer: lastValue(() => "") } },
+  async (state) => ({ answer: await summarize(state.query) }),
+);
+
+const result = await app.invoke({ query: "Explain quantum computing" });
 ```
 
 ---
 
-## ONI Platform
+## Testing
 
-`@oni.bot/core` is the foundation layer. Other ONI packages build on top:
+```ts
+import { mockModel, assertGraph, createTestHarness } from "@oni.bot/core/testing";
+
+// Deterministic model responses
+const model = mockModel([
+  { role: "assistant", content: "Hello!" },
+  { role: "assistant", content: "Goodbye!", toolCalls: [{ id: "1", name: "search", args: {} }] },
+]);
+
+// Structural graph assertions
+assertGraph(graph, {
+  hasNode: ["agent", "tools"],
+  hasEdge: [["__start__", "agent"]],
+  nodeCount: 2,
+});
 
-| Package | Built on |
-|---|---|
-| `@oni/agentOS` | AgentOS ADE — multi-agent orchestration |
-| `@oni/vectorforge` | VectorForge — knowledge base & SOP retrieval |
-| `@oni/cic` | CIC Agent Assist — call center intelligence |
-| `@oni/oats` | OATS — Five9 AI Agent Assist integration |
+// Pre-wired test harness
+const harness = createTestHarness(graph);
+const result = await harness.invoke({ query: "test" });
+const events = await harness.collectStream({ query: "test" }, "updates");
+```
 
 ---
 
 ## Documentation
 
-- **[Developer Guide](docs/GUIDE.md)** — Progressive tutorial from zero to advanced (19 sections)
-- **[API Reference](docs/API.md)** — Complete reference for all 116+ public exports
-- **[Examples](examples/)** — 30+ runnable example files covering every feature
+| Resource | Description |
+|---|---|
+| **[Developer Guide](docs/GUIDE.md)** | Progressive tutorial from zero to advanced -- 19 sections covering every feature |
+| **[API Reference](docs/API.md)** | Complete reference for all 130+ public exports |
+| **[Examples](examples/)** | 30+ runnable example files covering every feature |
+
+---
+
+## Optional Peer Dependencies
+
+The core engine has zero runtime dependencies. Optional packages unlock additional backends:
+
+```bash
+npm install better-sqlite3   # SqliteCheckpointer
+npm install pg               # PostgresCheckpointer
+```
+
+---
+
+## Contributing
+
+Contributions are welcome. Please open an issue to discuss significant changes before submitting a PR.
+
+```bash
+git clone https://github.com/oni-bot/core.git
+cd core
+npm install
+npm test
+```
 
 ---
 
 ## License
 
-MIT — ONI Platform
+MIT -- [ONI Platform](https://github.com/oni-bot)