Concepts

From passive prompts to reactive state machines

Traditional passive skills dump monolithic instructions into context. Agents attempt to remember prior turns and self-police progress without execution boundaries or verifiable checkpoints.

Reactive Skills structures execution as a formal Hierarchical State Machine (HSM). The agent receives an isolated prompt slice for the active state, evaluates deterministic guard expressions before transitions, and records all transitions to an append-only event ledger.

States & prompt isolation

Skills advance through named states such as PLAN, EXECUTE, and composite REFACTOR. Instead of loading the entire skill manual, agents receive only the prompt slice for the active state (states/*.md). This context isolation prevents attention drift and cuts token waste.

Signals and ancestor bubbling

Signals are typed payloads dispatched from the agent harness, AXI CLI, or MCP. If a leaf substate has no handler for an incoming signal, the event bubbles up the hierarchy to ancestor states. This eliminates boilerplate across substates for global policies like rollbacks, aborts, and timeouts.

Deterministic guard gates

Guards evaluate context facts (e.g. exit_code == 0, schema checks, artifact existence) deterministically. The runtime prevents transitions on subjective model claims, ensuring reproducible execution and verifiable progress.

PLAN --[ guard: plan.approved ]--> EXECUTE

Decoupled Judgment Engine & Snap-On Adapters

When deterministic boolean assertions are not enough (e.g. assessing semantic criteria like "Did the security scan identify zero critical CVEs?"), RSA provides a decoupled Judgment Engine adhering to SASH / Hexagonal Ports-and-Adapters principles.

The core runtime includes the TypeSafe SDK needed for semantic judgments, but only makes network calls when TYPESAFE_API_KEY is configured. Transitions declare domain-level semantic contracts (predicate, categorical, or evaluation) which the runtime delegates to registered Judgment Adapters:

• ScriptJudgmentAdapter: Built-in default (<1ms) providing deterministic sandboxed heuristic evaluation with zero configuration.
• JevJudgmentAdapter: Direct integration with TypeSafe AI's System One decision model through @typesafe-ai/sdk. It requires TYPESAFE_API_KEY, does not invoke jev-axi, and preserves Script fallback behavior when unavailable.
• Circuit Breaker & Fallbacks: Resilient evaluation wraps external calls in a circuit breaker. If an adapter times out or trips, the FSM transitions directly to a declared fallback_target (e.g. BLOCKED or MANUAL_REVIEW) and audits GUARD_FALLBACK_TRIGGERED into the event ledger.

# skill.yaml transition contract
transitions:
  SECURITY_CLEAN:
    target: "SPEC_ALIGNMENT"
    judgment:
      type: "predicate"
      criterion: "Did the security scan confirm zero leaked API keys and no high-severity vulnerabilities?"
      min_confidence: 0.85
      fallback_target: "BLOCKED"

Semantic Model Capability Tiers

Not every state requires a flagship frontier model. RSA enables per-state cognitive tier declarations in skill.yaml so orchestrators and agents can dynamically allocate model budgets:

• fast: Low latency, low cost for structured triage, lint parsing, and state setup (e.g. Claude Haiku, Gemini Flash).
• balanced: Standard coding, refactoring, and deterministic implementations (e.g. Claude Sonnet, GPT-4o).
• reasoning: Deep architectural decisions, invariant proofs, and root-cause analysis (e.g. Claude Opus, OpenAI o3, Gemini Pro).
• decision: Specialized micro-decision models trained for sub-second classification (e.g. TypeSafe Jev).

When an agent enters a state, the runtime injects a structured <model_contract> tag into the prompt slice, declaring the required tier, suggested models, and cost bounds.

Event sourcing and projections

Every signal dispatch, guard evaluation, and state transition appends to an immutable ledger (.reactive/skills/<skill>/events.jsonl + SQLite). Current state, history, and workspace deliverables are computed read-model projections folded from the event ledger.

Isolated skill storage

Each skill maintains dedicated state and event storage. Skill executions never cross-contaminate. SQLite provides ACID durability and indexed replay, while JSONL logs ensure human-readable auditability.

Parent runs summarize child failures

Skills can invoke child skills hierarchically. When a child skill encounters a guard rejection or unhandled signal, the parent run folds the child’s events into a structured summary and surfaces the exact recovery action inline.

Agent interfaces: AXI & MCP

Reactive skills expose two host interfaces. During INIT, the runtime checks local capabilities and versions, selects a compatible AXI or MCP transport, and persists that choice for the run.

Interactive State Machine Simulator

Simulate state transitions, ancestor signal bubbling, guard evaluations, and event stream persistence directly in the browser.