# Fable Agent — Architecture Reference

## Thesis

**Harness-agnostic, model-agnostic.** The harness compounds. The model executes phases.
Swap any executor, any model, any provider — the system accumulates regardless.

---

## Layer 1: Safety Stack (Pre-loop)

Every task passes through these gates before reaching the feedback loop:

```
User Input
  │
  ├── ContentSafetyGate──────────── classify risk domain
  │     cybersecurity_exploit → BLOCK
  │     harmful_content      → BLOCK
  │     financial_advice     → REFORMULATE
  │     code_generation      → ALLOW
  │
  ├── DecompositionGuard ────────── detect multi-turn attacks
  │     3+ exploit stages in 5min window → BLOCK
  │     Unicode homoglyphs → normalized before matching
  │
  ├── PromptBoundaryAdapter ─────── stay within classifier boundaries
  │     exploit-adjacent verbs → defensive equivalents
  │     Mixed domains → split with safety framing
  │
  ├── SafetyBoundary ────────────── route to available model
  │     Fable 5 / Mythos 5 → BLOCKED (export control)
  │     Opus 4.8 → orchestrator
  │     Sonnet 4.6 → bounded subtasks
  │     Haiku → grading
  │
  └── HallucinationDetector ─────── verify output against known facts
        contradiction → BLOCK
        confabulation → BLOCK
        self-contradiction → BLOCK
```

**Files:** `upgrades/content-safety-gate.ts`, `upgrades/decomposition-guard.ts`, `upgrades/prompt-boundary-adapter.ts`, `upgrades/safety-boundary.ts`, `upgrades/hallucination-detector.ts`, `upgrades/fallback-detector.ts`

---

## Layer 2: Foundation (Tier 1)

| Module | File | Purpose |
|--------|------|---------|
| SessionEngine | `tier1-foundation/session-engine.ts` | Checkpoint/resume, heartbeat stall detection, days-long autonomy |
| ContextManager | `tier1-foundation/context-manager.ts` | Sliding window, priority summarization, token budget |
| ToolOrchestrator | `tier1-foundation/tool-orchestrator.ts` | Retry with backoff, timeout, validators |

---

## Layer 3: Primitives (Tier 2)

### Loops
| Module | File | Purpose |
|--------|------|---------|
| FeedbackLoop | `tier2-primitives/loops/feedback-loop.ts` | Plan → Execute → Observe → Reflect → Refine phase machine |
| StateAccumulator | `tier2-primitives/loops/state-accumulator.ts` | Append-only event log, aggregation, trends |
| ConvergenceCheck | `tier2-primitives/loops/convergence-check.ts` | Diminishing returns, quality plateau detection |

### Workflows
| Module | File | Purpose |
|--------|------|---------|
| WorkflowGraph | `tier2-primitives/workflows/workflow-graph.ts` | DAG execution, topological sort, conditional branching |
| AdaptiveRouter | `tier2-primitives/workflows/adaptive-router.ts` | Epsilon-greedy branch selection, historical path scoring |
| RecoveryHandler | `tier2-primitives/workflows/recovery-handler.ts` | Retry, fallback, graceful degradation |

### Routines
| Module | File | Purpose |
|--------|------|---------|
| SkillRegistry | `tier2-primitives/routines/skill-registry.ts` | CRUD, versioning, tagging, search |
| ExecutionEngine | `tier2-primitives/routines/execution-engine.ts` | Deliberate practice, timing, validation |
| RoutineEvolution | `tier2-primitives/routines/routine-evolution.ts` | Analyze history, auto-suggest improvements |

---

## Layer 4: Compounding (Tier 3)

| Module | File | Purpose |
|--------|------|---------|
| StateRepository | `tier3-compounding/state-repository.ts` | Cross-session knowledge base, tagging, compaction |
| SkillSharpener | `tier3-compounding/skill-sharpener.ts` | Meta-review, quality gate, auto-apply improvements |
| MetaAgent | `tier3-compounding/meta-agent.ts` | Orchestrator: select → execute → sharpen → store → compound |

---

## Layer 5: Upgrades (Elite Patterns)

| Pattern | File | Purpose |
|---------|------|---------|
| Dreaming | `upgrades/dreaming-system.ts` | Sleep → review → extract → codify → dream |
| Self-Validation | `upgrades/self-validator.ts` | Per-phase quality gates, auto-retry on failure |
| Multi-Agent | `upgrades/multi-agent.ts` | Orchestrator → specialists → collect → verify |
| Rubric Engine | `upgrades/rubric-engine.ts` | N-criteria evaluation, dynamic exit conditions |
| Persistent Memory | `upgrades/persistent-memory.ts` | Episodic + Semantic + Procedural partitions |
| Enhanced Meta | `upgrades/enhanced-meta-agent.ts` | Full Dream → Act → Validate → Codify loop |
| Vision Check | `upgrades/vision-self-check.ts` | Automated visual verification via vision model |
| Scheduler | `upgrades/routine-scheduler.ts` | Cron-like task scheduling |
| Goal Queue | `upgrades/goal-queue.ts` | Persistent priority queue |
| Daemon | `upgrades/daemon-engine.ts` | 24/7 autonomous loop, auto-resume, auto-benchmark |
| Benchmark | `upgrades/benchmark-runner.ts` | Measure compounding trends |
| Cost Tracker | `upgrades/cost-tracker.ts` | Per-call/per-model/per-session cost |
| Cost Cap | `upgrades/cost-cap.ts` | Hard budget limits, auto-pause |
| Skill Sync | `upgrades/skill-sync.ts` | Two-way SKILLS/ markdown ↔ TS registry |
| Exa Search | `upgrades/exa-search.ts` | Web search + company research |
| Env Loader | `upgrades/env-loader.ts` | .env loading, no dependencies |
| Fallback Detector | `upgrades/fallback-detector.ts` | Detect silent model fallback |
| Familiar Knowledge | `upgrades/familiar-knowledge.ts` | inbox → wiki processing pipeline |
| PAI Adapter | `upgrades/pai-adapter.ts` | PAIMM / TELOS / LifeOS mapping |
| AI SDK Adapter | `upgrades/ai-sdk-adapter.ts` | AI SDK v7 harness interface |

---

## Layer 6: Executors

| Executor | File | Interface | Model |
|----------|------|-----------|-------|
| Antigrav | `examples/executors/antigrav-executor.ts` | `agy --print` | gemini-2.5-pro |
| Claude Code | `examples/executors/cc-executor.ts` | `claude -p` | claude-sonnet-4-6 |
| Codex | `examples/executors/codex-executor.ts` | `codex` or `pi --provider codex` | codex |
| Composite | `examples/executors/composite-executor.ts` | multi-model routing | per-phase |
| Fable5 | `examples/executors/fable5-executor.ts` | effort levels | opus-4-8 |
| Grok | `examples/executors/grok-executor.ts` | `grok -m grok-3 -p` | grok-3 |
| Kimi | `examples/executors/kimi-executor.ts` | Kimi API | kimi-k2.6 |
| Local | `examples/executors/local-executor.ts` | OAI-compatible | Ollama/vLLM |
| OpenAI | `examples/executors/openai-executor.ts` | OpenAI API | gpt-4.1 / o3 |
| OpenCode | `examples/executors/opencode-executor.ts` | `opencode -p` | via proxy :18901 |
| Pi | `examples/executors/pi-executor.ts` | `pi --print` | 324 models |
| Sonnet | `examples/executors/sonnet-executor.ts` | Anthropic API | claude-sonnet-4-6 |
| Weak-to-Strong | `examples/executors/weak-to-strong.ts` | bootstrap | any |

---

## Layer 7: Bridges

| Bridge | File | Connects |
|--------|------|---------|
| PAI-FA | `pai/pai-fa-bridge.ts` | PAI TELOS → FA rubric, PAI memory → FA memory |
| PAI-Pi | `pai/pai-pi-bridge.ts` | PAI Pi release (4035-char prompt, 9 skills) → FA |
| AI SDK | `upgrades/ai-sdk-adapter.ts` | Fable Agent ↔ AI SDK v7 harness ecosystem |

---

## Layer 8: Pre-existing Modules

| Module | Directory | Contents |
|--------|-----------|---------|
| PAI | `pai/` | TELOS bridge, ISA writer, memory progression, proxy client, skill sync |
| Fable5 | `fable5/` | Model router, independent verifier, goal pattern, agent chains, meta-agent, agent teams, worktree isolation, state file, compound stack |

---

## Data Flow

```
                    ┌─────────────────────────────┐
                    │        User / CLI            │
                    └──────────┬──────────────────┘
                               │ task
                    ┌──────────▼──────────────────┐
                    │     SAFETY STACK (4 gates)   │
                    │  content → decomp → adapt →  │
                    │  route → hallucination check  │
                    └──────────┬──────────────────┘
                               │ safe task
                    ┌──────────▼──────────────────┐
                    │     FEEDBACK LOOP            │
                    │  plan → execute → observe →  │
                    │  reflect → refine            │
                    │  (rubric evaluates each iter)│
                    └──────────┬──────────────────┘
                               │ iteration results
                    ┌──────────▼──────────────────┐
                    │     ACCUMULATOR              │
                    │  store → aggregate → trend   │
                    └──────────┬──────────────────┘
                               │ converged?
                    ┌──────────▼──────────────────┐
                    │     DREAM CYCLE              │
                    │  every 3 goals: review →     │
                    │  extract → distill → codify  │
                    └──────────┬──────────────────┘
                               │ skill improvements
                    ┌──────────▼──────────────────┐
                    │     MEMORY                   │
                    │  episodic (what happened)    │
                    │  semantic (what it means)    │
                    │  procedural (how to do it)   │
                    └──────────┬──────────────────┘
                               │ accumulated state
                    ┌──────────▼──────────────────┐
                    │     KNOWLEDGE                │
                    │  state repo / familiar wiki  │
                    │  / STATE.md / SKILLS/        │
                    └─────────────────────────────┘
```

## CLI Map

```
fable-agent run <task>           → Safety stack → Feedback loop → Memory
fable-agent demo                 → Exa search → Register skill → Loop → Sharpen
fable-agent daemon start --detach → 24/7 loop with auto-resume + auto-benchmark
fable-agent daemon queue <goal>  → Priority queue → Daemon picks → Execute
fable-agent familiar capture     → inbox/ .md
fable-agent familiar process     → inbox/ → wiki/ + auto git commit
fable-agent familiar graph       → [[wikilinks]] → knowledge graph
fable-agent benchmark run        → 3 benchmarks → Trend report
fable-agent learned              → Every storage layer → Full knowledge report
fable-agent exa search           → Exa API → Results → Knowledge base
fable-agent skills sync          → SKILLS/ markdown ↔ TS registry
fable-agent pai-pi run <goal>    → PAI Pi prompt + Pi executor → FA loop
```

## File Inventory

```
~/fable-agent/
├── 86 source files     (src/ — all layers)
├── 5 test files        (43 tests)
├── 13 executors        (examples/executors/)
├── 25 upgrade modules  (upgrades/)
├── 7 pre-existing      (pai/ + fable5/)
├── 6 root docs         (README.md, AGENT.md, CONFIG.md, STATE.md, ARCHITECTURE.md, PHASES/)
├── 6 skill dirs        (SKILLS/)
├── 14 phase defs       (PHASES/)
├── Dockerfile          (deployable)
├── .github/            (CI/CD)
├── deploy/             (systemd + PM2)
└── .env.example        (all config vars)
```

## Version

**0.0.1** — architecture-complete. Every pattern from every source implemented.
All 14 roadmap steps. All Fable 5 elite patterns. All safety layers. All executors.
All bridges. Deployment ready. The harness, not the model.