@agentikos/omega-os 0.2.0 → 0.19.5

package/omega/Agentik_Engine/omega_engine/done_signal.py

@@ -0,0 +1,154 @@
+"""Worker `.done.json` — the structured completion signal.
+
+Events are the source of truth (event-sourcing). But events are *facts about
+state*, not *artifacts the worker produced*. The done file is the workspace
+artifact: the worker's structured summary of what it did, what's still
+pending, what failed.
+
+Schema
+------
+::
+
+    {
+        "status": "done_clean" | "pending" | "failed",
+        "summary": str,
+        "files_changed": [str, ...],
+        "artifacts": {str: any},
+        "pending_actions": [str, ...],
+        "errors": [str, ...],
+        "audit": {...}              # optional, set by the verifier
+    }
+
+Where it lives
+--------------
+::
+
+    $OMEGA_HOME/Agentik_Runtime/sessions/<task_id>/.done.json
+
+The executor passes this path to the worker through the envelope; the worker
+writes there when finished; the audit gate reads it back before flipping
+VERIFIED. AISB / parent dispatchers can also read it to surface progress.
+"""
+from __future__ import annotations
+
+import json
+import os
+import threading
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+VALID_STATUSES = {"done_clean", "pending", "failed"}
+
+
+class DoneSignalError(RuntimeError):
+    """The done file is missing, malformed, or claims an invalid status."""
+
+
+@dataclass
+class DoneSignal:
+    status: str = "pending"
+    summary: str = ""
+    files_changed: list[str] = field(default_factory=list)
+    artifacts: dict[str, Any] = field(default_factory=dict)
+    pending_actions: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+    audit: dict[str, Any] = field(default_factory=dict)
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self), indent=2, ensure_ascii=False)
+
+
+def session_dir(omega_home: str | Path, task_id: str) -> Path:
+    """Per-task session directory; created on demand with mode 700."""
+    d = Path(omega_home) / "Agentik_Runtime" / "sessions" / task_id
+    d.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(d, 0o700)
+    except OSError:
+        pass
+    return d
+
+
+def done_path(omega_home: str | Path, task_id: str) -> Path:
+    return session_dir(omega_home, task_id) / ".done.json"
+
+
+def write_done(
+    omega_home: str | Path,
+    task_id: str,
+    signal: DoneSignal,
+) -> Path:
+    """Write a DoneSignal as JSON to the session dir, ATOMICALLY.
+
+    Atomicity matters here: ``read_done`` is polled by the audit gate, the
+    Telegram patrol, AISB, and a partial write would make the verifier read
+    half a JSON blob. We write to a temp file in the same dir, fsync, then
+    rename — rename within the same filesystem is atomic.
+    """
+    if signal.status not in VALID_STATUSES:
+        raise DoneSignalError(
+            f"invalid status {signal.status!r} — must be one of {VALID_STATUSES}"
+        )
+    path = done_path(omega_home, task_id)
+    # Unique tmp suffix per call so concurrent writers from different
+    # threads don't clobber each other's intermediate file.
+    tmp = path.with_suffix(
+        path.suffix + f".tmp.{os.getpid()}.{threading.get_ident()}"
+    )
+    # Write + fsync + close. `os.fdopen` takes ownership of `fd` so the
+    # `with` block is responsible for closing — we never double-close.
+    fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as fh:
+        fh.write(signal.to_json())
+        fh.flush()
+        try:
+            os.fsync(fh.fileno())
+        except OSError:
+            # tmpfs / network FS may not support fsync — best-effort.
+            pass
+    # Atomic rename. POSIX guarantees same-dir rename is atomic; readers
+    # see either the old file or the new file, never a partial blob.
+    os.replace(tmp, path)
+    return path
+
+
+def read_done(omega_home: str | Path, task_id: str) -> DoneSignal | None:
+    """Read a DoneSignal back. Returns None if the file is missing."""
+    path = done_path(omega_home, task_id)
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError) as exc:
+        raise DoneSignalError(f"unparseable done file at {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise DoneSignalError(f"done file must be a JSON object, got {type(data)}")
+    status = data.get("status", "")
+    if status not in VALID_STATUSES:
+        raise DoneSignalError(
+            f"done file {path} has invalid status {status!r}"
+        )
+    return DoneSignal(
+        status=status,
+        summary=str(data.get("summary", "")),
+        files_changed=list(data.get("files_changed") or []),
+        artifacts=dict(data.get("artifacts") or {}),
+        pending_actions=list(data.get("pending_actions") or []),
+        errors=list(data.get("errors") or []),
+        audit=dict(data.get("audit") or {}),
+    )
+
+
+def attach_audit_to_done(
+    omega_home: str | Path,
+    task_id: str,
+    audit: dict[str, Any],
+) -> None:
+    """Update an existing done file in place with the verifier's verdict."""
+    signal = read_done(omega_home, task_id)
+    if signal is None:
+        signal = DoneSignal(status="pending", summary="(audit-only)")
+    signal.audit = dict(audit)
+    write_done(omega_home, task_id, signal)

package/omega/Agentik_Engine/omega_engine/envelope.py

@@ -0,0 +1,219 @@
+"""Mission envelope — the bridge between a Task and the provider's request.
+
+The executor used to send the agent ONLY a bare prompt ("subtask 1"). That's
+not how AISB-style orchestration works: an Oracle needs to know who it is,
+what the user asked for verbatim, what its parent already decided, and the
+contract for declaring completion. The envelope is that wrapper.
+
+Two things come out of ``build_envelope``:
+
+* ``system`` — the role's full agent prompt (from ``omega_engine.prompts``)
+  plus the orchestration contract appended at the end. This goes in the
+  provider's ``system`` parameter.
+* ``user`` — the user-visible content: the original intent, the parent
+  context, the plan-so-far, and any role-specific data. This goes in
+  ``messages``.
+
+For programmatic roles (mock, educators, RAG sub-roles), the envelope still
+works but the contract block is skipped — those agents don't dispatch.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+# Roles that DISPATCH (return a plan). They need the dispatcher contract.
+DISPATCHER_ROLES = {
+    "aisb", "oracle", "manager", "architect", "keymaker", "morpheus",
+}
+# Roles that EXECUTE (return artifacts + claimed_done).
+EXECUTOR_ROLES = {"worker", "construct", "link"}
+# Roles that VERIFY (return a verdict).
+VERIFIER_ROLES = {"audit", "verifier", "seraph"}
+# Read-only roles — observe the system, propose, never act.
+READ_ONLY_ROLES = {"pythia", "neo", "niobe", "merovingian", "zion"}
+# Improvement / learning roles — analyse outcomes, propose tuning.
+LEARNER_ROLES = {"smith"}
+
+
+@dataclass
+class EnvelopeContext:
+    """Everything the envelope needs to know about a task's place in the world."""
+
+    role: str
+    intent: str                                              # user prompt verbatim
+    mission_id: str = ""
+    task_id: str = ""
+    parent_role: str | None = None
+    parent_intent: str | None = None
+    plan_so_far: list[dict[str, Any]] = field(default_factory=list)
+    sibling_states: dict[str, str] = field(default_factory=dict)
+    available_tools: list[str] = field(default_factory=list)
+    project: dict[str, Any] | None = None                    # name, slug, path
+    done_json_path: str | None = None                        # where the worker writes done
+    verify_cmd: str | None = None
+    extras: dict[str, Any] = field(default_factory=dict)
+
+
+def _dispatcher_contract() -> str:
+    return (
+        "## ORCHESTRATION CONTRACT (dispatcher)\n\n"
+        "You are a DISPATCHER. You break the mission into atomic subtasks\n"
+        "and respond with a JSON array of child tasks. Format strictly:\n\n"
+        "```json\n"
+        "[\n"
+        '  {"role": "worker", "spec": {\n'
+        '    "task": "<one concrete actionable instruction>",\n'
+        '    "verify_cmd": "<shell command that returns 0 iff the task is truly done>",\n'
+        '    "files_owned": ["<path/glob>", ...],\n'
+        '    "context": {<any extra data the worker will need>}\n'
+        "  }},\n"
+        "  ...\n"
+        "]\n"
+        "```\n\n"
+        "Rules:\n"
+        "1. Preserve the user's intent verbatim — never paraphrase it away.\n"
+        "2. Each subtask MUST be small enough to fit in one worker context.\n"
+        "3. `verify_cmd` is the ground truth — if it exits 0, the worker is done.\n"
+        "4. JSON ONLY — no prose around the array. No code fences except the one above.\n"
+        "5. Your reply IS the plan. The engine will dispatch each child as a task.\n"
+    )
+
+
+def _executor_contract(done_json_path: str | None) -> str:
+    path = done_json_path or "Agentik_Runtime/sessions/<task_id>/.done.json"
+    return (
+        "## ORCHESTRATION CONTRACT (executor / worker)\n\n"
+        "You are a WORKER. You produce concrete artifacts and prove you're done.\n"
+        f"When finished, you WRITE a JSON file at `{path}` with this exact schema:\n\n"
+        "```json\n"
+        "{\n"
+        '  "status": "done_clean" | "pending" | "failed",\n'
+        '  "summary": "<one-paragraph what you did and why>",\n'
+        '  "files_changed": ["<relative path>", ...],\n'
+        '  "artifacts": {"<key>": "<value>", ...},\n'
+        '  "pending_actions": ["<thing the next worker / human should do>", ...],\n'
+        '  "errors": ["<actionable error>", ...]\n'
+        "}\n"
+        "```\n\n"
+        "Rules:\n"
+        "1. NEVER write `done_clean` if a `verify_cmd` would fail. Run it first.\n"
+        "2. `pending` means you did real work but more is needed — list it.\n"
+        "3. `failed` is honest. The engine prefers honesty over fake success.\n"
+        "4. The completion-verification gate reads this file. Lying = REJECTED.\n"
+    )
+
+
+def _verifier_contract() -> str:
+    return (
+        "## ORCHESTRATION CONTRACT (verifier)\n\n"
+        "You are a VERIFIER. The worker has just claimed done. Your job is to\n"
+        "prove or disprove that claim by running real checks (not just reading\n"
+        "code). Respond with a JSON object:\n\n"
+        "```json\n"
+        '{"verified": true|false, "score": 0-100, "confidence": "low|med|high",\n'
+        ' "findings": [{"audit":"...","severity":"low|med|high|crit","msg":"..."}],\n'
+        ' "fix_plan": ["<actionable, ordered>", ...]}\n'
+        "```\n\n"
+        "Rules:\n"
+        "1. Code lies, comments lie — only runtime tells the truth. Run things.\n"
+        "2. Bias toward `false` — earn a `true` with concrete evidence.\n"
+        "3. Every PASS must cite at least 3 concrete checks.\n"
+    )
+
+
+def _section(title: str, body: str | None) -> str:
+    if not body:
+        return ""
+    return f"\n\n## {title}\n\n{body}"
+
+
+def build_envelope(
+    omega_home: str | Path,
+    ctx: EnvelopeContext,
+) -> dict[str, str]:
+    """Return ``{system, user}`` strings ready to pass to a provider.
+
+    The ``system`` part loads the role's prompt from
+    ``Agentik_SSOT/agents/`` and appends the appropriate orchestration
+    contract. If no agent file exists for the role, a minimal generic
+    envelope is built (one line of identity + the contract).
+    """
+    # Local import to avoid cycles.
+    from omega_engine.prompts import load_agent_prompt
+
+    home = Path(omega_home)
+    agent_prompt = load_agent_prompt(home, ctx.role) or (
+        f"You are an Omega OS {ctx.role.upper()} agent."
+    )
+
+    if ctx.role in DISPATCHER_ROLES:
+        contract = _dispatcher_contract()
+    elif ctx.role in EXECUTOR_ROLES:
+        contract = _executor_contract(ctx.done_json_path)
+    elif ctx.role in VERIFIER_ROLES:
+        contract = _verifier_contract()
+    else:
+        # Programmatic / specialised roles use their own internal contract.
+        contract = ""
+
+    system_parts = [agent_prompt]
+    if contract:
+        system_parts.append(f"\n\n{contract}")
+    system = "".join(system_parts).strip()
+
+    # ---- user message ------------------------------------------------------
+    user_blocks: list[str] = []
+
+    user_blocks.append(f"# USER INTENT (verbatim)\n\n{ctx.intent.strip()}")
+
+    if ctx.parent_intent and ctx.parent_role:
+        user_blocks.append(
+            f"## Parent task ({ctx.parent_role})\n\n{ctx.parent_intent.strip()}"
+        )
+
+    if ctx.plan_so_far:
+        user_blocks.append(
+            "## Plan so far\n\n"
+            "```json\n" + json.dumps(ctx.plan_so_far, indent=2) + "\n```"
+        )
+
+    if ctx.sibling_states:
+        user_blocks.append(
+            "## Sibling states\n\n```json\n"
+            + json.dumps(ctx.sibling_states, indent=2)
+            + "\n```"
+        )
+
+    if ctx.available_tools:
+        user_blocks.append(
+            "## Available tools\n\n- " + "\n- ".join(ctx.available_tools)
+        )
+
+    if ctx.project:
+        user_blocks.append(
+            f"## Project context\n\nname: {ctx.project.get('name')}\n"
+            f"slug: {ctx.project.get('slug')}\n"
+            f"path: {ctx.project.get('path')}"
+        )
+
+    if ctx.verify_cmd:
+        user_blocks.append(
+            f"## Verify command\n\n```bash\n{ctx.verify_cmd}\n```"
+        )
+
+    if ctx.done_json_path and ctx.role in EXECUTOR_ROLES:
+        user_blocks.append(
+            f"## Done file\n\nWrite your completion JSON to: `{ctx.done_json_path}`"
+        )
+
+    if ctx.task_id:
+        user_blocks.append(f"## Task id\n\n`{ctx.task_id}`")
+    if ctx.mission_id:
+        user_blocks.append(f"## Mission id\n\n`{ctx.mission_id}`")
+
+    user = "\n\n".join(user_blocks)
+    return {"system": system, "user": user}

package/omega/Agentik_Engine/omega_engine/executor.py

@@ -99,8 +99,17 @@ class Executor:
         return reduce_task(self._store.events_for(task_id))
 
     def _run(self, task: Task, mission_id: str) -> None:
-        self._emit(task.id, EventType.CREATED,
-                   {"role": task.role, "kind": task.kind.value, "mission_id": mission_id})
+        # Carry the intent/task description in the CREATED payload so the
+        # event log + semantic memory have something searchable per task.
+        intent = (
+            task.spec.get("intent") or task.spec.get("task") or ""
+        )
+        self._emit(task.id, EventType.CREATED, {
+            "role": task.role,
+            "kind": task.kind.value,
+            "mission_id": mission_id,
+            "spec": {"intent": str(intent)[:500]} if intent else {},
+        })
         self._emit(task.id, EventType.DISPATCHED)
         self._emit(task.id, EventType.STARTED)
         if task.kind is Kind.EXECUTOR:
@@ -112,9 +121,8 @@ class Executor:
     def _run_dispatcher(self, task: Task, mission_id: str) -> None:
         provider = self._router.resolve(task.role)
         prompt = task.spec.get("intent") or task.spec.get("task") or task.role
-        result = provider.run(
-            AgentRequest(role=task.role, prompt=str(prompt), context=task.spec)
-        )
+        result = provider.run(self._build_request(task, mission_id, str(prompt)))
+        self._emit_usage(task, provider, result, mission_id)
         children: list[Task] = []
         for item in result.plan:
             child_role = item.get("role", "worker")
@@ -176,12 +184,12 @@ class Executor:
 
     def _run_worker(self, task: Task) -> None:
         provider = self._router.resolve(task.role)
+        prompt = str(task.spec.get("task", task.role))
+        mission_id = task.spec.get("mission_id", "")
         for attempt in range(task.budget.max_iterations):
-            result = provider.run(AgentRequest(
-                role=task.role,
-                prompt=str(task.spec.get("task", task.role)),
-                context=task.spec,
-            ))
+            result = provider.run(self._build_request(task, mission_id, prompt))
+            self._maybe_persist_done(task, result)
+            self._emit_usage(task, provider, result, mission_id)
             self._emit(task.id, EventType.CLAIMED_DONE, {"attempt": attempt + 1})
             self._emit(task.id, EventType.VERIFYING)
             verdict = self._audit.verify({
@@ -191,6 +199,7 @@ class Executor:
                 "changed": result.artifacts.get("files", []),
                 "path": str(task.spec.get("path", ".")),
             })
+            self._attach_audit_to_done(task.id, verdict)
             if verdict.verified:
                 self._emit(task.id, EventType.VERIFIED, {
                     "score": verdict.score,
@@ -205,3 +214,133 @@ class Executor:
                 self._emit(task.id, EventType.STARTED)
         # budget exhausted — honest failure, the deadman clause terminates it
         self._emit(task.id, EventType.FAILED, {"reason": "audit budget exhausted"})
+
+    # ---- envelope + done.json plumbing -------------------------------------
+
+    def _build_request(self, task: Task, mission_id: str, prompt: str) -> AgentRequest:
+        """Build a request enriched with the role's system prompt + context.
+
+        Failures here MUST NOT crash the executor — the engine has always
+        worked with a bare prompt, and old test providers don't read
+        ``request.system``. So we fall back to the legacy AgentRequest if
+        the envelope build fails for any reason.
+        """
+        try:
+            import os
+            from pathlib import Path
+            from omega_engine.envelope import (
+                EnvelopeContext, build_envelope,
+            )
+            from omega_engine.done_signal import done_path
+
+            omega_home = Path(os.environ.get(
+                "OMEGA_HOME", str(Path.home() / "Omega"),
+            ))
+            parent = self._tasks.get(task.parent_id or "")
+            parent_role = parent.role if parent else None
+            parent_intent = (
+                parent.spec.get("intent") if parent else None
+            ) or (parent.spec.get("task") if parent else None)
+
+            ctx = EnvelopeContext(
+                role=task.role,
+                intent=prompt,
+                mission_id=mission_id,
+                task_id=task.id,
+                parent_role=parent_role,
+                parent_intent=parent_intent,
+                verify_cmd=task.spec.get("verify_cmd"),
+                done_json_path=str(done_path(omega_home, task.id)),
+                project=task.spec.get("project"),
+            )
+            env = build_envelope(omega_home, ctx)
+            return AgentRequest(
+                role=task.role, prompt=env["user"], context=task.spec,
+                system=env["system"],
+            )
+        except Exception:  # noqa: BLE001
+            return AgentRequest(
+                role=task.role, prompt=prompt, context=task.spec,
+            )
+
+    def _emit_usage(
+        self, task: Task, provider, result, mission_id: str,
+    ) -> None:
+        """Emit a ``task.usage`` event so the BillingAggregator sees real
+        per-account cost — only when the provider returned non-zero usage.
+
+        ClaudeMaxProvider returns a ``cost_usd`` from Claude Code's own
+        billing computation; we propagate it as-is. Provider id is the
+        ``account_id`` fallback when the operator hasn't pinned this task
+        to a specific account.
+        """
+        try:
+            usage = dict(getattr(result, "usage", {}) or {})
+            if not usage:
+                return
+            if not usage.get("account_id"):
+                # Best-effort: use the provider id as the account label.
+                # When the operator wires multiple Claude Max accounts,
+                # whatever picks one explicitly should also set
+                # account_id on the AgentResult.usage.
+                usage["account_id"] = getattr(provider, "id", "default")
+            self._emit(task.id, EventType.HEARTBEAT, {
+                "kind": "usage", "mission_id": mission_id,
+                "usage": usage, "role": task.role,
+            })
+        except Exception:  # noqa: BLE001 — usage emit must never break the loop
+            pass
+
+    def _maybe_persist_done(self, task: Task, result) -> None:
+        """If the provider returned a structured artifact and no done file
+        exists yet, write one so the audit gate / AISB always have something
+        to read."""
+        try:
+            import os
+            from pathlib import Path
+            from omega_engine.done_signal import (
+                DoneSignal, done_path, read_done, write_done,
+            )
+            omega_home = Path(os.environ.get(
+                "OMEGA_HOME", str(Path.home() / "Omega"),
+            ))
+            # If the worker (or the provider stub) already wrote the file,
+            # respect it.
+            existing = None
+            try:
+                existing = read_done(omega_home, task.id)
+            except Exception:  # noqa: BLE001
+                existing = None
+            if existing is not None:
+                return
+            # Build a synthetic done from the provider result.
+            arts = getattr(result, "artifacts", None) or {}
+            signal = DoneSignal(
+                status="done_clean" if getattr(result, "claimed_done", False)
+                else "failed",
+                summary=str(arts.get("summary") or getattr(result, "text", "")),
+                files_changed=list(arts.get("files") or []),
+                artifacts=arts,
+            )
+            write_done(omega_home, task.id, signal)
+        except Exception:  # noqa: BLE001
+            pass
+
+    def _attach_audit_to_done(self, task_id: str, verdict) -> None:
+        try:
+            import os
+            from pathlib import Path
+            from omega_engine.done_signal import attach_audit_to_done
+            omega_home = Path(os.environ.get(
+                "OMEGA_HOME", str(Path.home() / "Omega"),
+            ))
+            attach_audit_to_done(omega_home, task_id, {
+                "verified": bool(getattr(verdict, "verified", False)),
+                "score": int(getattr(verdict, "score", 0) or 0),
+                "findings": [
+                    getattr(f, "audit", str(f))
+                    for f in getattr(verdict, "findings", []) or []
+                ],
+            })
+        except Exception:  # noqa: BLE001
+            pass