@agentikos/omega-os 0.2.0 → 0.19.5

package/omega/Agentik_Engine/omega_engine/worker.py

@@ -0,0 +1,526 @@
+"""Worker dispatcher — spawn each worker as its own persistent `claude`
+session in tmux, mirroring the live VPS pattern.
+
+Architecture
+------------
+
+Today the executor runs workers synchronously: ``provider.run(...)`` blocks
+until the model responds, then the executor moves on. If the engine /
+Telegram bot / supervisor crashes mid-mission, every in-flight worker
+dies with it.
+
+The VPS pattern fixes this: each worker is a complete ``claude`` CLI
+running inside its own tmux session. The session is detached, has its
+own PTY, and survives parent crashes. A 4-hour coding mission keeps
+making progress even if everything else falls over.
+
+Protocol
+--------
+
+The orchestrator (Oracle, dispatcher, or operator) calls
+``spawn_worker(...)`` with the brief. We:
+
+  1. Write the brief to
+     ``Agentik_Runtime/sessions/<task_id>/brief.json``
+  2. Create a detached tmux session named
+     ``<Project>-worker-<N>-<task>``
+  3. The session immediately runs ``omega worker run <task_id>`` —
+     reads its brief, calls Claude with the envelope, writes the
+     ``.done.json`` on completion.
+
+The orchestrator returns immediately; the mission monitor (or the
+operator) polls ``.done.json`` to know when each worker is done.
+
+Why per-call ``claude``, not interactive
+----------------------------------------
+
+For predictable completion + structured output, the worker runs:
+
+    claude -p "<user>" --append-system-prompt "<system>"
+           --model "<model>" --output-format json
+           --dangerously-skip-permissions
+
+This returns one JSON blob with ``result``, ``usage``, ``total_cost_usd``,
+``session_id``. The worker parses it and writes a structured
+``.done.json``. If the operator wants interactive (the worker asks the
+oracle questions mid-task), the same brief.json can drive that mode in
+a later iteration.
+
+Model selection
+---------------
+
+By default:
+
+  * role=``oracle`` / ``manager`` / ``aisb``  → ``sonnet`` (fast planner)
+  * role=``worker`` / ``construct``           → ``opus`` (1M context coding)
+  * role=``audit`` / ``verifier`` / ``seraph`` → ``sonnet``
+  * role=``haiku-*`` (cost-routed cheap roles) → ``haiku``
+
+This is the smart-routing default — overridable via the brief's ``model``
+field for explicit control.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+import time
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+# ---------------------------------------------------------------------------
+# Hardening — input validation for shell-bound identifiers
+# ---------------------------------------------------------------------------
+
+# task_id is interpolated into a tmux command line + used as a directory
+# name. We accept ONLY a-zA-Z0-9._- — anything else can break out of the
+# argument or escape the path. Bug history: prior to this guard,
+# `--task-id "t; touch /tmp/PWNED"` executed the second command.
+_TASK_ID_RE = re.compile(r"^[A-Za-z0-9._-]{1,128}$")
+
+
+def _validate_task_id(task_id: str) -> str:
+    if not isinstance(task_id, str) or not _TASK_ID_RE.match(task_id):
+        raise ValueError(
+            f"invalid task_id {task_id!r} — must match [A-Za-z0-9._-]{{1,128}}"
+        )
+    return task_id
+
+
+# ---------------------------------------------------------------------------
+# Default model per role
+# ---------------------------------------------------------------------------
+
+_ROLE_MODEL: dict[str, str] = {
+    # Dispatchers — fast planners
+    "oracle":     "sonnet",
+    "manager":    "sonnet",
+    "aisb":       "sonnet",
+    "architect":  "sonnet",
+    # Executors doing real coding work → opus with 1M context window
+    "worker":     "claude-opus-4-7[1m]",
+    "construct":  "claude-opus-4-7[1m]",
+    "link":       "sonnet",
+    # Verifiers — fast structured judgement
+    "audit":      "sonnet",
+    "verifier":   "sonnet",
+    "seraph":     "sonnet",
+    # Cheap classifier / triage roles
+    "classifier": "haiku",
+    "triage":     "haiku",
+}
+
+
+def default_model_for_role(role: str) -> str:
+    """The default Claude Code Max model for a role. Falls back to sonnet."""
+    return _ROLE_MODEL.get(role, "sonnet")
+
+
+# ---------------------------------------------------------------------------
+# Brief / done.json paths
+# ---------------------------------------------------------------------------
+
+
+def _omega_home() -> Path:
+    return Path(os.environ.get("OMEGA_HOME", str(Path.home() / "Omega")))
+
+
+def _session_dir(home: Path, task_id: str) -> Path:
+    d = home / "Agentik_Runtime" / "sessions" / task_id
+    d.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(d, 0o700)
+    except OSError:
+        pass
+    return d
+
+
+def brief_path(home: Path | str, task_id: str) -> Path:
+    return _session_dir(Path(home), task_id) / "brief.json"
+
+
+def done_path(home: Path | str, task_id: str) -> Path:
+    return _session_dir(Path(home), task_id) / ".done.json"
+
+
+def transcript_path(home: Path | str, task_id: str) -> Path:
+    """Where the raw claude JSON response is stored — useful for debug."""
+    return _session_dir(Path(home), task_id) / "transcript.json"
+
+
+# ---------------------------------------------------------------------------
+# Brief — what the worker reads to know what to do
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class WorkerBrief:
+    task_id: str
+    role: str                       # "worker" | "construct" | ...
+    intent: str                     # what the worker should do
+    system_prompt: str = ""         # the envelope's system component
+    user_prompt: str = ""           # the envelope's user component (fallback: intent)
+    model: str = ""                 # overrides role default if set
+    verify_cmd: str | None = None
+    project: str | None = None
+    cwd: str | None = None
+    spawned_at: int = field(default_factory=lambda: int(time.time()))
+    mission_id: str = ""
+    # Skill palette for this worker. Empty list → use the role default
+    # (resolved by ``resolved_skills()``). Set explicitly to ``None`` is
+    # equivalent to empty.
+    skills: list[str] = field(default_factory=list)
+
+    def resolved_model(self) -> str:
+        return self.model or default_model_for_role(self.role)
+
+    def resolved_skills(self) -> list[str]:
+        """Final skill list — explicit > role default. Used by ``run_brief``
+        to weave the skill block into ``--append-system-prompt``."""
+        if self.skills:
+            return list(self.skills)
+        try:
+            from omega_engine.skill_routing import recommend
+            return recommend(self.role)
+        except ImportError:
+            return []
+
+    def to_json(self) -> str:
+        return json.dumps({
+            "task_id": self.task_id, "role": self.role,
+            "intent": self.intent,
+            "system_prompt": self.system_prompt,
+            "user_prompt": self.user_prompt or self.intent,
+            "model": self.resolved_model(),
+            "skills": self.resolved_skills(),
+            "verify_cmd": self.verify_cmd,
+            "project": self.project, "cwd": self.cwd,
+            "spawned_at": self.spawned_at,
+            "mission_id": self.mission_id,
+        }, indent=2)
+
+    @staticmethod
+    def from_dict(d: dict[str, Any]) -> "WorkerBrief":
+        return WorkerBrief(
+            task_id=str(d["task_id"]),
+            role=str(d.get("role", "worker")),
+            intent=str(d.get("intent", "")),
+            system_prompt=str(d.get("system_prompt", "")),
+            user_prompt=str(d.get("user_prompt", "")),
+            model=str(d.get("model", "")),
+            verify_cmd=d.get("verify_cmd"),
+            project=d.get("project"),
+            cwd=d.get("cwd"),
+            spawned_at=int(d.get("spawned_at", time.time())),
+            mission_id=str(d.get("mission_id", "")),
+            skills=list(d.get("skills") or []),
+        )
+
+
+def write_brief(home: Path | str, brief: WorkerBrief) -> Path:
+    """Persist the brief atomically. Same temp+rename trick as write_done
+    so a polling reader never sees a half-written brief."""
+    _validate_task_id(brief.task_id)
+    p = brief_path(home, brief.task_id)
+    tmp = p.with_suffix(p.suffix + ".tmp")
+    tmp.write_text(brief.to_json())
+    try:
+        fd = os.open(str(tmp), os.O_RDONLY)
+        try:
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+    except OSError:
+        pass
+    os.replace(tmp, p)
+    return p
+
+
+def read_brief(home: Path | str, task_id: str) -> WorkerBrief:
+    p = brief_path(home, task_id)
+    if not p.exists():
+        raise FileNotFoundError(f"no brief at {p}")
+    return WorkerBrief.from_dict(json.loads(p.read_text()))
+
+
+# ---------------------------------------------------------------------------
+# Spawning the tmux session
+# ---------------------------------------------------------------------------
+
+
+def _session_name(brief: WorkerBrief, *, worker_id: int = 1) -> str:
+    """Build the tmux session name following the AISB convention."""
+    project = brief.project or "Omega"
+    # Sanitise task component (no spaces, max 40 chars)
+    task_label = "".join(
+        c if c.isalnum() or c in "-_" else "-" for c in brief.intent[:40]
+    ).strip("-") or "task"
+    return f"{project}-worker-{worker_id}-{task_label}"
+
+
+def spawn_worker(
+    brief: WorkerBrief, *,
+    home: Path | str | None = None,
+    worker_id: int = 1,
+    omega_bin: str | None = None,
+) -> str:
+    """Persist the brief + spawn a detached tmux session that runs the worker.
+
+    Returns the tmux session name. The orchestrator returns IMMEDIATELY —
+    the worker runs asynchronously in its own session. Poll
+    ``.done.json`` (via :func:`read_done`) to know when it's finished.
+    """
+    # SECURITY: refuse shell-injection vectors before they reach tmux.
+    _validate_task_id(brief.task_id)
+
+    home = Path(home or _omega_home())
+    write_brief(home, brief)
+    name = _session_name(brief, worker_id=worker_id)
+
+    if shutil.which("tmux") is None:
+        raise RuntimeError("tmux not on PATH — workers can't be spawned async")
+
+    bin_ = omega_bin or str(
+        home / "Agentik_Tools" / "bin" / "omega"
+    )
+    if not Path(bin_).exists():
+        bin_ = shutil.which("omega") or "omega"
+
+    cwd = brief.cwd or os.getcwd()
+    # Build the command via shlex.quote so even a future malformed task_id
+    # cannot escape its argument slot. _validate_task_id is the first
+    # line of defence; this is the second.
+    cmd = " ".join([
+        f"OMEGA_HOME={shlex.quote(str(home))}",
+        shlex.quote(bin_),
+        "worker", "run",
+        shlex.quote(brief.task_id),
+    ])
+
+    # Refuse to overwrite an existing live session — that would be a bug.
+    proc = subprocess.run(
+        ["tmux", "has-session", "-t", name],
+        check=False, capture_output=True, timeout=10,
+    )
+    if proc.returncode == 0:
+        # session already exists; treat as idempotent re-spawn.
+        return name
+
+    subprocess.run(
+        ["tmux", "new-session", "-d", "-s", name, "-c", cwd, cmd],
+        check=True, capture_output=True, text=True, timeout=30,
+    )
+    return name
+
+
+# ---------------------------------------------------------------------------
+# Worker entry point (runs INSIDE the tmux session)
+# ---------------------------------------------------------------------------
+
+
+def run_brief(home: Path | str, task_id: str) -> int:
+    """The body of ``omega worker run <task_id>``.
+
+    Reads the brief, calls ``claude -p`` with the envelope, parses the
+    JSON response, writes a structured ``.done.json``. Returns the exit
+    code (0 on done_clean, 1 on failure).
+    """
+    from omega_engine.done_signal import DoneSignal, write_done
+
+    home = Path(home)
+    try:
+        brief = read_brief(home, task_id)
+    except FileNotFoundError as exc:
+        write_done(home, task_id, DoneSignal(
+            status="failed",
+            summary=f"worker missing brief: {exc}",
+            errors=[str(exc)],
+        ))
+        return 1
+
+    # Compose the system prompt: explicit system_prompt + the skill block
+    # (so the worker knows which slash commands it has access to).
+    sys_prompt = brief.system_prompt or ""
+    skills = brief.resolved_skills()
+    if skills:
+        try:
+            from omega_engine.skill_routing import format_skill_block
+            block = format_skill_block(skills, home=home)
+            if block:
+                sys_prompt = (sys_prompt + "\n" + block).strip()
+        except ImportError:
+            pass
+
+    cmd = [
+        "claude", "-p", brief.user_prompt or brief.intent,
+        "--output-format", "json",
+        "--model", brief.resolved_model(),
+        "--dangerously-skip-permissions",
+    ]
+    if sys_prompt:
+        cmd += ["--append-system-prompt", sys_prompt]
+    if brief.cwd:
+        cmd += ["--add-dir", str(brief.cwd)]
+
+    print(f"omega worker {task_id}: model={brief.resolved_model()} "
+          f"cwd={brief.cwd or os.getcwd()}")
+    print(f"  intent: {brief.intent[:120]}")
+
+    started = time.time()
+    try:
+        proc = subprocess.run(
+            cmd, check=False, capture_output=True, text=True,
+            timeout=3600,                 # 1 hour cap per claude call
+            cwd=brief.cwd or os.getcwd(),
+        )
+    except subprocess.TimeoutExpired:
+        write_done(home, task_id, DoneSignal(
+            status="failed",
+            summary="claude -p timed out after 3600s",
+            errors=["timeout"],
+        ))
+        return 1
+    except OSError as exc:
+        write_done(home, task_id, DoneSignal(
+            status="failed",
+            summary=f"claude -p failed to launch: {exc}",
+            errors=[str(exc)],
+        ))
+        return 1
+
+    elapsed = round(time.time() - started, 2)
+
+    if proc.returncode != 0:
+        write_done(home, task_id, DoneSignal(
+            status="failed",
+            summary=f"claude -p exited {proc.returncode} after {elapsed}s",
+            errors=[
+                (proc.stderr or proc.stdout or "")[:500],
+            ],
+        ))
+        return 1
+
+    # Persist the raw transcript for debug.
+    transcript_path(home, task_id).write_text(proc.stdout or "")
+
+    try:
+        data = json.loads(proc.stdout or "{}")
+    except json.JSONDecodeError as exc:
+        write_done(home, task_id, DoneSignal(
+            status="failed",
+            summary=f"claude -p returned non-JSON: {exc}",
+            errors=[(proc.stdout or "")[:500]],
+        ))
+        return 1
+
+    text = str(data.get("result", "")).strip()
+    usage = data.get("usage", {}) or {}
+    cost = float(data.get("total_cost_usd", 0.0) or 0.0)
+    sig = DoneSignal(
+        status="done_clean",
+        summary=text[:1000] or "(no text response)",
+        files_changed=[],
+        artifacts={
+            "session_id": data.get("session_id", ""),
+            "model": brief.resolved_model(),
+            "elapsed_s": elapsed,
+            "usage": {
+                "input_tokens": int(usage.get("input_tokens", 0) or 0),
+                "output_tokens": int(usage.get("output_tokens", 0) or 0),
+                "cost_usd": cost,
+            },
+        },
+    )
+    write_done(home, task_id, sig)
+    print(f"omega worker {task_id}: done in {elapsed}s, cost ${cost:.4f}")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Status / wait / list helpers
+# ---------------------------------------------------------------------------
+
+
+def worker_status(home: Path | str, task_id: str) -> dict[str, Any]:
+    """Read .done.json + tmux state. Returns a single status dict."""
+    home = Path(home)
+    done = done_path(home, task_id)
+    if done.exists():
+        try:
+            data = json.loads(done.read_text())
+            return {
+                "task_id": task_id,
+                "state": data.get("status", "unknown"),
+                "summary": data.get("summary", ""),
+                "artifacts": data.get("artifacts", {}),
+                "tmux_alive": False,
+                "source": ".done.json",
+            }
+        except json.JSONDecodeError:
+            pass
+    # No done.json — check tmux
+    if shutil.which("tmux"):
+        from omega_engine import tmux as tx
+        for sess in tx.list_sessions(home):
+            # Match by task_id in the session name
+            if task_id in sess.name:
+                return {
+                    "task_id": task_id,
+                    "state": "running",
+                    "tmux_alive": True,
+                    "tmux_session": sess.name,
+                    "source": "tmux",
+                }
+    return {"task_id": task_id, "state": "unknown", "tmux_alive": False,
+            "source": "absent"}
+
+
+def wait_for_done(
+    home: Path | str, task_id: str,
+    *, timeout_s: int = 3600, poll_s: int = 5,
+) -> dict[str, Any]:
+    """Block until .done.json exists (or timeout). Returns the final status."""
+    end = time.time() + timeout_s
+    while time.time() < end:
+        status = worker_status(home, task_id)
+        if status["state"] in ("done_clean", "pending", "failed"):
+            return status
+        time.sleep(poll_s)
+    return {"task_id": task_id, "state": "timeout", "tmux_alive": False,
+            "source": "timeout"}
+
+
+def list_workers(home: Path | str) -> list[dict[str, Any]]:
+    """Scan every per-task session dir. One row per task with a brief."""
+    home = Path(home)
+    sessions_root = home / "Agentik_Runtime" / "sessions"
+    if not sessions_root.is_dir():
+        return []
+    out: list[dict[str, Any]] = []
+    for child in sorted(sessions_root.iterdir()):
+        if not child.is_dir():
+            continue
+        b = child / "brief.json"
+        if not b.exists():
+            continue
+        try:
+            brief = WorkerBrief.from_dict(json.loads(b.read_text()))
+        except (json.JSONDecodeError, OSError):
+            continue
+        status = worker_status(home, brief.task_id)
+        out.append({
+            "task_id": brief.task_id, "role": brief.role,
+            "model": brief.resolved_model(),
+            "intent": brief.intent[:80],
+            "project": brief.project, "spawned_at": brief.spawned_at,
+            "state": status["state"],
+            "tmux_alive": status.get("tmux_alive", False),
+        })
+    return out

package/omega/Agentik_Engine/pyproject.toml

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