@reactive-agents/reactive-intelligence

Metacognitive layer for the Reactive Agents framework. v0.10.3

Real-time entropy sensing, adaptive intervention dispatch, and local learning. Monitors agent reasoning quality every iteration through 5 entropy sources, triggers interventions (early-stop, context compression, strategy switch) when the agent is struggling, and learns from outcomes via conformal calibration, Thompson Sampling, and skill synthesis.

Installation

bun add @reactive-agents/reactive-intelligence

Or via the umbrella:

bun add reactive-agents

Quick Example

import { ReactiveAgents } from "reactive-agents";

const agent = await ReactiveAgents.create()
  .withName("smart-agent")
  .withProvider("anthropic", { model: "claude-sonnet-4-20250514" })
  .withReasoning()
  .withReactiveIntelligence()
  .build();

const result = await agent.run("Analyze market trends for Q1 2026");
// EntropyScored events publish per iteration
// ReactiveDecision events fire when an intervention dispatches

Architecture

Entropy Sensor — 5 sources

| Source | What it measures | Module | | --------------------- | ------------------------------------------------------------- | --------------------------------- | | Token entropy | LLM confidence from logprobs | computeTokenEntropy | | Structural entropy | Format compliance, hedge words, thought density | computeStructuralEntropy | | Semantic entropy | Task alignment, novelty, repetition (centroid-based) | computeSemanticEntropy | | Behavioral entropy | Tool reuse, action diversity, loop detection | computeBehavioralEntropy | | Context pressure | Context-window utilization and overflow risk | computeContextPressure |

computeCompositeEntropy blends them with adaptive weights per model. computeEntropyTrajectory classifies trends as converging, flat, diverging, oscillating, or v-recovery.

Reactive Controller — interventions

Consumes entropy scores and dispatches interventions through InterventionDispatcherService. v0.10.2 ships 8 dispatched interventions plus 4 advisory signals:

• Dispatched — early-stop, context-compression, strategy-switch, temperature-adjust, tool-injection, memory-boost, skill-activation, escalate-to-human
• Advisory — surfaced as ReactiveDecision events for downstream consumers; do not directly mutate kernel state

Custom intervention handlers register via registerHandler(); the default registry lives in defaultInterventionRegistry.

Note: Earlier 0.10.x builds shipped createReactiveIntelligenceLayer without the dispatcher service wired in (resulting in 0 dispatches). v0.10.2 includes the fix — the dispatcher is part of the default layer.

Learning Engine

• Conformal calibration — computeConformalThreshold adjusts entropy thresholds to the specific model using prior observations; CalibrationStore persists per-model state
• Community profiles — fetchCommunityProfile pulls shared baselines (opt-in) so users start with reasonable thresholds
• Thompson Sampling bandit — BanditStore + selectArm / updateArm learn which strategies (ReAct, Plan-Execute, ToT, Reflexion) work best per task category
• Task classifier — classifyTaskCategory maps inputs to category labels for the bandit
• Skill synthesis — extractSkillFragment mines successful runs into reusable skill fragments (SkillFragment); injectSkill re-uses them on similar tasks

Telemetry Client

Opt-in HMAC-signed telemetry (TelemetryClient, signPayload, getOrCreateInstallId) reports anonymized run metrics to improve community calibration profiles. Fire-and-forget; never blocks the agent.

Skill Layer

SkillResolverService resolves which skills apply to a task; SkillDistillerService produces new skills from runs. Skills are tier-budgeted (SKILL_TIER_BUDGETS) and prioritized for context injection (sortByEvictionPriority).

Direct Service Usage

import { Effect } from "effect";
import {
  EntropySensorServiceLive,
  ReactiveControllerServiceLive,
  InterventionDispatcherServiceLive,
  LearningEngineServiceLive,
  createReactiveIntelligenceLayer,
} from "@reactive-agents/reactive-intelligence";

Key Features

• 5-source entropy scoring — composite signal with adaptive weights per model
• Trajectory analysis — 5 trend classifications with stable detection
• Pre-calibrated model registry — MODEL_REGISTRY ships baselines for Claude (Sonnet, Haiku), GPT-4, Gemini, Ollama (qwen3, cogito, llama variants)
• EventBus-driven — EntropyScored, ContextWindowWarning, CalibrationDrift, ReactiveDecision events publish through @reactive-agents/core EventBus
• Zero-config — .withReactiveIntelligence() enables sensing + control + learning with sensible defaults

Key Exports

| Export | Purpose | | ---------------------------------------------------------------------- | ------------------------------------------------ | | createReactiveIntelligenceLayer | Factory for the runtime layer | | EntropySensorServiceLive | Composite entropy sensor | | ReactiveControllerService, ReactiveControllerServiceLive | Decision-making loop | | InterventionDispatcherService, InterventionDispatcherServiceLive | Intervention registry + dispatcher | | LearningEngineService, LearningEngineServiceLive | Calibration + bandit + skill synthesis | | TelemetryClient, signPayload, getOrCreateInstallId | Opt-in telemetry pipeline | | BanditStore, selectArm, updateArm | Thompson Sampling primitives | | CalibrationStore, computeCalibration, computeConformalThreshold | Per-model threshold calibration | | MODEL_REGISTRY, lookupModel | Pre-calibrated model baselines | | SkillResolverService, SkillDistillerService | Skill resolution + distillation | | defaultInterventionRegistry, registerHandler | Custom intervention handlers |

Documentation

• Full docs: docs.reactiveagents.dev
• Reactive intelligence guide: docs.reactiveagents.dev/guides/reactive-intelligence/

License

MIT