Skip to content

About

Hyper-compressed, architecturally sovereign Rust micro agent runtime built on the 5-zone HEAV3NS-JOY Joyzoning architecture: 16-MiB Arena slab allocator, transactional VFS, self-healing tool parser, 23 native tools, dependency wave scheduler, and 5-scenario Agent Flight Test suite.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

31 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

HEAV3NS-MICRO (v0.1.0) — The Sovereign Intelligence Runtime

Rust Tests: 129 Passed AppKit Tests: 323 Passed Joyzoning: 100% Sovereign Hardening: Waves 4-25 Docs Guardrails: 438 Links Verified

Hyper-Compressed, Architecturally Sovereign Rust Intelligence Runtime, Double-Wrapped Spatial Action Engine & Native macOS AppKit IDE (HEAV3NS-CODE) — structured under the HEAV3NS-JOY 5-Zone Joyzoning architecture (100% Stability Index, 0 blocking violations, 0 advisories, all 343 workspace files < 800 lines Tier 1 Optimal).

Sovereign Charter (doc.md) · AGENTS.md · SOUL.md · Aspirational Roadmap · Documentation Hub · Ascendant Intelligence Paper · Project Map · Constitution · Validation Report · Native Product Spec

简体中文 · 日本語 · Tiếng Việt · Bahasa Indonesia · 한국어 · Español · Português · Русский · Українська · Français · Deutsch · 繁體中文 · हिन्दी · Türkçe · Italiano · Polski · العربية · Català

Jump to: 60-Sec Mental Model · Adoption Ladder & Drills · Visual Deep-Dives (1–8) · 5-Zone Architecture · 5 Security Rings · Quick Start


Start Here in 60 Seconds: The "Surgical Cockpit" Mental Model

If you are opening HEAV3NS-MICRO for the first time, think of it not as a single chat wrapper around an LLM, but as a surgical cockpit built from seven cooperating subsystems.

Three Golden Rules to Internalize in 10 Seconds

  1. Nothing is permanent until you say so: Plan prevents edits, /vfs + /diff drafts them in pencil, and /undo rewinds committed disk & memory state via SHA-256 CAS.
  2. One runway, many readers: Read-only tools run in parallel, while writes and turns queue cleanly in FIFO order (legacy_turn_gate, max 32 holding) so nothing collides.
  3. Trust, then verify on screen: Spatial/GUI actions ground coordinates first (Wrapper A) and prove an observable delta afterward (Wrapper B).

Tip

New to the codebase? Start in Plan posture (Shift+Tab) and run cargo run -- --flight — you can explore every tool, prompt budget, and safety gate offline with zero API calls or disk mutations.

If You Already Know X, Here Is How HEAV3NS-MICRO Maps

Familiar Engineering Concept Closest HEAV3NS-MICRO Equivalent Why It Exists
git diff + git commit SessionVfs (/vfs, /diff, /commit) Stage agent edits in memory and verify disk baseline hashes before writing.
Time-Machine Snapshot / git reset WorkspaceSnapshotCas (/undo, /restore) + ArenaAllocator Rewind files and conversation state in $O(1)$ even in non-Git folders.
Compiler AST + Browser DevTools SPIDER (environmental_diff.rs) Understand code structure, UI affordances, and modal occlusion before acting.
chmod / sudo / Seatbelt ExecutionPosture (Shift+Tab) + seatbelt_profile.rs Dial autonomy up or down per task; .heav3ns/constitution.json rules always win.
make -j Dependency Waves ToolRegistry Wave Scheduler Run reads in parallel while serializing file/shell writes to avoid races.

Note

Plain-English No-Jargon Decoder:

  • KV-Locked Prefix: The unchanging "instruction header" stays pinned in the LLM's cache so every follow-up turn is faster and cheaper.
  • SHA-256 CAS: A content-addressed vault that stores every file version once by its fingerprint, making /undo and /restore instant.
  • Seatbelt Sandbox: macOS kernel-level rules (sandbox-exec) that stop shell commands from reading secrets or escaping your workspace.
  • Joyzoning: Strict folder-by-folder import boundaries (PLUMBING -> DOMAIN <- INFRASTRUCTURE <- CORE <- UI) verified automatically by joy-check.
Pillar Everyday Analogy What It Actually Does Core Implementation
1. HEAV3NS-MICRO The Flight Computer Runs the deterministic ReAct loop with a cache-locked system prompt prefix so turns stay fast and predictable. AgentEngine, SystemPromptSpec, ContextInspectionSnapshot, ToolCallArgParser, flight_runner (FT-01..FT-05)
2. SPIDER The Structural Radar Maps code ASTs, UI affordances, and modal/occlusion relationships before anything touches disk or screen. environmental_diff.rs, EnvironmentalObservation, spider.check
3. REWIND The Time Machine Takes instant SHA-256 workspace snapshots and $O(1)$ Arena checkpoints so every edit can be /diffed, /undone, or /restored. ArenaAllocator, WorkspaceSnapshotCas, SessionVfs, TransactionJournal, VirtualDisplayState
4. BROCCOLI Long-Term Muscle Memory Remembers which workflows succeeded or failed with Laplace-smoothed confidence instead of repeating mistakes. BehavioralKnowledgeStore, LearnedWorkflowProcedure, MemoryStore, SkillTreeCatalog
5. SYNTHETIC SWARM The Specialist Council Splits complex work into non-overlapping file waves (Legion) or consults 5 GUI specialists before risky UI clicks. ComputerUseOrchestrator::consult, Legion
6. COMPUTER USE Gloved Hands + Double-Check Grounds every click/type to a safe hitbox (Wrapper A) and verifies an observable state change afterward (Wrapper B). ComputerUseOrchestrator, SpatialActionMediator, SpatialInteractionEngine, browser_use
7. THE HARNESS The Guardrails & Toolbelt Enforces your Shift+Tab safety posture, macOS Seatbelt sandbox, 31 tools, and native AppKit IDE (HEAV3NS-CODE). ToolRegistry, ExecutionPosture, seatbelt_profile.rs, TurnReceipt, stdio_worker.rs, native/

Visual Walkthrough: How a Single Turn Executes Safely

"Not an agent. Not a swarm. Not an operating system. A computational civilization of cooperating intelligence — where the system doesn't merely execute instructions: it understands its environment, learns its structure, remembers its experience, and acts with intent." — doc.md

flowchart TB
  U["1. User Intent (CLI · Native AppKit IDE · JSON-RPC v1)"] --> P["2. Posture & Constitution Gate (Ask / AcceptEdits / Plan / AutoReview / FullAccess)"]
  P --> S["3. REWIND Pre-Turn Snapshot (SHA-256 CAS + Arena Checkpoint)"]
  S --> M["4. KV-Locked Prompt + Model Router (43 Providers · OAuth / API Key)"]
  M --> W{"5. Wave Scheduler (ToolRegistry)"}
  W -->|"Read-Only Tools"| R["Parallel Read Wave (view_file · grep · spider)"]
  W -->|"Mutating Tools"| X["Serialized Write Wave (patch · shell · Seatbelt + Journal)"]
  R --> REC["6. Post-Turn Receipt (Diff · Token Cost · /undo Ready)"]
  X --> REC
Loading

Your First 5 Minutes: Adoption Ladder

Smooth your onboarding by progressing through four natural stages — you never have to adopt the whole stack at once:

flowchart LR
  S1["Stage 1: Verify & Inspect (cargo test · --flight · doctor)"] --> S2["Stage 2: Safe Read-Only (Plan Posture · /context · /prompt)"]
  S2 --> S3["Stage 3: Reversible Edits (/vfs · /diff · /commit · /undo)"]
  S3 --> S4["Stage 4: Multi-Agent & GUI (/legion · /spatial · HEAV3NS-CODE)"]
Loading
Stage Everyday Analogy Try This First What You Gain
1. Verify Offline Pre-flight instrument check cargo run -- --flight and cargo run -- doctor Zero-network proof that tools, CAS, and Joyzoning invariants work on your machine.
2. Read-Only Recon Look before you touch Cycle Shift+Tab to Plan, then run /context and /prompt Inspect exact token budgets, active tools, and prompt prefixes with zero disk mutations.
3. Reversible Editing Drafting in pencil first Stage edits with /vfs, inspect /diff, then /commit or /undo Every file change is hash-verified against disk baselines and instantly rollable back.
4. Swarm & Spatial Delegating to a crew Use /legion for parallel tasks or /spatial for GUI automation Exclusive file locks prevent worker collisions; Double-Wrapped spatial grounding prevents blind clicks.

Learn by Doing: 3 Thirty-Second Micro-Drills

Drill 1. Try This 2. Notice This 3. Concept Internalized
Drill A: Safe Recon Run cargo run -- --flight then cargo run -- context All 5 scenarios pass offline; context budget shows locked prefix + 15 core tools. Zero-trust deterministic runtime (no black-box prompts).
Drill B: Pencil -> Ink In REPL, press Shift+Tab to Plan, then AcceptEdits; try /vfs, /diff, /undo Plan blocks writes; /diff previews staged changes before /commit; /undo restores prior state. Reversible editing (REWIND + ExecutionPosture).
Drill C: Runway Queue Submit a task, then immediately queue a 2nd task while #1 runs #2 waits in HoldingPattern ([Edit | Drop]) without interrupting #1's disk state. Single-runway turn safety (RuntimeRequestQueue).

Choose Your Cockpit (3 Ways to Run)

flowchart TD
  WHO{"How do you want to work?"}
  WHO -->|"Fast Terminal Loop"| CLI["Terminal Pilot: cargo run (Interactive REPL & Slash Commands)"]
  WHO -->|"Visual Mac Workspace"| IDE["Native Cockpit: HEAV3NS-CODE (native/ AppKit Client)"]
  WHO -->|"Embed in Editor / CI"| RPC["Headless Sidecar: Stdio JSON-RPC v1 (stdio_worker.rs)"]
Loading

A Real 60-Second Bugfix Story (Putting It All Together)

flowchart LR
  B1["1. Plan Posture: Read-Only Recon"] --> B2["2. AcceptEdits: Stage Fix in /vfs"]
  B2 --> B3["3. /diff: Inspect Pencil Draft"]
  B3 --> B4["4. /commit: Write + Run cargo test"]
  B4 -->|"Pass"| B5["5. Done (TurnReceipt Saved)"]
  B4 -->|"Fail"| B6["5. /undo: Instant CAS Rewind"]
Loading

Visual Deep-Dives: How Key Subsystems Work

1. REWIND: Pencil Draft (SessionVfs) vs. Time Machine (WorkspaceSnapshotCas)

Think of VFS Staging as writing in pencil before you ink it onto disk, and CAS Snapshots as a time machine that can rewind even after ink hits disk:

flowchart LR
  EDIT["Agent Edit"] --> VFS["Pencil Draft (SessionVfs Overlay)"]
  VFS -->|"/diff"| PREVIEW["Inspect Unified Diff"]
  PREVIEW -->|"/commit"| DISK["Ink to Disk (Baseline Hash Verified)"]
  DISK -->|"/undo or /restore"| CAS["Time Machine (SHA-256 CAS + O(1) Arena Rewind)"]
  DISK -->|"FS Failure"| JRN["TransactionJournal Rollback"]
Loading

2. COMPUTER USE & SYNTHETIC SWARM: Gloved Hands + Air-Traffic Control

Instead of firing blind screen coordinates or letting parallel workers overwrite each other's files, HEAV3NS-MICRO wraps every GUI action in Double-Wrapped Verification and every swarm wave in Exclusive File Locks:

flowchart LR
  OBS["Observe Display / DOM"] --> WA["Wrapper A: Ground & Assure (Hitbox · Occlusion · Lease)"]
  WA --> ACT["Execute Input (Click / Type / Auto-Scroll)"]
  ACT --> WB["Wrapper B: Verify Observable Delta (Focus · Value · Frame)"]
  WB -->|"Confirmed"| DONE["Emit Assurance Receipt"]
  WB -->|"SuspectedNoop"| ESC["Escalate / Consult 5-Seat CUA Swarm"]
Loading
flowchart LR
  TASK["Legion Objective"] --> W1["Wave 1: Parallel Specialists (Disjoint File Locks)"]
  W1 -->|"Handoff"| W2["Wave 2: Dependent Specialists (Inherit ExecutionPosture)"]
  W2 --> MERGE["Unified Turn Receipt"]
Loading

3. BROCCOLI & Toolbelt Scaling: Muscle Memory + Pegboard vs. Rolling Tool Chest

To keep prompts fast and cache-friendly without losing power, HEAV3NS-MICRO keeps 15 core tools on an always-visible "workshop pegboard" and stores 16 specialist tools in a "rolling tool chest" (tool_search 8-slot LRU), while BROCCOLI distills repeated outcomes into calibrated priors:

flowchart LR
  PEG["Workshop Pegboard (15 Core Tools · Always in KV Prefix)"] -->|"Need Specialist"| CHEST["Rolling Chest (16 On-Demand Tools)"]
  CHEST -->|"tool_search (8-Slot LRU)"| PEG
  PEG -->|"execute_tools (Up to 32 Steps)"| BATCH["Bounded Batch Execution"]
Loading
stateDiagram-v2
  [*] --> ColdStart: New workspace
  ColdStart --> Observed: Action outcome recorded
  Observed --> Calibrated: Laplace-smoothed confidence
  Calibrated --> Procedure: Repeated success promoted
  Procedure --> GuidedTurn: Recalled by TF-IDF + BehavioralStore
  GuidedTurn --> Observed: Updated by next TurnReceipt
Loading

4. End-to-End Reversible Turn Lifecycle (sequenceDiagram)

sequenceDiagram
  participant U as User / IDE
  participant H as Harness (Posture Gate)
  participant E as AgentEngine
  participant M as LLM Provider
  participant T as ToolRegistry + Sandbox
  participant R as REWIND (CAS + Journal)

  U->>H: Submit prompt (Ask / Plan / AutoReview)
  H->>R: Capture pre-turn SHA-256 CAS snapshot
  H->>E: Start turn with KV-locked prefix
  E->>M: Stream request (preflight + 43-provider router)
  M-->>E: Tool calls (read + write)
  E->>T: Partition into parallel reads & serial writes
  T->>R: Journal pre-image & execute in Seatbelt
  T-->>E: Bounded tool results
  E-->>U: TurnReceipt (diff · cost · /undo ready)
  opt User runs /undo
    U->>R: /undo last turn
    R-->>U: Pre-load CAS blobs & restore workspace
  end
Loading

5. Native macOS AppKit IDE (HEAV3NS-CODE) Architecture

Think of HEAV3NS-CODE (native/) as the glass flight deck bolted onto the Rust engine over a multiplexed stdio JSON-RPC v1 bridge:

flowchart LR
  WIN["WorkspaceWindow (Omnibar · Posture · Composer)"] -->|"Stdio JSON-RPC v1"| RT["RuntimeClient (DispatchIO + ControlFrameReader)"]
  WIN --> VIEWS["Document · Walkthrough · Approval · Swarm · Checkpoints"]
  WIN --> STORES["ViewportStore & DraftStore (Atomic .tmp Cleanup)"]
  RT <-->|"v: 1 Framed Events"| WORKER["Rust stdio_worker.rs (32-Task Queue · Turn Gate)"]
  ACC["AccountClient (OAuth PKCE)"] <-->|"Loopback :1455"| WORKER
Loading

6. What the Cockpit HUD Looks Like in Action

┌─ HEAV3NS-MICRO v0.1.0 ── Posture: [AutoReview] (Shift+Tab) ── CAS: snap_4_a91f3c ──┐
│ Context Budget :  18,420 / 200,000 tok (9.2%)  │ KV Prefix : LOCKED (98.4% hit)     │
│ Active Tools   :  15 core + 2 unlocked (spatial_interact, browser_use)               │
│ Last Receipt   :  turn_0004 · 2 files modified · $0.014 · /diff or /undo ready       │
└──────────────────────────────────────────────────────────────────────────────────────┘

7. Clear & Present Queues: Single-Runway Air-Traffic Control

What happens if you type three follow-up instructions while the agent is still mid-turn? Nothing gets lost, and nothing collides. Think of RuntimeRequestQueue, stdio_worker.rs, and QueuedInstructions.swift as single-runway air-traffic control:

stateDiagram-v2
  [*] --> HoldingPattern: Submit while turn active (task.submit)
  HoldingPattern --> ActiveRunway: legacy_turn_gate clears (FIFO)
  HoldingPattern --> EditedOrCancelled: Edit / Cancel in QueuedInstructions
  HoldingPattern --> QueueFull: >= 32 pending (RUNTIME_QUEUE_FULL)
  ActiveRunway --> Completed: Emit TurnReceipt & CAS Snapshot
  ActiveRunway --> Guarded: Mid-turn switch blocked (TURN_IN_PROGRESS)
Loading
┌─ Instruction Queue (1 Running · 2 Waiting · Cap: 32) ────────────────────────────────┐
│  ▶ [RUNNING]  turn_0005  "Refactor auth middleware & run cargo test"                 │
│  ⏳ [QUEUED 1] req_0006   "Update CHANGELOG.md with the auth changes"  [Edit | Drop] │
│  ⏳ [QUEUED 2] req_0007   "Run joy-check --theme strict"               [Edit | Drop] │
└──────────────────────────────────────────────────────────────────────────────────────┘

8. Long-Session Context Hygiene: Carry-On Suitcase + Spillover Locker

What happens when a command dumps 10,000 lines or a session runs for 50 turns? HEAV3NS-MICRO never silently crashes or forgets your active tool call:

flowchart LR
  BIG["Huge Tool Output"] -->|"ToolOutputGovernor"| SPILL["Spillover Locker (spill_id Reference + Head/Tail Preview)"]
  HIST["Long Chat History"] -->|"SessionCompactor"| CHK["Carry-On Checkpoint (Role::User Summary · Keeps Active Tool Pairs Intact)"]
Loading

5-Zone Joyzoning Architecture (96 Rust Modules · 343 Workspace Files)

Important

The Kitchen Analogy for Joyzoning: PLUMBING is the knives and thermometers (stateless utilities), DOMAIN is the recipes and contracts (pure rules, 0% I/O), INFRASTRUCTURE is the stove and pantry (concrete I/O adapters), CORE is the head chef (orchestrating turns via domain traits), and UI is the dining room (CLI, JSON-RPC, and native macOS AppKit IDE). Dependencies flow strictly inward — never upward.

Every source file belongs to one of five strictly enforced architectural zones, verified by joy-check --theme strict:

Zone Path Responsibility & Invariants
PLUMBING src/plumbing/ (14 modules), native/... Stateless leaf primitives: hash_and_math.rs, text_tokens.rs, oauth_pkce.rs, json_repair.rs, schema_and_sse.rs, secret_redactor.rs, seatbelt_profile.rs, shell_guard.rs, fuzzy_patch.rs, vision_and_dom.rs, spatial_geometry.rs, environmental_diff.rs, display_telemetry.rs. 0 upward imports, 0 mutable state (SPI-205).
DOMAIN src/domain/ (34 modules) Pure entities & 24 port traits (interfaces/), behavioral & value types (types/, model_catalog.rs, posture_types.rs, provider_registry.rs), SystemPromptSpec, PrefixStabilityTracker, BillingMetering, TurnReceipt, ArenaAllocator, VirtualDisplayState, SpatialActionMediator, SkillTreeCatalog, MemoryStore, CompactionPolicy, SwarmAssignment, and ToolCallArgParser. 0% I/O (SPI-206), <= 3 structs/file (SPI-203).
INFRASTRUCTURE src/infrastructure/ (16 modules) Concrete I/O adapters: HttpProvider, wire_dialects, sse_and_response_parsers, CodexAccountStore, ProjectRunner, pricing_updater (ModelPricingRegistry), ScriptedProvider, SessionVfs, WorkspaceSnapshotCas, BehavioralKnowledgeStore, TransactionJournal, execute_shell_command_sandboxed, dispatch_fs_tool, and search_tools.
CORE src/core/ (23 modules) Use-case orchestration: AgentEngine, turn_orchestrator, batch_executor, context_inspector, ComputerUseOrchestrator, SpatialInteractionEngine, slash_and_swarm, SessionStore, ToolRegistry, tool_specs, ToolOutputGovernor, RuntimeRequestQueue, flight_runner, benchmark_runner, and test suites (substrate_tests, spatial_tests, computer_use_tests, zenith_tests, codewhale_zenith_tests, codex_oauth_e2e_tests, zenith_hardening_tests).
UI src/ui/ (7 modules + roots), native/ CLI presenter (cli_presenter.rs, onboarding.rs), multiplexed stdio JSON-RPC worker (stdio_worker.rs, worker_handlers.rs, provider_rpc.rs), desktop RPC router (rpc_dispatch.rs), AppKit Native Desktop IDE (native/Sources/Heav3nsCode/), and Composition Roots (lib.rs, main.rs).
flowchart LR
  UI["UI (CLI · Stdio JSON-RPC v1 · Native macOS AppKit IDE)"] --> CORE["CORE (AgentEngine · TurnOrchestrator · ToolRegistry · SpatialEngine)"]
  CORE --> DOMAIN["DOMAIN (Pure Entities · 24 Port Traits I<Name> · 0% I/O)"]
  INFRA["INFRASTRUCTURE (HttpProvider · CodexOAuth · CAS · VFS · Journal · Shell)"] --> DOMAIN
  CORE -.->|"Port Traits"| INFRA
  CORE --> PLUMB["PLUMBING (Stateless Leaf Primitives · 0 Upward Imports)"]
  INFRA --> PLUMB
Loading

"Where Does Everything Live?" Folder-to-Kitchen Map

Think of the repository like a well-run restaurant kitchen — every folder has one clear job and never crosses into another station's lane:

flowchart LR
  K["src/plumbing/ · The Knives & Prep Tools\n(Stateless text, JSON, SSE, hash & geometry helpers)"] --> R["src/domain/ · The Recipe Book\n(Pure rules, types & 24 I<Name> contracts — 0% I/O)"]
  S["src/infrastructure/ · The Stove, Fridge & Pantry\n(HTTP, Codex OAuth, Disk CAS, VFS, Journal & Shell)"] --> R
  C["src/core/ · The Head Chef\n(Orchestrates turns, tools, swarms & queues via recipes)"] --> R
  C -.->|"Orders ingredients through I<Name> ports"| S
  D["src/ui/ & native/ · The Dining Room\n(Terminal CLI, Stdio RPC & macOS AppKit Cockpit)"] --> C
Loading
If You Want to Change... Open This Folder Kitchen Rule
How text, diffs, JSON, or safety checks work src/plumbing/ Pure tools only — never reads files, network, or other zones
Core data shapes, budgets, or I<Name> contracts src/domain/ Zero I/O — recipes only, never talks to disk or network
Provider HTTP dialects, OAuth, CAS, or shell runners src/infrastructure/ Implements src/domain/interfaces/mod.rs — never touches UI
Turn loop, tool routing, swarms, or queue orchestration src/core/ Coordinates domain & I<Name> ports — never imports UI
Terminal output, JSON-RPC, or the macOS AppKit app src/ui/ · native/ Talks to core only — never reaches straight into infrastructure

Multi-Provider Routing, Wire Dialects & Auth (43 Providers)

provider_registry.rs, wire_dialects.rs, and codex_oauth.rs support multi-provider routing with ProviderChain fallback, ModelPricingRegistry live OpenRouter synchronization (12h TTL), and isolated credential handling:

flowchart LR
  REQ["Outbound Request"] --> PRE["Credential & SSRF Preflight"]
  PRE -->|"API Key"| WIRE["Wire Dialect Router (Chat / Responses / Anthropic / Gemini)"]
  PRE -->|"ChatGPT OAuth"| PKCE["CodexAccountStore (PKCE · Auto-Switch on 429)"]
  PRE -->|"Offline / --flight"| FLT["ScriptedProvider (Deterministic Replay)"]
  WIRE -->|"Fallback"| CHAIN["ProviderChain Next Endpoint"]
Loading
Wire Dialect Target Providers & Capabilities Hardening Invariants
OpenAI Chat (/v1/chat/completions) OpenAI, OpenRouter, DeepSeek, Qwen, Z.AI, MiniMax, Groq, Together, Fireworks, local OpenAI-compatible endpoints Streaming SSE delta accumulation (schema_and_sse.rs), json_repair.rs, and canonical_vendor_prefix fallback resolution.
OpenAI Responses (/v1/responses) OpenAI reasoning & responses endpoints sanitize_tool_schema_for_responses (allOf required union + dangling-key pruning) and strict schema normalization.
OpenAI Codex OAuth PKCE openai-codex via CodexAccountStore (ICodexAccountStore) Pure S256 PKCE + 127.0.0.1:1455 loopback callback, 0600 atomic persistence, single-flight AsyncMutex refresh, 429 account auto-switch.
Anthropic (/v1/messages) Anthropic Claude & *-anthropic compatible endpoints Adaptive thinking blocks, dangling tool_use repair, Role::User compaction checkpoints for strict user-first alternation.
Google Gemini & Local Gemini generateContent / SSE, Ollama, deterministic ScriptedProvider (FT-01..FT-05) Credential-unsent preflight (CREDENTIAL_REJECTED_UNSENT_CODE), SSRF/IPv6 endpoint guards, and zero-network flight replay.

Governance, Tooling & Execution Postures

Think of ExecutionPosture (Shift+Tab) as a 5-stop safety dimmer switch — you choose how much autonomy the runtime has at any moment, and fail-closed .heav3ns/constitution.json (RepoConstitution) rules always win:

flowchart LR
  ASK["1. Ask (Approve every write & shell cmd)"] --> AE["2. AcceptEdits (Auto-approve file edits · ask on shell)"]
  AE --> PLAN["3. Plan (Strict read-only recon · 0 mutations)"]
  PLAN --> AR["4. AutoReview (Autonomous inside workspace + sandbox)"]
  AR --> FA["5. FullAccess (Unrestricted · Process cred guard active)"]
Loading
  • 5-Stop ExecutionPosture (Shift+Tab): Ask -> AcceptEdits -> Plan -> AutoReview -> FullAccess enforced monotonically alongside fail-closed .heav3ns/constitution.json (RepoConstitution) across tool calls, AgentEngine::run_swarm, and handle_automation_rpc.
  • 31 Native Tools & Parallel Wave Scheduler: 15 always-loaded core tools + 16 on-demand specialist tools (tool_search 8-slot LRU + execute_tools 32-step batch) partitioned into parallel read waves and serialized mutation waves in tool_registry.rs.
  • 35 Interactive Slash Commands: Includes /mode, /posture, /preview-request, /receipts, /turn, /restore, /undo, /models, /context, /prompt, /tools, /vfs, /diff, /commit, /skills, /rewind, /doctor, /computer, /browser, /vision, /spatial, and /legion.

Command Cheat Sheet by Goal (No Memorization Required)

What You Want to Do Command / Shortcut Plain-English Analogy
Change autonomy level Shift+Tab or /posture Turn the 5-stop safety dimmer switch.
See what the model sees /context, /prompt, /preview-request Open the cockpit dashboard before takeoff.
Review staged edits safely /vfs, /diff, /commit Read your pencil draft before inking it to disk.
Undo a mistake instantly /undo, /restore, /rewind Hit the time-machine rewind button.
Switch models or providers /models Swap engines mid-flight without losing context.
Run parallel / GUI agents /legion, /spatial, /computer, /browser Dispatch the specialist crew or gloved hands.
Check architectural health /doctor Run a full diagnostic scan on the airframe.

Hardening & Reliability Guarantees (Waves 4–25)

Think of HEAV3NS-MICRO's security as five concentric airport-security & bank-vault rings — a single bypass attempt has to clear every independent ring before touching your machine or credentials:

flowchart LR
  R1["Ring 1: Input & URL Preflight (SSRF · file:// · Trojan Unicode · 64KiB Cap)"] --> R2["Ring 2: Posture & Constitution Gate (5-Stop Shift+Tab · CUA Lease/Epoch)"]
  R2 --> R3["Ring 3: Sandbox & Credential Guard (Seatbelt · ShellGuard · Env Scrub)"]
  R3 --> R4["Ring 4: Workspace Containment (16-Hop Symlink Check · Bounded I/O)"]
  R4 --> R5["Ring 5: Atomic Vault & Rollback (sync_all · CAS Pre-Load · Journal Discard)"]
Loading
  • Workspace, Sandbox & Credential Isolation: Dangling-symlink resolution (canonicalize_best_effort 16-hop read_link), lexical .. resolution in classify_sensitive_path, parent-symlink & .. rejection in SessionVfs::commit_all, child-process credential env scrubbing (SafetyPolicy::is_sensitive_env_var), @ userinfo rejection in is_safe_oauth_url, USER_CONFIG_IO_LOCK config serialization, and hardened inspect_command_security / ShellCommandGuard (16-level sh -c cap, rm normalization, bundled curl short-flag & credential-pipe Deny, sort -o/rg --pre/git -C ... -c filtering, &>/&>> heredocs, POSIX >&1/>&2/>&- handling, and macOS Seatbelt).
  • Durable Persistence, Bounded I/O & Parser Safety: sync_all() + temp-rename atomic writes across CAS blobs, manifests, and filesystem tools; fail-closed WorkspaceSnapshotCas GC and rewind_to_snapshot receipt/CAS alignment; SessionCompactor active-turn [User, Assistant(tc), Tool] preservation; ProviderChain :model override retention; bounded is_file() disk reads; $O(N)$ SSE/JSON stream parsing, UTF-8 char-boundary pagination, and overflow-safe geometry/CUA checks.
  • Turn Serialization & AppKit Lifecycle: legacy_turn_gate serialization across task.submit (32-task RUNTIME_QUEUE_FULL cap), monotonic MODEL_SELECT_SEQ gating, TURN_IN_PROGRESS guards on mid-turn conversation switches, posture-checked automation RPC routing, RuntimeClient.deinit reservation release, NSTableView row bounds guards, viewport clamping/reset on conversation switch, and client === source / closing / conversationSwitchGeneration guards across AppKit windows and stores. See CHANGELOG.md and docs/SECURITY_BEST_PRACTICES.md.

Zero-to-Ready in 3 Commands

If you want to go from a fresh clone to your first live session in under a minute, run these three steps in order:

Step Plain-English Goal Command What Success Looks Like
1 Verify offline — prove every safety & replay engine works with zero API keys cargo run -- --flight 5 deterministic flight scenarios pass locally
2 Plug in a brain — save your provider API key or sign in with ChatGPT OAuth cargo run -- init Key/OAuth stored and provider route ready
3 Open the cockpit — start talking in the terminal or launch the macOS app cargo run (or cd native && swift run) Interactive prompt or native macOS IDE opens

Quick Start & Verification

Gate Command Current Verified Baseline
1. Rust Test Suite cargo test 129 passed, 0 failed (unit, spatial, computer-use, OAuth E2E, Wave 4–25 hardening)
2. Agent Flight Suite cargo run -- --flight 5 scenarios (FT-01..FT-05, 19/19 checks passing)
3. Native macOS AppKit cd native && swift test 323 executed, 6 skipped, 0 failed
4. Joyzoning & Doctor joy-check . --theme strict / --doctor 100% Stability Index, 343 files, 0 errors, 0 warnings
5. Documentation Guardrails node bin/docs-check.mjs 72 required docs (16 ADRs, 6 playbooks, 4 wiki, 5 postmortems, 3 KB), 438 verified links
# 1. Run Rust unit, spatial, computer-use, zenith, codewhale, OAuth & hardening test suites (129 tests)
cargo test

# 2. Run Native macOS AppKit test suite (323 tests; 6 skipped)
cd native && swift test && cd ..

# 3. Inspect live prompt & context budget HUD, outbound request manifest, receipts, and Flight Suite
cargo run -- context
cargo run -- preview-request
cargo run -- receipts
cargo run -- doctor
cargo run -- --flight
cargo run -- --smoke

# 4. Run strict Joyzoning architectural audit & Stability Doctor (100% SI, Grade A+)
node /Users/bozoegg/Desktop/HEAV3NS-JOY/bin/joy-check.mjs . --theme strict
node /Users/bozoegg/Desktop/HEAV3NS-JOY/bin/joy-check.mjs . --doctor

# 5. Run documentation guardrails check
node bin/docs-check.mjs

"Wait — Why Did the Cockpit Stop Me?" (Guardrail Decoder)

When HEAV3NS-MICRO refuses an action, it is almost always protecting you from a silent hazard. Use this quick decoder:

What Happened Everyday Analogy Why It Stopped 1-Step Fix
Write/command blocked in Plan Museum "Look, Don't Touch" mode ExecutionPosture::Plan forbids all disk & shell mutations. Press Shift+Tab to cycle to AcceptEdits or AutoReview.
.env / ~/.aws / ~/.ssh refused Sealed biohazard container ModelContext credential guard blocks secret files from entering LLM context (even via cat or file://). Inspect secrets yourself locally, or pass non-sensitive mock fixtures.
Edit rejected ("stale read") Editing an outdated Google Doc tab FileReadTracker detected disk changes since the agent last read the file. Let the agent re-read the file, or run /undo if unexpected.
Symlink / .. path refused Locked emergency exit outside building Path resolves outside workspace_root or exceeds the 16-hop symlink ceiling. Keep target files inside the active workspace root.
GUI click returned SuspectedNoop Pushing a pull-only door Wrapper B saw no focus/value/frame change after clicking (e.g., modal occlusion or disabled button). Inspect the returned AssuranceReceipt or enable the prerequisite control.

60-Second Self-Check: Have You Internalized the Cockpit?

Question Quick Answer
1. How do I explore a repo with 0% risk of edits? Press Shift+Tab to select Plan posture (or run cargo run -- --flight).
2. What is the difference between /diff and /undo? /diff previews pencil-staged VFS edits before /commit; /undo rewinds already-committed CAS changes after a turn.
3. Can I send a new prompt while a turn is running? Yes — it waits safely in HoldingPattern (up to 32 queued) behind legacy_turn_gate until the active runway clears.
4. Where can I add new I/O code without breaking Joyzoning? Put the trait in src/domain/interfaces/mod.rs, the I/O adapter in src/infrastructure/, and wire it into src/core/.

Documentation Index

About

Hyper-compressed, architecturally sovereign Rust micro agent runtime built on the 5-zone HEAV3NS-JOY Joyzoning architecture: 16-MiB Arena slab allocator, transactional VFS, self-healing tool parser, 23 native tools, dependency wave scheduler, and 5-scenario Agent Flight Test suite.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages