🌱

Veil Runtime

A predictable, auditable AI agent runtime.
Kernel/userspace separation. Event-sourced state. Hard limits that cannot be bypassed.

⚡ Sub-second loop 🔒 3-tool limit per request 📜 Event Sourcing 🧠 4K token prompt budget
🌿 Why Veil?
🎯

Predictability Over Intelligence

Same inputs produce roughly the same decisions. Understandable behavior. Reproducible errors. Smart enough, not too smart.

🏰

Kernel / Userspace Isolation

Stable core never depends on experimental modules. veil-labs can observe but never control the runtime. One-way dependency only.

🛡️

Constitutional Hard Limits

Max 3 tool calls per request. Max 3 active goals. Max 50 learnings. Prompt budget at 4K chars. Determined by code, not by LLM.

✨ Core Design
🧭

Single Control Flow

One brain: AgentLoop.run(). No background threads making autonomous decisions. No hidden feedback loops.

💾

Event Sourcing

All state changes are events. StateStore rebuilds from the event log. Every mutation is traceable, replayable, auditable.

⏳

Memory Decay

TTL = 24 hours. Ring buffer max 100 events. Fresh interactions matter more. The system naturally forgets stale context.

📊

Proposal Queue

veil-labs can propose improvements, but they queue for human review. No auto-apply. No self-modification. Human in the loop.

🔐

Immutable Core

11 modules classified IMMUTABLE — changing them breaks the runtime contract. AST-based import graph locked by CI tests.

♻️

Deterministic Replay

Same event stream always produces identical StateStore snapshots. Runtime behavior is reproducible and verifiable.

🏗️ Architecture
# Kernel Space (Immutable) veil/ ├── core/ interfaces, authority, system_language ├── runtime/ kernel, loop, protocol ← Single control flow ├── state/ store, snapshot, memory ← Event Sourcing + SQLite ├── events/ types, transitions ← Immutable event schema ├── tools/ registry, executor ← MAX 3 calls/request ├── prompts/ compiler ← 4K token hard budget ├── bridge/ server, adapter ← I/O boundary ├── llm/ client ← LLM abstraction ├── persona/ config ← Personality profiles └── heartbeat/ collector, models ← Infrastructure metrics # User Space (Experimental, Sandboxed) veil-labs/ ├── goals/ GoalTracker ← Read-only observation ├── learning.py LearningStore ← 50 records max ├── diagnose.py DiagnosisEngine ← Passive analysis ├── quality.py QualityEvaluator ← Feedback scoring └── orchestrator.py SelfEvolutionLoop ← Proposal-only output # One-way dependency (law): # veil-labs → veil/core/interfaces.py (read only) # veil/core → veil-labs/* (NEVER)
📜 Design Principles
1

State is the only reality

All decisions derive from State. No hidden variables. No ambient authority. StateStore is the single source of truth.

2

Tools are the only action

The LLM cannot modify the system directly. Every action goes through a Tool — registered, validated, rate-limited.

3

Prompt is the only instruction

No hidden system directives. PromptCompilerV2 assembles context deterministically from State. Budget enforced at compile time.

4

Evolution is supervised

veil-labs can observe, diagnose, and propose. But changes flow through review + approve + apply. Never automatic.

🚀 Quick Start
📦

Clone & Install

git clone https://github.com/veil/veil.git
pip install -r requirements.txt
python main.py

🔧

Configure

Set ANTHROPIC_API_KEY in .env. Choose a persona profile. The bridge listens on :8080 by default.

⚠️

Experimental Modules

veil-labs/ is a sandbox. Tools here cannot modify the runtime. Proposals queue for human review. Read CLAUDE.md before contributing.