@agentikos/omega-os 0.2.0 → 0.19.6

package/omega/Agentik_Engine/omega_engine/hermes_bootstrap.py

@@ -0,0 +1,382 @@
+"""Hermès bootstrap — teach Hermès what OmegaOS is, so it can use it
+itself and improve it over time.
+
+What this fixes
+---------------
+
+After ``omega hermes install`` + ``omega hermes link``, Hermès has the
+Claude OAuth token and knows how to talk to Claude. But it does NOT yet
+know:
+
+  * that OmegaOS exists as Layer 3-5 below it
+  * how to dispatch a mission via ``omega run`` / ``omega genesis``
+  * which audits to call when the operator says "is it broken?"
+  * what its own learning loop should ingest (the .done.json archive,
+    the audit history, the autonomous charters)
+
+This module writes a single SKILL.md into Hermès's user skill dir
+(``~/.hermes/skills/omega/SKILL.md``) so the agent loop discovers it
+on next start. The SKILL.md is auto-generated from the engine's current
+shape — when we add new CLI surfaces, the brief regenerates with them.
+
+The brief is structured so Hermès's learning loop ingests:
+  * Every mission outcome (``$OMEGA_HOME/Agentik_Runtime/sessions/*/.done.json``)
+  * Every audit verdict (``$OMEGA_HOME/Agentik_Runtime/audits.db``)
+  * The autonomous-charter outcomes (``$OMEGA_HOME/Agentik_Extra/staging/promotion/``)
+
+Auto-improvement loop
+---------------------
+
+When Hermès finishes a task that called ``omega …``:
+  1. ``hermes_bootstrap.observe_outcome(slug, task_id)`` reads the
+     resulting .done.json + any audit verdict.
+  2. Writes a one-line learning event to
+     ``~/.hermes/memory/omega_observations.jsonl``.
+  3. Hermès's memory provider (Honcho) picks it up and uses it to
+     adjust its dialectic user model.
+
+Public API
+----------
+
+  ``write_brief(home=None, hermes_home=None)`` — write the SKILL.md.
+  ``observe_outcome(slug, task_id)`` — append one learning event.
+  ``status()`` — return ``{brief_present, last_observed_at, …}``.
+
+The CLI surface ``omega hermes brief {write,status}`` lives in cli.py.
+"""
+from __future__ import annotations
+
+import json
+import os
+import threading
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+
+_DEFAULT_HERMES_HOME = Path.home() / ".hermes"
+
+
+def _hermes_home(explicit: str | Path | None) -> Path:
+    return (
+        Path(explicit) if explicit
+        else Path(os.environ.get("HERMES_HOME", str(_DEFAULT_HERMES_HOME)))
+    )
+
+
+def _omega_home(explicit: str | Path | None) -> Path:
+    return (
+        Path(explicit) if explicit
+        else Path(os.environ.get("OMEGA_HOME", str(Path.home() / "Omega")))
+    )
+
+
+# ---------------------------------------------------------------------------
+# The brief — generated from current engine shape
+# ---------------------------------------------------------------------------
+
+
+def _render_brief(omega_home: Path) -> str:
+    """Build the OmegaOS SKILL.md content for Hermès."""
+    return f"""---
+name: omega
+description: |
+  OmegaOS is the Layer 3-5 system this Hermès sits on top of. Use it when
+  the operator wants verified-completion engineering work: new projects,
+  multi-day autonomous coding, forensic audits, deployment to production.
+  Use OmegaOS instead of doing the engineering yourself — Hermès is
+  Layer 2 (conversation, gateway, memory, learning); OmegaOS is Layer
+  3-5 (intake bus, planner, verified workers).
+when_to_use: |
+  Trigger phrases (FR + EN, case-insensitive):
+    - "build me a", "fais-moi un", "code me a", "ship a"
+    - "audit the code", "is it broken", "is it secure", "is it fast"
+    - "create new project", "nouveau projet", "start from scratch"
+    - "fix all linear tickets", "regler les feedbacks"
+    - "deploy", "ship", "met en prod"
+allowed-tools: Bash Read Write
+---
+
+# OmegaOS — your engineering layer
+
+You (Hermès) are **Layer 2** in this system. OmegaOS sits below you as
+Layer 3-5:
+
+    L1 Human                — Telegram / CLI / web
+    L2 You (Hermès)         — autonomous companion, learning loop, gateway
+    L3 AISB                 — OmegaOS intake bus + classifier
+    L4 Oracle               — planner / dispatcher
+    L5 Workers              — verified-completion executors
+
+You share ONE credential: the Claude Max OAuth token at
+``~/.claude/.credentials.json``. No API key burn. The bridge reads it
+live on every call (your config NEVER stores the literal).
+
+## Your responsibilities at Layer 2
+
+1. **Conversation + memory.** You hold the user model, the personality,
+   the long-running context. OmegaOS workers don't.
+2. **Cross-platform gateway.** Telegram / Discord / Signal / WhatsApp.
+   When a message arrives, you classify intent and either answer
+   directly (chat / question / status) OR delegate to OmegaOS for
+   engineering work.
+3. **Learning loop.** Every mission outcome is observable. Read
+   `$OMEGA_HOME/Agentik_Runtime/sessions/*/.done.json` after a mission
+   completes; ingest into your memory so the next dispatch improves.
+4. **Self-improvement.** When you observe a pattern ("worker_ui always
+   forgets dark mode"), write a learning note that the next worker
+   brief picks up.
+
+## How to delegate to OmegaOS
+
+### A. Start a new project (vision → market → branding → PRD → features → plan)
+
+```bash
+omega genesis new <slug> --intent "<one-line brief>"
+omega genesis run <slug>                    # walks all 7 phases
+```
+
+This produces 19 docs under
+``$OMEGA_HOME/Agentik_Coding/projects/<slug>/docs/`` + ``plan/DAG.json``.
+
+### B. Execute the plan (multi-day autonomous loop)
+
+```bash
+omega plan build <slug>                     # ingest DAG.json into store
+omega plan run <slug>                       # FSM-enforced loop:
+                                            # next → in_progress → verify → verified
+```
+
+The reducer REFUSES illegal transitions — a worker cannot skip a task
+whose deps aren't VERIFIED. This is engine-enforced, not prompt-soft.
+
+### C. Quick mission (no project skeleton needed)
+
+```bash
+omega run "fix the typo in apps/web/app/page.tsx"
+```
+
+### D. Forensic audits (17 available)
+
+```bash
+omega audit run codeaudit --scope=apps/web
+omega audit run a11yaudit
+omega audit run perfaudit
+omega audit run secaudit
+# Full list: codeaudit / debugaudit / flowaudit / uiuxaudit /
+#            featureaudit / perfaudit / secaudit / a11yaudit /
+#            seoaudit / dataaudit / apiaudit / copyaudit /
+#            dxaudit / motionaudit / automationaudit / logicaudit /
+#            retentionaudit
+```
+
+### E. Ship to production
+
+```bash
+omega run "/prod <slug>"     # full build + push + Vercel deploy + verify
+```
+
+## Observing outcomes (your learning loop input)
+
+After EVERY ``omega …`` call you make, observe:
+
+```bash
+omega plan status <slug>                                            # progression
+ls $OMEGA_HOME/Agentik_Runtime/sessions/*/.done.json                # raw outcomes
+omega learn report                                                  # Smith reflection
+```
+
+Then write to your memory:
+
+```bash
+hermes memory add "On project <slug>, F-005 verified in 12min; \
+worker_ui correctly invoked /shadcn-ui + /impeccable. Next time \
+similar UI work: same skill bundle."
+```
+
+This is how you compound — every mission you delegate teaches you
+something about which roles, which skills, which audits the operator's
+work needs.
+
+## What you should NOT do at Layer 2
+
+  * Write code yourself when the work is engineering. Delegate.
+  * Bypass the audit gate. If the operator says "ship it", you call
+    ``omega run "/prod"`` which runs the gate; you do NOT push directly.
+  * Re-implement what OmegaOS already exposes (audits, planners,
+    workers). It's already there.
+  * Burn API tokens. Always use the Claude OAuth — that's why the bridge
+    exists.
+
+## How OmegaOS gets better when you use it
+
+Every dispatch you make:
+  * adds a row to ``$OMEGA_HOME/Agentik_Runtime/eventlog/omega.db``
+  * if a worker fails verify, ``omega learn reflect`` produces an
+    Insight in ``$OMEGA_HOME/Agentik_Extra/staging/promotion/`` — your
+    next dispatch should consider that pattern.
+  * the audit history accumulates — call ``omega audit history`` to see
+    score trends per project.
+
+## Quick commands
+
+| You want to | Run |
+|---|---|
+| Status of everything | ``omega doctor`` |
+| What's running in tmux | ``omega tmux list`` |
+| List projects | ``omega project list`` |
+| Memory across sessions | ``omega memory search "<query>"`` |
+| Auto-update OmegaOS | ``omega update apply`` |
+| Backup before risky | ``omega backup create --encrypt`` |
+
+The full CLI is at ``omega --help`` and every subcommand has its own
+``--help`` page.
+
+---
+
+OmegaOS root: ``{omega_home}``
+Generated: {time.strftime("%Y-%m-%dT%H:%M:%S")} by ``omega hermes brief write``.
+Re-run ``omega hermes brief write`` to refresh this file with the latest
+engine surface.
+"""
+
+
+# ---------------------------------------------------------------------------
+# Atomic write
+# ---------------------------------------------------------------------------
+
+
+def _atomic_write(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(
+        path.suffix + f".tmp.{os.getpid()}.{threading.get_ident()}"
+    )
+    fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o644)
+    with os.fdopen(fd, "w") as fh:
+        fh.write(content)
+        fh.flush()
+        try:
+            os.fsync(fh.fileno())
+        except OSError:
+            pass
+    os.replace(tmp, path)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def brief_path(hermes_home: str | Path | None = None) -> Path:
+    """Where the SKILL.md lands inside Hermès's tree."""
+    return _hermes_home(hermes_home) / "skills" / "omega" / "SKILL.md"
+
+
+def memory_log_path(hermes_home: str | Path | None = None) -> Path:
+    """The JSONL Hermès's memory provider ingests."""
+    return _hermes_home(hermes_home) / "memory" / "omega_observations.jsonl"
+
+
+@dataclass
+class BriefResult:
+    written: bool
+    path: str
+    bytes_written: int
+    omega_home: str
+
+
+def write_brief(
+    omega_home: str | Path | None = None,
+    hermes_home: str | Path | None = None,
+) -> BriefResult:
+    """Generate + atomically write the OmegaOS brief into Hermès's skills."""
+    home = _omega_home(omega_home)
+    content = _render_brief(home)
+    dest = brief_path(hermes_home)
+    _atomic_write(dest, content)
+    return BriefResult(
+        written=True,
+        path=str(dest),
+        bytes_written=len(content),
+        omega_home=str(home),
+    )
+
+
+@dataclass
+class Observation:
+    """One observable outcome — what Hermès learns from."""
+
+    ts: float
+    slug: str
+    task_id: str
+    status: str            # done_clean | pending | failed
+    summary: str
+    score: int | None = None
+    audit_verdict: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def observe_outcome(
+    slug: str,
+    task_id: str,
+    *,
+    omega_home: str | Path | None = None,
+    hermes_home: str | Path | None = None,
+) -> Observation | None:
+    """Read the .done.json for a task + append a learning event to Hermès's memory.
+
+    Returns None if no .done.json exists yet (worker hasn't finished).
+    """
+    from omega_engine.done_signal import read_done
+
+    home = _omega_home(omega_home)
+    sig = read_done(home, task_id)
+    if sig is None:
+        return None
+    obs = Observation(
+        ts=time.time(),
+        slug=slug,
+        task_id=task_id,
+        status=sig.status,
+        summary=sig.summary or "",
+        audit_verdict=(
+            sig.audit.get("verdict", "")
+            if isinstance(sig.audit, dict) else ""
+        ),
+    )
+    # Append-only JSONL — Hermès's memory provider reads this file.
+    log = memory_log_path(hermes_home)
+    log.parent.mkdir(parents=True, exist_ok=True)
+    with log.open("a") as fh:
+        fh.write(json.dumps(obs.to_dict()) + "\n")
+    return obs
+
+
+def status(
+    hermes_home: str | Path | None = None,
+) -> dict[str, Any]:
+    """Snapshot of the bootstrap state — for the doctor + status CLI."""
+    bp = brief_path(hermes_home)
+    ml = memory_log_path(hermes_home)
+    out: dict[str, Any] = {
+        "brief_path": str(bp),
+        "brief_present": bp.exists(),
+        "brief_size": bp.stat().st_size if bp.exists() else 0,
+        "memory_log_path": str(ml),
+        "memory_log_present": ml.exists(),
+        "observation_count": 0,
+        "last_observed_at": None,
+    }
+    if ml.exists():
+        try:
+            lines = ml.read_text().splitlines()
+            out["observation_count"] = len(lines)
+            if lines:
+                last = json.loads(lines[-1])
+                out["last_observed_at"] = last.get("ts")
+        except (OSError, json.JSONDecodeError):
+            pass
+    return out