Architecture

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

Mental model

Every .with*() call adds a Layer. build() composes Layers into the 12-phase ExecutionEngine. agent.run() flows a task through all 12 phases. No singletons, no global state — each agent is its own isolated runtime.

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.

The meta-loop

Internally the reasoning harness is a one-directional loop — a small DAG where each stage reads only from the stage before it, with no back-edges. This is what makes a run’s decisions replayable: given the same ledger, every downstream read is a pure function.

Contract → Ledger → Assessment → Control → Actuators → Projector

Stage	Role
Contract	The typed goal — “what does DONE mean for this run?” Compiled once at run start from the task (plus any declared .withContract()) and then frozen: requirements, deliverables, constraints, horizon, acceptance policy.
Ledger	The append-only event store everything else projects from — tool invocations, artifacts (path + content digest), verifier verdicts, evidence claims (twelve fact families). It is the single source of run history and rides crash-resume. Full entry taxonomy + honest-compaction rules: The evidence ledger.
Assessment	A pure, per-iteration read of where the run stands, derived from contract × ledger: requirements satisfied/outstanding, deliverables produced/missing, evidence delta, run phase (orient / gather / execute / synthesize / verify), pace band, health. Emitted as an AssessmentEmitted trace event every iteration. Default-on; opt-in levers (.withLongHorizon() / .withAdaptiveHarness()) only react to it. Field-by-field: Run assessment.
Control	One proposal → resolver that picks a single action per iteration from a documented total order (continue, nudge, switch strategy, redirect, escalate, terminate). No two subsystems race to steer the loop.
Actuators	The effects that carry out the chosen action — guards, strategy switch, the terminal gate (which consults contract requirement satisfaction against the ledger).
Projector	The single authority that renders the prompt window each turn — deciding what context, references, and outstanding requirements the model sees. One reference grammar is shared by the projector, the recall gate, and step references, so every reference rendered into the prompt is resolvable via recall(...).

Each subsystem is fenced by a grep-able enforcement script in scripts/, so a change that reintroduces a back-edge (e.g. Assessment reading loop state directly, or a second termination owner) fails CI rather than drifting silently. The receipt’s deliverables[] and the rax diagnose replay view are both projections of this same ledger.

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
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