@oni.bot/core 0.6.1

package/README.md

@@ -0,0 +1,308 @@
+# @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
+
+```bash
+npm install @oni.bot/core
+```
+
+**Optional peer dependencies:**
+
+```bash
+npm install better-sqlite3          # for SqliteCheckpointer
+npm install pg                      # for PostgresCheckpointer
+```
+
+---
+
+## Quick Start
+
+### Minimal graph
+
+```ts
+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
+
+```ts
+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
+
+```ts
+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)
+
+```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",
+});
+
+const app = swarm.compile();
+const result = await app.invoke({ task: "Write a blog post about AI" });
+```
+
+### All 7 Templates
+
+| 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 |
+
+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:
+
+```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!" }] });
+```
+
+Entry points at every level: `ONIModel` -> `defineAgent()` -> `StateGraph` -> `SwarmGraph`.
+
+---
+
+## 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) |
+
+---
+
+## Core Concepts
+
+### Channels
+
+Every state field has a **channel** — a reducer + default factory that controls how concurrent updates merge.
+
+```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
+};
+```
+
+### Nodes, edges, compile
+
+```ts
+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
+
+```ts
+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](docs/GUIDE.md)**.
+
+---
+
+## Sub-module Exports
+
+Tree-shakeable sub-module imports for bundle optimization:
+
+| 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 |
+
+---
+
+## 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:
+
+| 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 |
+
+---
+
+## 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
+
+---
+
+## License
+
+MIT — ONI Platform

package/dist/agents/context.d.ts

@@ -0,0 +1,24 @@
+import type { ONIModel } from "../models/types.js";
+import type { ToolDefinition } from "../tools/types.js";
+import type { ONIConfig } from "../types.js";
+import type { BaseStore } from "../store/index.js";
+import type { StreamWriter } from "../context.js";
+import type { AgentContext, SwarmMessageView } from "./types.js";
+export interface BuildAgentContextOptions<S = Record<string, unknown>> {
+    model?: ONIModel;
+    tools?: ToolDefinition[];
+    agentName: string;
+    systemPrompt?: string;
+    config: ONIConfig;
+    store: BaseStore | null;
+    state: S;
+    streamWriter: StreamWriter | null;
+    remainingSteps: number;
+    onSend: (agent: string, payload: unknown) => void;
+    getInbox: () => SwarmMessageView[];
+    onRequest: (agent: string, payload: unknown) => Promise<unknown>;
+    onReply: (msg: SwarmMessageView, payload: unknown) => void;
+    onPublish: (topic: string, data: unknown) => void;
+}
+export declare function buildAgentContext<S = Record<string, unknown>>(opts: BuildAgentContextOptions<S>): AgentContext<S>;
+//# sourceMappingURL=context.d.ts.map

package/dist/agents/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/agents/context.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,QAAQ,EAMT,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAMjE,MAAM,WAAW,wBAAwB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACnE,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IAGtB,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,CAAC,CAAC;IACT,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;IAClC,cAAc,EAAE,MAAM,CAAC;IAGvB,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,QAAQ,EAAE,MAAM,gBAAgB,EAAE,CAAC;IACnC,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE,OAAO,EAAE,CAAC,GAAG,EAAE,gBAAgB,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAC3D,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;CACnD;AAMD,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,IAAI,EAAE,wBAAwB,CAAC,CAAC,CAAC,GAChC,YAAY,CAAC,CAAC,CAAC,CAkHjB"}

package/dist/agents/context.js

@@ -0,0 +1,93 @@
+// ============================================================
+// @oni.bot/core — AgentContext Builder
+// ============================================================
+// Factory that assembles an AgentContext from runtime parts.
+// Used by both defineAgent() and agent() factories.
+// ============================================================
+// ----------------------------------------------------------------
+// buildAgentContext — assemble a full AgentContext
+// ----------------------------------------------------------------
+export function buildAgentContext(opts) {
+    const { model, tools = [], agentName, systemPrompt, config, store, state, streamWriter, remainingSteps, onSend, getInbox, onRequest, onReply, onPublish, } = opts;
+    // Convert ToolDefinition[] to LLMToolDef[] for model.chat/stream
+    const llmTools = tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        parameters: t.schema,
+    }));
+    // Build the ChatParams base (system prompt + tools)
+    function makeChatParams(messages) {
+        return {
+            messages,
+            tools: llmTools.length > 0 ? llmTools : undefined,
+            systemPrompt,
+        };
+    }
+    return {
+        // ---- LLM interaction ----
+        async chat(messages) {
+            if (!model) {
+                throw new Error(`Agent "${agentName}" has no model configured. Pass a model via options to use chat().`);
+            }
+            return model.chat(makeChatParams(messages));
+        },
+        async *stream(messages) {
+            if (!model) {
+                throw new Error(`Agent "${agentName}" has no model configured. Pass a model via options to use stream().`);
+            }
+            yield* model.stream(makeChatParams(messages));
+        },
+        async executeTools(calls) {
+            const toolMap = new Map(tools.map((t) => [t.name, t]));
+            return Promise.all(calls.map(async (call) => {
+                const tool = toolMap.get(call.name);
+                if (!tool) {
+                    return {
+                        toolCallId: call.id,
+                        name: call.name,
+                        result: `Tool "${call.name}" not found`,
+                        isError: true,
+                    };
+                }
+                try {
+                    // Build a manual ToolContext — we don't rely on AsyncLocalStorage here
+                    // because agent nodes run inside Pregel which provides context, and we
+                    // want the tool to receive our explicit config/store/state.
+                    const toolCtx = {
+                        config,
+                        store,
+                        state: state,
+                        emit: (event, data) => {
+                            if (streamWriter)
+                                streamWriter.emit(event, data);
+                        },
+                    };
+                    const result = await tool.execute(call.args, toolCtx);
+                    return { toolCallId: call.id, name: call.name, result };
+                }
+                catch (err) {
+                    return {
+                        toolCallId: call.id,
+                        name: call.name,
+                        result: String(err),
+                        isError: true,
+                    };
+                }
+            }));
+        },
+        // ---- Coordination ----
+        send: onSend,
+        inbox: getInbox,
+        request: onRequest,
+        reply: onReply,
+        publish: onPublish,
+        // ---- Runtime context ----
+        config,
+        store,
+        state,
+        streamWriter,
+        remainingSteps,
+        agentName,
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/agents/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/agents/context.ts"],"names":[],"mappings":"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"}

package/dist/agents/define-agent.d.ts

@@ -0,0 +1,10 @@
+import type { DefineAgentOptions, AgentNode } from "./types.js";
+/**
+ * defineAgent — create a declarative ReAct agent
+ *
+ * The returned AgentNode._nodeFn is suitable for use as a graph node.
+ * It expects the state to have an optional `messages` field (ONIModelMessage[])
+ * and returns `{ messages }` with the conversation appended.
+ */
+export declare function defineAgent<S extends Record<string, unknown> = Record<string, unknown>>(opts: DefineAgentOptions): AgentNode<S>;
+//# sourceMappingURL=define-agent.d.ts.map

package/dist/agents/define-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-agent.d.ts","sourceRoot":"","sources":["../../src/agents/define-agent.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEhE;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrF,IAAI,EAAE,kBAAkB,GACvB,SAAS,CAAC,CAAC,CAAC,CAuHd"}

package/dist/agents/define-agent.js

@@ -0,0 +1,121 @@
+// ============================================================
+// @oni.bot/core — defineAgent() — Declarative Agent Factory
+// ============================================================
+// Creates an AgentNode that runs a ReAct loop automatically:
+//   1. Seed messages from state.messages
+//   2. Loop up to maxSteps:
+//      a. Call model.chat with messages + systemPrompt + tools
+//      b. Track token usage, break if maxTokens exceeded
+//      c. Push assistant message
+//      d. If no toolCalls -> break (done)
+//      e. Execute tools with manual ToolContext
+//      f. Push tool result messages
+//   3. Return { messages }
+// ============================================================
+/**
+ * defineAgent — create a declarative ReAct agent
+ *
+ * The returned AgentNode._nodeFn is suitable for use as a graph node.
+ * It expects the state to have an optional `messages` field (ONIModelMessage[])
+ * and returns `{ messages }` with the conversation appended.
+ */
+export function defineAgent(opts) {
+    const { name, description, model, tools = [], systemPrompt, maxSteps = 10, maxTokens, } = opts;
+    // Pre-compute LLMToolDef[] from ToolDefinition[]
+    const llmTools = tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        parameters: t.schema,
+    }));
+    const _nodeFn = async (state, config) => {
+        // 1. Seed messages from state
+        const existingMessages = (Array.isArray(state.messages)
+            ? state.messages
+            : []);
+        const messages = [...existingMessages];
+        let totalTokens = 0;
+        // 2. ReAct loop
+        for (let step = 0; step < maxSteps; step++) {
+            // a. Call model.chat
+            const response = await model.chat({
+                messages,
+                tools: llmTools.length > 0 ? llmTools : undefined,
+                systemPrompt,
+            });
+            // b. Track token usage
+            totalTokens += response.usage.inputTokens + response.usage.outputTokens;
+            // c. Push assistant message
+            const assistantMsg = {
+                role: "assistant",
+                content: response.content,
+            };
+            if (response.toolCalls && response.toolCalls.length > 0) {
+                assistantMsg.toolCalls = response.toolCalls;
+            }
+            messages.push(assistantMsg);
+            // Check maxTokens budget
+            if (maxTokens !== undefined && totalTokens >= maxTokens) {
+                break;
+            }
+            // d. If no tool calls -> done
+            if (!response.toolCalls || response.toolCalls.length === 0) {
+                break;
+            }
+            // e. Execute tools with manual ToolContext
+            const toolMap = new Map(tools.map((t) => [t.name, t]));
+            const toolResults = await Promise.all(response.toolCalls.map(async (call) => {
+                const tool = toolMap.get(call.name);
+                if (!tool) {
+                    return {
+                        toolCallId: call.id,
+                        name: call.name,
+                        result: `Tool "${call.name}" not found`,
+                        isError: true,
+                    };
+                }
+                try {
+                    const toolCtx = {
+                        config: config ?? {},
+                        store: null,
+                        state: state,
+                        emit: () => { },
+                    };
+                    const result = await tool.execute(call.args, toolCtx);
+                    return { toolCallId: call.id, name: call.name, result };
+                }
+                catch (err) {
+                    return {
+                        toolCallId: call.id,
+                        name: call.name,
+                        result: String(err),
+                        isError: true,
+                    };
+                }
+            }));
+            // f. Push tool result messages
+            for (const tr of toolResults) {
+                messages.push({
+                    role: "tool",
+                    content: typeof tr.result === "string" ? tr.result : JSON.stringify(tr.result),
+                    toolCallId: tr.toolCallId,
+                    name: tr.name,
+                });
+            }
+        }
+        // 3. Return updated messages (only the new ones appended during this run)
+        const newMessages = messages.slice(existingMessages.length);
+        return { messages: newMessages };
+    };
+    return {
+        name,
+        description,
+        model,
+        tools,
+        systemPrompt,
+        maxSteps,
+        maxTokens,
+        _nodeFn,
+        _isAgent: true,
+    };
+}
+//# sourceMappingURL=define-agent.js.map

package/dist/agents/define-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-agent.js","sourceRoot":"","sources":["../../src/agents/define-agent.ts"],"names":[],"mappings":"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"}

package/dist/agents/functional-agent.d.ts

@@ -0,0 +1,12 @@
+import type { AgentNode, AgentContext, FunctionalAgentOptions } from "./types.js";
+type AgentHandler<S> = (ctx: AgentContext<S>) => Promise<Partial<S>> | Partial<S>;
+/**
+ * agent() — create a functional agent node
+ *
+ * Overloads:
+ *   agent(name, handler)
+ *   agent(name, opts, handler)
+ */
+export declare function agent<S extends Record<string, unknown> = Record<string, unknown>>(name: string, fnOrOpts: AgentHandler<S> | FunctionalAgentOptions, fn?: AgentHandler<S>): AgentNode<S>;
+export {};
+//# sourceMappingURL=functional-agent.d.ts.map

package/dist/agents/functional-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"functional-agent.d.ts","sourceRoot":"","sources":["../../src/agents/functional-agent.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,sBAAsB,EAAoB,MAAM,YAAY,CAAC;AAQpG,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAElF;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,sBAAsB,EAClD,EAAE,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,GACnB,SAAS,CAAC,CAAC,CAAC,CAkHd"}