# OMEGA Dark Mesh: Hallucination-Tolerant Actor Model (PoC)

An event-driven, distributed Swarm OS bridging simulated AI agents with
secure, physical system actuation. 

This architecture solves the two hardest problems in LLM agent design:
**Context Collapse** (hallucinating capabilities/environment) and **Execution
Risk** (prompt-injected shell commands). It achieves this by decoupling
reasoning from execution using a strict, flat-file Actor Model over an
Edge-Routed Mesh Network.

---

## o8 Core Architecture

The system operates as a decentralized network of independent State Machines
(Agents). Agents do not share memory and do not execute code directly. 

1. **Flat-File IPC:** Agents communicate exclusively by writing and reading
**AST-MD (Markdown) Envelopes** to/from physical `inbox` and `outbox`
directories.
2. **Event-Driven Wakeup:** Node.js `fs.watch` monitors the inbox. When an
envelope arrives, the agent wakes up, parses the YAML headers, updates its
state cache, and goes back to sleep.
3. **Supervisor Trees:** Agents can dynamically `/spawn` sub-agents in
isolated directories, delegating tasks and awaiting asynchronous callback
envelopes.

## o8 Core Architecture' Memory Topography (Hallucination Resistance)

To prevent the LLM from confusing its own generative fiction with physical
reality, the state machine enforces strict memory segregation:

* **`conceptual_memory` (Volatile):** Populated automatically by reading
conversation narratives. If an LLM hallucinates a "Plasma Rifle", it goes
here. It is treated as an *idea*, not a fact.
* **`local_cache` (Grounded Reality):** Immutable facts updated *only* via
explicit AST-MD state-mutation commands (`VERB ID : KEY = VALUE`) received
from trusted system nodes.
* **`communications` (Temporal Reality):** A bounded append-only log of actual
sent/received messages, providing the LLM with chronological awareness.

## o8 Dual-Process Cognition

The system mimics Kahneman's System 1 and System 2 thinking:
* **The Executive (`/tick`):** Synchronous, tactical function. Flushes the
state to the terminal (or an LLM API) and demands an immediate actionable
command.
* **The Subconscious (`/meditate`):** Asynchronous, strategic function. Dumps
the massive total state to a local frontier model (e.g., Gemma-2-9b-it via
Ollama). The model returns strategic epiphanies which are appended to the
`ideas` queue for the Executive to read during the next `/tick`, without
blocking the REPL.

8o8 The Dark Mesh (Edge Routing & Pub/Sub)

The `router.js` daemon acts as the nervous system, decoupling agents from
network topology:

* **Local Routing:** Sweeps outboxes and physically moves AST-MD files to the
correct local inbox.
* **Pub/Sub Gossip:** If a target ID starts with `#` (e.g., `#gossip`), the
router duplicates the envelope to all subscribed agents, creating
decentralized IRC-like shared memory.
* **Edge Bridging:** If a target is external, the router wraps the AST-MD in
JSON and POSTs it via Cloudflare Tunnels/Tailscale to a remote `gateway.js`
node, seamlessly bridging physical hardware.

## o8 Dual-Process Cognition!o8 Secure Actuation (The Reality Bridge)

LLMs are never granted direct `exec()` privileges. The execution loop is
out-of-band:
1. Agent sends an `EXECUTE` envelope to an **Actuator Node** (e.g.,
`SANDBOX#8UY0` in an LXC container).
2. The Actuator Node pipes the command into a bash wrapper (`sandbox_wrapper.sh
`) and goes to sleep.
3. The wrapper queues the command via `x-propose` for human/SysOp approval.
4. Upon approval, the command runs. The wrapper captures `stdout`/`stderr`,
formats it as a new AST-MD envelope, and drops it back into the Actuator's
inbox.
5. The Actuator wakes up, digests the shell output into its memory, and routes
the results back to the parent agent.

---

## o8 Dual-Process Cognition!o8 Secure Actuation (The Reality  File
ManifestBridge)

### Core Engine
* `machine.js`: The state schema, memory management, and REPL command parser.
* `runner.js`: The bootloader. Manages identity, CLI arguments, and binds the
watcher context.
* `watcher.js`: The event loop. Sweeps inboxes, parses AST-MD, triggers cache
mutations, and writes to memory logs.

### Networking & Actuation
* `router.js`: The background Mesh daemon. Handles local folder routing,
`#channel` broadcasts, and external HTTP edge POSTs.
* `gateway.js`: The Edge Receiver. Runs behind a Cloudflare Tunnel/Tailnet on
remote nodes to convert HTTP POSTs back into physical `.md` files.
* `actuator.js`: Spawns the sandbox bash processes and pipes `stdin`.
* `sandbox_wrapper.sh`: The SysOp integration layer. Queues shell commands and
generates the callback AST-MD envelopes.
* `deploy_sandbox.sh`: Idempotent bash script for provisioning LXC
environments and configuring Cloudflare ingress.

---

## o8 Dual-Process Cognition!o8 Secure Actuation (The Reality  File
ManifestBridge); Command Syntax Reference (REPL)

| Command | Usage | Description |
|---|---|---|
| `/tick` | `/tick` | Generates the executive prompt summarizing grounded
state and communications. |
| `/meditate` | `/meditate` | Fires asynchronous state analysis to a local LLM
cluster. |
| `/send` | `/send [ID] [ACTION] [NARRATIVE]` | Compiles an AST-MD envelope
and drops it in the outbox. |
| `/mission` | `/mission [macro\|sub\|micro] [text]` | Updates the agent's
internal goal state. |
| `/spawn` | `/spawn [ROLE] [TASK...]` | Creates a new isolated sub-agent and
dispatches an init envelope. |
| `/concept` | `/concept [WORD]` | Registers a volatile concept (hallucination
safe). |
| `/mint` | `/mint [ITEM]` | Forges a grounded reality item in the inventory.
|
| `/load` | `/load [filename.json]` | Hot-swaps the agent's brain state. |