Architecture

Reactive Agents uses a layered, composable architecture built on Effect-TS.

Kernel structure

The reasoning kernel was reorganized in v0.10 to group code by capability. If you’re contributing or reading the source, this is the layout:

Directorypackages/reasoning/src/kernel/
- Directorycapabilities/
  - Directoryact/ tool execution, gating, parsing, healing pipeline
    …
  - Directoryattend/ context utils + tool formatting
    …
  - Directorycomprehend/ task intent
    …
  - Directorydecide/ arbitrator (single-owner termination)
    …
  - Directoryreason/ think · think-guards · stream parser
    …
  - Directoryreflect/ loop detector · reactive observer · strategy evaluator
    …
  - Directorysense/ step utils
    …
  - Directoryverify/ evidence grounding · quality utils · verifier
    …
- Directoryloop/
  - runner.ts main 12-phase orchestrator
  - react-kernel.ts ReAct strategy kernel
  - terminate.ts single-owner termination helper
  - auto-checkpoint.ts
  - output-assembly.ts
  - output-synthesis.ts
- Directorystate/ kernel-state · kernel-hooks · kernel-constants
  - …
- Directoryutils/ diagnostics · ICS coordinator · lane controller
  - …

The single-owner termination invariant (M9 mechanism, 100% path coverage) is enforced by kernel/loop/terminate.ts plus a CI lint guard at scripts/check-termination-paths.sh — no path bypasses the arbitrator.

Layer Stack

                    ┌─────────────────────────┐
                    │    ReactiveAgentBuilder  │  Public API
                    └────────────┬────────────┘
                                 │
                    ┌────────────▼────────────┐
                    │      ExecutionEngine     │  12-phase lifecycle
                    └────────────┬────────────┘
                                 │
         ┌───────────────────────┼───────────────────────┐
         │                       │                       │
    ┌────▼────┐            ┌─────▼─────┐           ┌─────▼─────┐
    │  Memory │            │ Reasoning │           │   Tools   │
    │ (L2)    │            │ (L3)      │           │ (L8)      │
    └────┬────┘            └─────┬─────┘           └─────┬─────┘
         │                       │                       │
    ┌────▼────────────────────────▼───────────────────────▼────┐
    │                    LLM Provider (L1.5)                    │
    └────────────────────────────┬─────────────────────────────┘
                                 │
    ┌────────────────────────────▼─────────────────────────────┐
    │           Core Services (L1)                             │
    │   EventBus  ·  AgentService  ·  TaskService              │
    └──────────────────────────────────────────────────────────┘

Optional Layers

These can be enabled independently:

Layer	Package	What It Does
Guardrails	`@reactive-agents/guardrails`	Input/output safety
Verification	`@reactive-agents/verification`	Fact-checking, semantic entropy
Cost	`@reactive-agents/cost`	Model routing, budget enforcement
Identity	`@reactive-agents/identity`	Agent certificates, RBAC
Observability	`@reactive-agents/observability`	Tracing, metrics, logging
Interaction	`@reactive-agents/interaction`	5 autonomy modes
Orchestration	`@reactive-agents/orchestration`	Multi-agent workflows
Prompts	`@reactive-agents/prompts`	Template engine
A2A	`@reactive-agents/a2a`	Agent-to-Agent protocol (JSON-RPC, Agent Cards, SSE)
Gateway	`@reactive-agents/gateway`	Persistent autonomous harness: heartbeats, crons, webhooks, policy engine
Reactive Intelligence	`@reactive-agents/reactive-intelligence`	Entropy sensor, reactive controller, local learning, optional telemetry; integrates with kernel + EventBus

Dependency Graph

Core ← LLM Provider ← Memory
                     ← Reasoning
                     ← Tools

Core ← Guardrails (standalone)
     ← Verification (standalone)
     ← Cost (standalone)
     ← Identity (standalone)
     ← Observability (standalone)
     ← Interaction (needs EventBus)
     ← Orchestration (standalone)
     ← Prompts (standalone)
     ← A2A (needs Core + Tools)
     ← Gateway (needs Core EventBus)

How Layers Compose

Every layer is an Effect Layer — a recipe for building a service. Layers compose through Layer.merge and Layer.provide:

import { createRuntime } from "@reactive-agents/runtime";

// The runtime composes all enabled layers into a single Layer
const runtime = createRuntime({
  agentId: "my-agent",
  provider: "anthropic",
  enableGuardrails: true,
  enableReasoning: true,
  enableCostTracking: true,
});

// This Layer provides ALL services needed by the ExecutionEngine

This means:

No singletons — Each agent gets its own service instances
No global state — Everything is scoped to the Layer
Testable — Swap any layer with a test implementation
Tree-shakeable — Disabled layers aren’t loaded