ONI Core is a TypeScript graph execution engine for production agent swarms, stateful workflows, tool execution, streaming, persistence, human review, and background-agent orchestration.

The root package stays dependency-light and ESM-first. Optional peer packages unlock runtime integrations such as SQLite, Postgres, Redis, model adapters, document loaders, and dev tooling without forcing them into every install.

Install

npm install @oni.bot/core

Requirements:

• Node.js 18+
• TypeScript projects should use ESM-compatible module resolution.
• Optional peers are installed only when you use the matching backend or package.

What Is Included

• Graph runtime: StateGraph, MessageGraph, channels, reducers, conditional routing, retries, checkpointing, and streaming.
• Swarm runtime: agent registries, pools, handoffs, supervisors, tracing, snapshots, scaling monitors, and topology helpers.
• Tool runtime: structured tool definitions, runtime policy wrapping, execution, permissions, audit logs, and guardrails.
• Model adapters: raw HTTP adapters for Anthropic, OpenAI, OpenRouter, Google, and Ollama.
• Platform control plane: background sessions, triggers, queues, identities, capability grants, environments, artifacts, review gates, health, and audit summaries.
• Harness layer: native agent loops, external CLI drivers, JSONL parsers, resumable metadata, safety gates, hooks, and context compaction.
• Release hardening: export smoke tests, type smoke tests, package tarball snapshots, dependency audit, secret scanning, coverage gates, and lint budgets.

Quick Start

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

type WorkflowState = {
  request: string;
  steps: string[];
  summary: string;
};

const graph = new StateGraph<WorkflowState>({
  channels: {
    request: lastValue<string>(() => ""),
    steps: appendList<string>(),
    summary: lastValue<string>(() => ""),
  },
});

graph.addNode("plan", async (state) => ({
  steps: [
    `Clarify scope: ${state.request}`,
    "Execute the smallest useful change",
    "Verify the result",
  ],
}));

graph.addNode("summarize", async (state) => ({
  summary: `Prepared ${state.steps.length} execution steps.`,
}));

graph.addEdge(START, "plan");
graph.addEdge("plan", "summarize");
graph.addEdge("summarize", END);

const app = graph.compile();
const result = await app.invoke({
  request: "Ship a monitored support workflow",
});

console.log(result.summary);

For token or event streaming, use app.stream(input, { streamMode: "values" }) or the dedicated streaming helpers exported from @oni.bot/core/streaming.

Public Entry Points

The package publishes 23 import surfaces so consumers can import only the runtime area they need.

| Import | Use it for | |---|---| | @oni.bot/core | Root graph runtime, channels, messages, swarm primitives, models, tools, platform, harness, telemetry, logging, and errors | | @oni.bot/core/prebuilt | ReAct agents, tool nodes, and prebuilt graph helpers | | @oni.bot/core/swarm | Swarm graph templates, pools, handoffs, supervisors, snapshots, scaling, tracing, and topology helpers | | @oni.bot/core/hitl | Human-in-the-loop interrupts, approvals, selections, and session storage | | @oni.bot/core/store | In-memory and namespaced cross-thread stores | | @oni.bot/core/messages | Message channels, reducers, message constructors, trimming, updates, and removals | | @oni.bot/core/checkpointers | Memory, SQLite, Postgres, Redis, and namespaced checkpoint backends | | @oni.bot/core/functional | Functional task, entrypoint, pipe, and branch APIs | | @oni.bot/core/inspect | Graph descriptors, cycle checks, topological order, and Mermaid output | | @oni.bot/core/streaming | Token streaming, stream writers, bounded buffers, and stream events | | @oni.bot/core/models | Anthropic, OpenAI, OpenRouter, Google, and Ollama model adapters | | @oni.bot/core/tools | defineTool, tool execution, schemas, permissions, and tool contexts | | @oni.bot/core/agents | Functional agent definitions and swarm message context helpers | | @oni.bot/core/coordination | Request/reply broker and pub/sub coordination primitives | | @oni.bot/core/events | Lifecycle event bus and event listener contracts | | @oni.bot/core/guardrails | Budgets, content filters, permission checks, and audit logging | | @oni.bot/core/testing | Mock models, graph assertions, harness helpers, and test utilities | | @oni.bot/core/harness | Agent loop, external agent host, CLI drivers, runtime registry, hooks, safety gates, context compaction, and JSONL parsers | | @oni.bot/core/mcp | MCP stdio transport and JSON-RPC tool bridge | | @oni.bot/core/lsp | Language Server Protocol client primitives | | @oni.bot/core/config | JSONC config loading and environment variable resolution | | @oni.bot/core/registry | Dynamic runtime tool registry | | @oni.bot/core/platform | Background-agent sessions, routing, triggers, environments, stores, artifacts, review gates, runtime policy, health, and audit summaries |

Platform Layer

@oni.bot/core/platform is the control plane for long-running or externally executed work. It normalizes task submission, trigger handling, routing, environment provisioning, scoped identity, capability grants, runtime policy, artifact publication, review, and session health into one lifecycle.

The platform includes:

• Local, HTTP, and Cerebro execution environment providers.
• In-memory, JSON-file, SQLite, and Postgres session/artifact stores.
• CLI, scheduled, chat command, GitHub webhook, and dependency alert triggers.
• Runtime policy helpers for path, command, network, tool, and explicit secret grants.
• Session runners for native agentLoop(), external CLI providers, and compiled swarm workflows.
• GitHubArtifactStore for publishing pull requests, reports, diagnostics, and test summaries to GitHub while mirroring enriched records to another store.
• Health and audit summaries for queue depth, session status, failure rates, durations, costs, artifacts, and lifecycle events.

For a local smoke run:

oni platform-smoke --dir .oni/platform-smoke

Workspace Packages

The monorepo also contains focused packages that build on the root runtime.

| Package | Status | Purpose | |---|---|---| | @oni.bot/tools | Public | Prebuilt tool definitions for filesystem, HTTP, search, Slack, Stripe, E2B, and related integrations | | @oni.bot/stores | Public | Redis and Postgres store backends | | @oni.bot/loaders | Public | Markdown, JSON, CSV, PDF, HTML, and DOCX document loaders | | @oni.bot/a2a | Public | A2A protocol client, server, and swarm integration | | @oni.bot/integrations | Public | ActivePieces-to-ONI adapter for community integrations | | @oni.bot/devtools | Public | Lightweight dev server for graph topology, registry state, and live execution events | | @oni.bot/hot-loader | Public | File-watching extension loader for DynamicToolRegistry | | @oni.bot/community | Private | ActivePieces community source library used by the integrations package |

Verification

Common local checks:

pnpm run typecheck
pnpm test
pnpm run build
pnpm run smoke:exports
pnpm run typecheck:exports
pnpm run pack:snapshot

Release verification runs the broader gate:

pnpm run verify:release

That gate combines root and package tests, strict type checking, coverage thresholds, build checks, subpath export smoke tests, consumer type smoke tests, dependency audit, content secret scanning, lint-warning budgets, and package tarball snapshots.

Documentation

• Developer Guide - graph basics, channels, streaming, checkpointing, agents, swarms, and advanced runtime patterns.
• Changelog - release history and compatibility notes.
• Security - reporting and security policy.

License

MIT - AP3X Dev