git:20260721.6379e94 to git:20260819.8eb1198

---

name: architecture-reference

description: Reactive Agents framework architecture — layer stack, dependency graph, build order, and package structure. Use when planning work, understanding package relationships, or determining build dependencies.

user-invocable: false

---

# Architecture Reference — Reactive Agents

>

> **For architectural questions, prefer `claude-obsidian:wiki-query "<topic>"`** over reading individual files. The wiki has MOCs, decisions, mechanism validations, and design specs that surface in semantic queries. See [[wiki/Development/Wiki-Workflow|Wiki-Workflow.md]] for the canonical pattern.

## Wiki Resources for Architecture Lookup

| Question | Where to look |

|----------|---------------|

| "Why was decision X made?" | `wiki/Decisions/Decision Index.md` |

| "What package contains Y?" | `wiki/Packages/00 Package Index.md` |

| "Has mechanism Z been validated?" | `wiki/Experiments/M*.md` (or `wiki/Experiments/by-verdict.base`) |

| "What failure modes apply here?" | `wiki/Failure-Modes/by-severity.base` |

| "Current empirical state?" | `wiki/Architecture/Specs/04-PROJECT-STATE.md` |

| "Roadmap for v1.0?" | `wiki/Architecture/Specs/07-ROADMAP-v1.0.md` |

## Package Dependency Graph

**Zero internal deps:**

- `@reactive-agents/core` — EventBus, types, Agent/Task services

- `@reactive-agents/runtime-shim` — unified Bun/Node.js primitives; consumed by memory, tools, health, judge-server

**Depends on core only:**

- `@reactive-agents/llm-provider` → `core`

- `@reactive-agents/observability` → `core`

- `@reactive-agents/identity` → `core`

- `@reactive-agents/a2a` → `core`

- `@reactive-agents/interaction` → `core`

- `@reactive-agents/observe` → `core` — OpenInference/OTel span exporter

**Depends on core + llm-provider:**

- `@reactive-agents/memory` → `core`, `llm-provider`

- `@reactive-agents/tools` → `core`, `llm-provider`

- `@reactive-agents/guardrails` → `core`, `llm-provider`

- `@reactive-agents/cost` → `core`, `llm-provider`

- `@reactive-agents/eval` → `core`, `llm-provider`

- `@reactive-agents/prompts` → `core`, `llm-provider`

**Higher layers:**

- `@reactive-agents/reasoning` → `core`, `llm-provider`, `memory`, `tools`

- `@reactive-agents/verification` → `core`, `llm-provider`, `memory`

- `@reactive-agents/gateway` → `core`, `llm-provider`, `tools`

- `@reactive-agents/reactive-intelligence` → `core`, `llm-provider`

- `@reactive-agents/replay` → `core`, `trace`, `runtime` — deterministic trace replay

- `@reactive-agents/compose` → `core`, `runtime` — harness composition + 6 killswitches

**Planned (branch `feat/channels-package`, not merged to `main`):**

- `@reactive-agents/channels` → `core`, `gateway` (external triggers, session bridge, webhook adapter); consumed by `@reactive-agents/runtime` via **`.withChannels()`** and optional dynamic import at `start()`. Gateway **`channels` → `accessControl`** rename separates sender policy from chat/task mode. See `wiki/Research/Debriefs/2026-05-03-channels-phase1-development-debrief.md`.

**Facade (depends on ALL):**

- `@reactive-agents/runtime` → all packages (composes layers via `createRuntime()`)

- `reactive-agents` → `runtime` (public API re-export)

**Private (never published):**

- `@reactive-agents/testing` → `core`, `llm-provider`

- `@reactive-agents/benchmarks` → `runtime`

- `@reactive-agents/health` → `core`

## Build Order

Build runs in dependency order. Lower layers must build before higher layers.

```

Phase 1: core → llm-provider

Phase 2: memory, tools, guardrails, cost, identity, observability, interaction, prompts, eval, a2a (parallel)

Phase 3: reasoning, verification, orchestration, gateway, reactive-intelligence (parallel)

Phase 4: runtime → reactive-agents (facade)

Phase 5: testing, benchmarks, health, cli, docs (parallel)

```

## ExecutionEngine 10-Phase Loop

```

Phase 1: BOOTSTRAP MemoryService.bootstrap(agentId)

Phase 2: GUARDRAIL GuardrailService.checkInput(input)

Phase 3: STRATEGY-SELECT AdaptiveStrategy or config.defaultStrategy

Phase 4: THINK ReasoningService.execute() → kernel loop

Phase 5: ACT (synthetic — extracted from reasoning steps)

Phase 6: OBSERVE (synthetic — extracted from reasoning steps)

Phase 7: MEMORY-FLUSH MemoryExtractor + MemoryService.snapshot()

Phase 8: VERIFY VerificationService.verify(result) [optional]

Phase 9: AUDIT AuditService.log() [optional]

Phase 10: COMPLETE EventBus.publish("AgentCompleted") + DebriefSynthesizer

```

## Kernel Architecture (Reasoning)

All 6 strategies delegate to `runKernel(reactKernel, input, options)` in `packages/reasoning/src/kernel/`.

### Composable Phase Pipeline

```

makeKernel({ phases?: Phase[] })

↓

kernel-runner.ts: runKernel() loop

↓ per turn:

1. context-builder.ts — buildSystemPrompt, toProviderMessage, buildConversationMessages, buildToolSchemas (pure data, no LLM)

2. think.ts — LLM stream, FC parsing, fast-path, loop detection, oracle hard gate

3. guard.ts — Guard[] pipeline, checkToolCall(guards), defaultGuards[]

4. act.ts — MetaToolHandler registry, final-answer gate, tool dispatch

```

### Key Files

```

packages/reasoning/src/kernel/

kernel-state.ts — KernelState, Phase type, KernelContext, ThoughtKernel

kernel-runner.ts — the loop: runKernel() — DO NOT add per-turn logic here directly

kernel-hooks.ts — KernelHooks lifecycle hooks

react-kernel.ts — makeKernel() factory + reactKernel + executeReActKernel

phases/

context-builder.ts — pure data: builds what the LLM sees this turn

think.ts — LLM decision: stream, FC parsing, loop detection

guard.ts — Guard[] pipeline: is this tool call allowed?

act.ts — MetaToolHandler registry: what happens when tools run?

utils/

ics-coordinator.ts, reactive-observer.ts, loop-detector.ts

tool-utils.ts, tool-execution.ts, termination-oracle.ts, strategy-evaluator.ts

stream-parser.ts, context-utils.ts, quality-utils.ts, service-utils.ts, step-utils.ts

```

### Two Independent State Records

```

state.messages[] ← What the LLM sees (multi-turn FC conversation thread)

state.steps[] ← What systems observe (entropy, metrics, debrief)

```

Do NOT conflate these. Debugging LLM behavior → inspect `messages[]`. Debugging metrics/entropy → inspect `steps[]`.

### Extending the Kernel

- **New phase**: create `phases/<name>.ts`, insert into `makeKernel({ phases: [...] })`

- **New guard**: add `Guard` fn to `guard.ts`, add to `defaultGuards[]`

- **New inline meta-tool**: add one entry to `metaToolRegistry` in `act.ts`

- **Custom kernel**: `makeKernel({ phases: [myThink, act] })`

See `.agents/skills/kernel-extension/SKILL.md` for full patterns.

### Context Assembly — Canonical Path

- `context-manager.ts` — `ContextManager.build(state, input)` returns `{ systemPrompt, messages }` (pure, deterministic)

- `context-builder.ts` — assembles raw conversation messages (`buildConversationMessages`), tool schemas, system prompt base

- `think.ts` — invokes `buildGuidanceSection(state.pendingGuidance)` and appends `Guidance:` block to system prompt

- `context-engine.ts` — retains only `buildStaticContext`, `buildEnvironmentContext`, `buildRules`; all dynamic/scoring code removed

## MCP Client Architecture

Location: `packages/tools/src/mcp/mcp-client.ts`

### Two Docker Patterns

| Pattern | Examples | Behavior |

|---------|---------|----------|

| stdio MCP | GitHub MCP, filesystem | Container reads JSON-RPC from stdin |

| HTTP-only | mcp/context7 | Container starts HTTP server, ignores stdin |

Both handled transparently via auto-detection.

### Critical Rules

- **`docker rm -f <containerName>` is the ONLY reliable container stop.** `subprocess.kill()` leaves the container alive in the Docker daemon.

- **Two-phase container naming**: `rax-probe-<name>-<pid>` (initial stdio probe) → `rax-mcp-<name>-<pid>` (port-mapped HTTP if HTTP detected)

- **PID in name** prevents conflicts between concurrent agents running the same MCP server

- **Transport auto-inferred**: `command` → `"stdio"`, endpoint `/mcp` → `"streamable-http"`, other endpoint → `"sse"`

- `transport` field is optional in `MCPServerConfig` — auto-inferred at runtime

See `.agents/skills/mcp-integration/SKILL.md` for full patterns.

## Technology Stack

| Decision | Choice |

|----------|--------|

| Language | TypeScript (strict mode) |

| Runtime | Bun >= 1.1 |

| FP framework | Effect-TS (^3.10) |

| Database | bun:sqlite (WAL mode), FTS5, sqlite-vec |

| LLM providers | Anthropic, OpenAI, Ollama, Gemini, LiteLLM (40+) |

| Module system | ESM ("type": "module") |

| Build | tsup (ESM + DTS) |

| Test | bun:test |

| Versioning | Changesets (fixed group) |

## Quick Navigation

| What you need | Where to look |

|--------------|---------------|

| Full file-level system map | `wiki/Architecture/Framework-Architecture-Index.md` |

| Coding standards | `CODING_STANDARDS.md` |

| Effect-TS patterns | `.agents/skills/effect-ts-patterns/SKILL.md` |

| LLM API signatures | `.agents/skills/llm-api-contract/SKILL.md` |

| Memory/SQLite patterns | `.agents/skills/memory-patterns/SKILL.md` |

| Spec documents | `spec/docs/` |

| Build commands | `AGENTS.md` (Build & Test Cycle) and `README.md` (quickstart/dev commands) |

| Extending the kernel | `.agents/skills/kernel-extension/SKILL.md` |

| Debugging agent behavior | `.agents/skills/kernel-debug/SKILL.md` |

| Provider streaming patterns | `.agents/skills/provider-streaming/SKILL.md` |

| MCP client patterns | `.agents/skills/mcp-integration/SKILL.md` |

| Full feature workflow | `.agents/skills/reactive-feature-dev/SKILL.md` |