@agentikos/omega-os 0.19.33 → 0.19.34

package/omega/Agentik_Engine/omega_engine/__init__.py

@@ -188,7 +188,7 @@ from omega_engine.genesis import (
 )
 from omega_engine import plan as plan_v7
 
-__version__ = "0.19.33"
+__version__ = "0.19.34"
 
 __all__ = [
     "__version__",

package/omega/Agentik_Engine/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "omega-engine"
-version = "0.19.33"
+version = "0.19.34"
 description = "The Omega OS orchestration engine — event-sourced, verified-completion agent graphs."
 readme = "README.md"
 requires-python = ">=3.11"

package/omega/Agentik_Engine/tests/test_paperclip_bridge.py

@@ -0,0 +1,139 @@
+"""Regression tests for omega_engine.paperclip_bridge — locks in the
+14-agent contract and the reporting-line invariants documented in
+FEATURE-MATRIX.md §8 (AISB rules)."""
+from __future__ import annotations
+
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from omega_engine import paperclip_bridge as P
+
+
+class TestAgentInventory(unittest.TestCase):
+    """Lock in the AISB contract — 14 agents total, fixed reporting."""
+
+    def test_exactly_14_agents(self):
+        """Hermès + 13 AISB suite = 14. Not 13, not 15."""
+        self.assertEqual(len(P.all_agents()), 14,
+            "the AISB contract requires exactly 14 agents — "
+            "if you added/removed one, update FEATURE-MATRIX.md §8 first")
+
+    def test_hermes_first_and_top(self):
+        agents = P.all_agents()
+        self.assertEqual(agents[0]["id"], "hermes")
+        self.assertIsNone(agents[0]["reports_to"],
+            "Hermès must be at the top of the org chart")
+
+    def test_aisb_suite_has_13(self):
+        self.assertEqual(len(P.AISB_AGENTS), 13)
+
+    def test_all_reporting_lines_valid(self):
+        """Every non-None reports_to must point to an actual agent_id."""
+        agents = P.all_agents()
+        ids = {a["id"] for a in agents}
+        for a in agents:
+            rt = a.get("reports_to")
+            if rt is not None:
+                self.assertIn(rt, ids,
+                    f"{a['id']} reports to {rt!r} which is not in the catalog")
+
+    def test_niobe_reports_to_hermes(self):
+        niobe = next(a for a in P.AISB_AGENTS if a["id"] == "niobe")
+        self.assertEqual(niobe["reports_to"], "hermes")
+
+    def test_oracle_reports_to_niobe(self):
+        oracle = next(a for a in P.AISB_AGENTS if a["id"] == "oracle")
+        self.assertEqual(oracle["reports_to"], "niobe")
+
+    def test_construct_reports_to_oracle(self):
+        c = next(a for a in P.AISB_AGENTS if a["id"] == "construct")
+        self.assertEqual(c["reports_to"], "oracle")
+
+
+class TestCredentialIsolation(unittest.TestCase):
+    """L0-L5 credential domains must not bleed. Specifically:
+       - Hermès uses ANTHROPIC_API_KEY_HERMES (vault)
+       - The 13 AISB agents must NOT declare any Anthropic API key
+         (they share Claude Max OAuth from ~/.claude/.credentials.json)."""
+
+    def test_hermes_uses_anthropic_key(self):
+        self.assertEqual(P.HERMES_AGENT["vault_secret"],
+                         "ANTHROPIC_API_KEY_HERMES")
+        self.assertEqual(P.HERMES_AGENT["runtime"], "anthropic-api")
+
+    def test_aisb_agents_do_not_declare_api_keys(self):
+        for a in P.AISB_AGENTS:
+            self.assertNotIn("vault_secret", a,
+                f"{a['id']} must not declare its own API key — AISB+Oracle+"
+                "Workers share the Claude Max OAuth at the engine level")
+            self.assertNotIn("runtime", a,
+                f"{a['id']} must not declare a runtime — runs as a "
+                "Claude Code subprocess under Max OAuth")
+
+
+class TestRegisterDryRun(unittest.TestCase):
+    """The register() entry point — dry-run mode must report what it
+    would write without touching disk."""
+
+    def test_dry_run_writes_nothing_to_disk(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            pdir = Path(tmp) / "companies" / "omegaos"
+            summary = P.register(paperclip_dir=pdir, dry_run=True)
+            self.assertFalse(pdir.exists(),
+                "dry_run=True must not create the company dir")
+            self.assertEqual(summary["agents_written"], 14)
+
+    def test_register_writes_14_agent_files(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            pdir = Path(tmp) / "companies" / "omegaos"
+            summary = P.register(paperclip_dir=pdir, dry_run=False)
+            # company.json
+            self.assertTrue((pdir / "company.json").exists())
+            company = json.loads((pdir / "company.json").read_text())
+            self.assertEqual(company["id"], "omegaos")
+            self.assertEqual(company["agent_count"], 14)
+            # 14 agent files
+            agent_files = list((pdir / "agents").glob("*.json"))
+            self.assertEqual(len(agent_files), 14,
+                f"register must write 14 agent files (got {len(agent_files)})")
+            # .bridge-version
+            self.assertTrue((pdir / ".bridge-version").exists())
+            self.assertEqual(summary["agents_written"], 14)
+
+
+class TestHeartbeat(unittest.TestCase):
+    """Heartbeat must drop a JSON file when no HTTP server is configured."""
+
+    def test_filesystem_fallback_writes_heartbeat(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            pdir = Path(tmp) / "companies" / "omegaos"
+            hb = P.Heartbeat(
+                agent_id="construct",
+                project="test-project",
+                session="test-session",
+                status="working",
+                summary="step 2/5 in progress",
+            )
+            ok = P.send_heartbeat(hb, paperclip_dir=pdir)
+            self.assertTrue(ok)
+            files = list((pdir / "heartbeats").glob("construct-*.json"))
+            self.assertEqual(len(files), 1)
+            payload = json.loads(files[0].read_text())
+            self.assertEqual(payload["agent_id"], "construct")
+            self.assertEqual(payload["status"], "working")
+
+
+class TestStatus(unittest.TestCase):
+    """status() must work even when nothing is registered yet."""
+
+    def test_status_safe_on_fresh_machine(self):
+        # Just call it — should not raise even if PAPERCLIP_HOME is bare.
+        st = P.status()
+        self.assertIsNotNone(st)
+        self.assertEqual(st.omega_version, P._bridge_version())
+
+
+if __name__ == "__main__":
+    unittest.main()

package/omega/Agentik_SSOT/VERSION

@@ -1 +1 @@
-0.19.33
+0.19.34

package/omega/Agentik_SSOT/docs/AUDIT-V0.19.34.md

@@ -0,0 +1,143 @@
+# OmegaOS v0.19.34 — deep audit, all bugs & incoherences logged
+
+> Run on 2026-05-25 after the v0.19.33 Paperclip bridge ship.
+> Method: parallel checks (pytest, shell syntax, imports, parsers,
+> duplicate scan, version cross-ref, catalog parse, bridge invariants).
+
+## 1. Clean (passed)
+
+| Check | Result |
+|---|---|
+| pytest full suite | **612 passed** (599 + 13 new bridge tests) |
+| Shell syntax `install.sh + common.sh + steps.sh` | ✓ |
+| 14 internal Python modules importable | ✓ |
+| Version coherent: `__init__.py / pyproject.toml / package.json / VERSION` | 0.19.34 |
+| 4 catalog YAMLs parse cleanly | mcp 16 / plugins 11 / clis 28 / providers 16 |
+| 49 omega subcommands registered in argparse | ✓ |
+| tmux config 3-char hex regression | 0 occurrences (v0.19.28 fix holds) |
+| Paperclip bridge: 14 agents, hermes top, reporting lines | ✓ |
+| Personas: all 8 LLM filenames written by `write_all_personas` | ✓ |
+| Hermès credential isolation (ANTHROPIC_API_KEY_HERMES) | ✓ |
+| Filesystem fallback heartbeat | ✓ |
+
+## 2. Bugs found + fixed in v0.19.34
+
+| # | Bug | Severity | Fix |
+|---|---|---|---|
+| 1 | `LAYERS.md` didn't mention Paperclip even though the bridge shipped in v0.19.33 | doc gap | Added a v0.19.33+ section at the top with the L0 Paperclip diagram + pointer to FEATURE-MATRIX.md |
+| 2 | No regression tests for `paperclip_bridge` — bridge invariants (14 agents, reporting lines, credential isolation) lived only in code | test gap | Added `tests/test_paperclip_bridge.py` (13 tests, all passing) covering: agent inventory, reporting lines per agent, credential isolation (AISB must NOT declare API keys), dry-run safety, register writes 14 files, heartbeat filesystem fallback, status() on fresh machine |
+
+## 3. Code smells (NOT runtime bugs — flagged for future cleanup)
+
+### 3.1 `_omega_home` duplicated 10× across modules
+
+```
+audit_gate.py         def _omega_home() -> Path
+handoff.py            def _omega_home(home: str | Path | None) -> Path
+tools.py              def _omega_home(explicit: str | Path | None = None) -> Path
+plan.py               def _omega_home(explicit: str | Path | None = None) -> Path
+aisb_chat.py          def _omega_home() -> Path
+hermes_bootstrap.py   def _omega_home(explicit: str | Path | None) -> Path
+mission.py            def _omega_home(explicit: str | Path | None = None) -> Path
+cleanup.py            def _omega_home(home: str | Path | None) -> Path
+project.py            def _omega_home(explicit: str | Path | None = None) -> Path
+daemons/telegram.py   def _omega_home() -> Path
+```
+
+**Status**: not a runtime bug. Each module uses its own private helper.
+But **3 different signatures** for the same conceptual function is
+code smell. Refactor: extract to `omega_engine.paths.omega_home(explicit=None)`
+and update all 10 call sites. Scope: ~30 line diff, low risk. **Backlog v0.20.x.**
+
+### 3.2 `step_mcp` legacy function unreferenced from STEPS
+
+`bootstrap/lib/steps.sh` defines 22 step functions but `install.sh` only
+references 21 in its STEPS array. The orphan is `step_mcp` (deliberately
+retired in v0.19.21 when we switched to `step_clis`).
+
+**Status**: not a bug. `step_mcp` is still reachable via `omega tool install <id>`
+as a manual escape hatch. Function header documents this. **Leave as-is.**
+
+### 3.3 `cmd_billing` overlaps with `cmd_account*`
+
+There's a `cmd_billing` (since pre-v0.19) showing per-account cost
+aggregation, and a `cmd_account` family (list / login / use / pool) for
+account management. User mentioned earlier wanting `/billing` renamed to
+`/account` for Telegram parity, but the CLI subcommand is named `omega
+billing` and that's its purpose (cost surfacing).
+
+**Status**: not a bug. They serve adjacent purposes. The Telegram side
+already uses `/account` (per v0.19.x routing). CLI rename would be a
+breaking change for any user/script depending on `omega billing`.
+**Backlog**: alias `omega billing` ↔ `omega account costs`. v0.19.35+
+
+### 3.4 Multiple `_atomic_write`, `_have`, `_cache_path` helpers
+
+Same pattern as `_omega_home` — local helpers duplicated across modules
+because there's no shared `omega_engine.paths` / `omega_engine.utils`.
+Same refactor as 3.1. **Backlog v0.20.x.**
+
+## 4. Architecture invariants verified
+
+These come from FEATURE-MATRIX.md §8 (AISB rules). Audit confirms each
+is enforced AT CODE LEVEL, not just at doc level:
+
+| Invariant | Where it's enforced |
+|---|---|
+| Exactly 14 agents (Hermès + 13 AISB) | `paperclip_bridge.AISB_AGENTS` (13) + `HERMES_AGENT` (1); locked by `test_exactly_14_agents` |
+| Hermès reports to no-one | `HERMES_AGENT["reports_to"] = None`; locked by `test_hermes_first_and_top` |
+| Niobe reports to Hermès | Catalog + `test_niobe_reports_to_hermes` |
+| Oracle reports to Niobe | Catalog + `test_oracle_reports_to_niobe` |
+| Construct reports to Oracle | Catalog + `test_construct_reports_to_oracle` |
+| Credential domain isolation | `test_aisb_agents_do_not_declare_api_keys` + `test_hermes_uses_anthropic_key` |
+| `.done.json` verified completion | `done_signal.py` write_done() schema |
+| Audit gate ≥85/100 | `audit_gate.py` threshold |
+| Plan first (Oracle writes plan.md before dispatch) | Mission envelope builder + `plan.py` FSM |
+
+## 5. Counts (the system's "shape")
+
+- **Engine modules**: 60 Python files
+- **AISB suite agent prompts**: 15 .md (13 personas + CLAUDE.md + lmc-protocol.md, + protocols/ + checkers/)
+- **Test files**: 42 (was 41 — added `test_paperclip_bridge.py`)
+- **pytest tests**: 612 (was 599 — added 13)
+- **Install steps**: 21 in install.sh STEPS array
+- **Step functions defined**: 22 in steps.sh (1 legacy: step_mcp)
+- **CLI subcommands**: 49 distinct omega subcommands
+- **MCP catalog entries**: 16 (legacy, opt-in only)
+- **Claude plugins**: 11 (after v0.19.20 cleanup, claude-mem now opt-in)
+- **System CLIs**: 28 (incl. CloakBrowser, Scrapling, Paperclip, …)
+- **LLM providers**: 16 (Anthropic/OpenAI/Google/GLM/DeepSeek/Qwen/Ollama/LM Studio/OpenRouter/Bedrock/Mistral/xAI/Vercel Gateway/Copilot/OpenAI-compat/ChatGPT)
+- **Genesis stack presets**: 8 (canonical/mobile-native/mobile-expo/desktop-tauri/supabase/claude-dashboard/convex-selfhosted/sqlite-local)
+- **Personas supported**: 10 LLM filenames
+- **Quality Arsenal audits**: 17 (Skills as forensic protocols)
+
+## 6. Verdict
+
+**v0.19.34 is clean** for what it claims to do:
+
+- ✓ Multi-LLM ecosystem (13 CLIs + 16 providers + persona system)
+- ✓ Multi-scraper (CloakBrowser + Scrapling)
+- ✓ Tmux-based session orchestration (Omega master + chat windows)
+- ✓ Paperclip bridge (governance roof, 14 agents, idempotent)
+- ✓ Hermès isolated credentials (Anthropic API)
+- ✓ AISB+Oracle+Workers on Max OAuth
+- ✓ Verified completion (.done.json + audit gate)
+- ✓ Light Claude theme (fzf + tmux)
+- ✓ Arrow-key menu (fzf) + session switcher (Option+/)
+- ✓ 612 tests pass
+
+**Not yet there** (backlog v0.19.35+):
+
+- Auto-heartbeat hook in `tmux.spawn_worker / spawn_oracle`
+- Per-agent budget enforcement from Paperclip
+- HTTP heartbeat transport (currently filesystem only)
+- Refactor `_omega_home` + 4-5 other helpers into `omega_engine.paths`
+- Streaming async in the Textual TUI
+
+**Production-ready** for: distribution via npm, end-to-end install on
+macOS/Linux, multi-LLM coding sessions, project genesis, audit-gated
+missions, optional Paperclip governance.
+
+---
+
+*Audit run on commit after v0.19.33 ship, before v0.19.34 release.*

package/omega/Agentik_SSOT/docs/LAYERS.md

@@ -1,9 +1,28 @@
 # OmegaOS Layered Architecture
 
-> Five layers. **Two independent credential domains.** **Two Telegram bots
-> with separate tokens.** Hermès sits above; AISB+Oracle+Workers stay below.
+> **Six layers** (L0–L5) with Paperclip as the optional governance roof.
+> Two independent credential domains. Two Telegram bots with separate
+> tokens. Hermès above the OmegaOS core; AISB+Oracle+Workers below.
 > Each layer is independently usable.
 
+## v0.19.33+ — Paperclip as L0 governance
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│  Layer 0 ─ PAPERCLIP (optional, governance roof)                     │
+│  React dashboard + budget + org chart + approvals.                   │
+│  Registered via `omega paperclip register` — writes                  │
+│  ~/.paperclip/companies/omegaos/ with 14 agent profiles.             │
+│  Heartbeats from L1-L5 sessions feed this layer.                     │
+└────────────────────────────────────────┬─────────────────────────────┘
+                                         │
+                                         ▼
+[everything below is the original L1-L5 model]
+```
+
+See `omega/Agentik_SSOT/docs/FEATURE-MATRIX.md` for the full feature
+cross-reference + bridge command list.
+
 ## The corrected model (v0.19.14)
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentikos/omega-os",
-  "version": "0.19.33",
+  "version": "0.19.34",
   "description": "Omega OS — installable agentic operating system with verified-completion orchestration. Event-sourced engine, 8-block rack, autonomous agents, MCP.",
   "bin": {
     "omega-os": "bin/omega-os.js"