Monorch

Getting started

Build the native runtime, run the repo smoke, then copy the smallest agent and graph patterns into your own HTTP handlers (Fastify, Hono, Nest, …).

Install from npm

@monorch/ai ships on npm with prebuilt @monorch/runtime binaries. No Rust toolchain required in your app repo.

terminal
pnpm add @monorch/ai
# optional: pnpm add pg   # only for @monorch/ai/postgres

Supported exports and SemVer policy: Public API.

Monorepo development

From the repo root when hacking on the engine or docs. Native bindings compile with N-API; TypeScript builds into packages/ai/dist.

terminal
pnpm install
pnpm build          # @monorch/runtime + @monorch/ai
pnpm smoke          # BYO HTTP example (examples/fastify)
pnpm smoke:npm      # consumer smoke against published @monorch/ai
pnpm smoke:hono     # same, Hono host (examples/hono-npm)
pnpm ci             # engine + TS tests, build, typecheck, smoke
pnpm dev:www        # docs site on :3100

Minimal agent

Register a tool, create an agent, call run or stream. Tool args are authorized and parsed in Rust before your execute callback runs.

math-agent.ts
import { agent, tool, mock } from "@monorch/ai";
import { z } from "zod";

const add = tool({
  name: "add",
  description: "Add two numbers",
  input: z.object({ a: z.number(), b: z.number() }),
  permission: { type: "roles", roles: ["agent"] },
  execute: ({ a, b }) => ({ sum: a + b }),
});

const math = agent({
  name: "math",
  model: mock([
    { toolCalls: [{ id: "c1", name: "add", arguments: { a: 2, b: 3 } }] },
    { text: "2 + 3 = 5" },
  ]),
  tools: [add],
  instructions: "Use tools for math.",
});

const result = await math.run("What is 2+3?");
// { text, runId, events }

Interruptible graph

Prefer graph() for orchestration. Pass a threadId when you need to restore after an interrupt.

refund.ts
import { graph, memorySaver } from "@monorch/ai";

const refund = graph("refund")
  .node("lookup", async ({ input }) => ({
    output: `order:${input.orderId}`,
    state: { orderId: input.orderId },
  }))
  .interrupt("approve", { prompt: "Approve refund?" })
  .node("pay", async ({ outputs }) => `refunded:${outputs.lookup}`)
  .compile({ checkpointer: memorySaver() });

let run = await refund.start({ orderId: "ord_9" }, { threadId: "t1" });
if (run.status === "waitingInterrupt") {
  run = await run.resume("approved");
  // or later: await refund.restore("t1") then resume
}

Smoke tests

Monorepo HTTP smoke — examples/fastify is a BYO HTTP sample, not a Fastify requirement. It covers agent run, SSE stream, handoffs, MCP tools, OTel listener, branching/cycles, checkpoint v2 restore, idempotent drive() while waiting, thread memory, abort, graph replace, Postgres adapters (in-memory SQL stand-in), and optional LIVE_SMOKE=1. Walkthrough: HTTP with Fastify.

Published npm smoke — examples/npm-smoke installs @monorch/ai from the registry (not the workspace) and runs a focused script: native load, agent tool loop, SSE stream, handoff, graph interrupt + checkpoint resume. From the repo root: pnpm smoke:npm. A second host is examples/hono-npm (pnpm smoke:hono).

FAQ