@agentikos/omega-os 0.1.0

package/omega/Agentik_Engine/omega_engine/reducer.py

@@ -0,0 +1,76 @@
+"""The reducer — the anti-hallucination core of Omega OS.
+
+A pure function. No agent ever writes a state; the engine REPLAYS events to
+derive it. An illegal transition raises an exception — it never corrupts state.
+
+This is the mechanical answer to "the agent said done and it wasn't": the only
+way to reach VERIFIED is the event `task.verified`, and only the independent
+verifier is allowed to emit that event.
+"""
+from __future__ import annotations
+
+from typing import Iterable, Optional
+
+from omega_engine.events import Event, EventType
+from omega_engine.task import TERMINAL, TaskState
+
+
+class IllegalTransition(Exception):
+    """Raised when an event would drive an illegal FSM transition."""
+
+
+# (current_state, event_type) -> next_state. Anything not listed is illegal.
+# `None` is the pre-creation state.
+_TRANSITIONS: dict[tuple[Optional[TaskState], EventType], TaskState] = {
+    (None,                   EventType.CREATED):      TaskState.PENDING,
+    (TaskState.PENDING,      EventType.DISPATCHED):   TaskState.DISPATCHED,
+    (TaskState.DISPATCHED,   EventType.STARTED):      TaskState.RUNNING,
+    (TaskState.RUNNING,      EventType.CLAIMED_DONE): TaskState.CLAIMED_DONE,
+    (TaskState.CLAIMED_DONE, EventType.VERIFYING):    TaskState.VERIFYING,
+    (TaskState.VERIFYING,    EventType.VERIFIED):     TaskState.VERIFIED,
+    (TaskState.VERIFYING,    EventType.REJECTED):     TaskState.REJECTED,
+    (TaskState.VERIFIED,     EventType.COMPLETED):    TaskState.COMPLETED,
+    (TaskState.REJECTED,     EventType.DISPATCHED):   TaskState.DISPATCHED,  # retry
+}
+
+
+def reduce(state: Optional[TaskState], event: Event) -> TaskState:
+    """Apply one event to one state. Pure. Raises IllegalTransition on a bad move."""
+    # Heartbeats are liveness pings, never transitions.
+    if event.type is EventType.HEARTBEAT:
+        if state is None:
+            raise IllegalTransition("heartbeat before task.created")
+        return state
+
+    # Scope events are not task-state events — the barrier consumes them.
+    if event.type is EventType.SCOPE_JOINABLE:
+        if state is None:
+            raise IllegalTransition("scope.joinable before task.created")
+        return state
+
+    # The deadman: a `task.failed` event terminates ANY live task. This is what
+    # guarantees the join barrier always resolves — no task can hang forever.
+    # `failed` on an already-terminal task remains illegal (handled below).
+    if event.type is EventType.FAILED and state is not None and state not in TERMINAL:
+        return TaskState.FAILED
+
+    key = (state, event.type)
+    if key not in _TRANSITIONS:
+        cur = state.value if state is not None else "<none>"
+        raise IllegalTransition(
+            f"illegal transition: {cur} --{event.type.value}--> ?"
+        )
+    return _TRANSITIONS[key]
+
+
+def reduce_task(events: Iterable[Event]) -> TaskState:
+    """Fold an ordered event stream into the current task state.
+
+    The events MUST be ordered (the Event Store returns them by `ts, id`).
+    """
+    state: Optional[TaskState] = None
+    for ev in events:
+        state = reduce(state, ev)
+    if state is None:
+        raise IllegalTransition("empty event stream — task never created")
+    return state

package/omega/Agentik_Engine/omega_engine/report.py

@@ -0,0 +1,146 @@
+"""Mission reports — every finished mission produces a whitepaper PDF.
+
+`build_report()` turns a MissionResult + the event log into the pdfgen whitepaper
+schema; `render_pdf()` shells out to the pdfgen tool. An Oracle finishing ALWAYS
+emits one of these (wired in omega_engine.mission).
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+import time
+from pathlib import Path
+from typing import Any
+
+from omega_engine.executor import MissionResult
+from omega_engine.reducer import reduce_task
+from omega_engine.store import EventStore
+from omega_engine.task import Kind, TaskState
+
+
+def _resolve_pdfgen() -> str:
+    """Locate the pdfgen tool: OMEGA_PDFGEN env -> Agentik_Tools -> PATH."""
+    env = os.environ.get("OMEGA_PDFGEN")
+    if env and Path(env).exists():
+        return env
+    home = Path(os.environ.get("OMEGA_HOME", str(Path.home() / "Omega")))
+    tool = home / "Agentik_Tools" / "pdfgen" / "bin" / "pdfgen"
+    if tool.exists():
+        return str(tool)
+    on_path = shutil.which("pdfgen")
+    if on_path:
+        return on_path
+    raise RuntimeError(
+        "pdfgen not found — install it into Agentik_Tools/ "
+        "(see omega/Agentik_Tools/README.md) or set $OMEGA_PDFGEN"
+    )
+
+
+def _state(store: EventStore, task_id: str) -> TaskState:
+    return reduce_task(store.events_for(task_id))
+
+
+def build_report(result: MissionResult, store: EventStore) -> dict[str, Any]:
+    """Turn a finished mission into the pdfgen whitepaper schema."""
+    workers = [t for t in result.tasks.values() if t.kind is Kind.EXECUTOR]
+    verified = sum(1 for w in workers if _state(store, w.id) is TaskState.COMPLETED)
+    verdict = "VERIFIED" if result.verified else "FAILED / PARTIAL"
+
+    done_body: list[str] = []
+    for i, w in enumerate(workers, 1):
+        evs = store.events_for(w.id)
+        vr = next((e for e in evs if e.type.value == "task.verified"), None)
+        score = vr.payload.get("score", "—") if vr else "—"
+        done_body.append(
+            f"### Worker {i} — {w.spec.get('task', w.role)}\n\n"
+            f"- Final state: **{_state(store, w.id).value}**\n"
+            f"- Audit score: **{score}/100** (verified by live flow)\n"
+        )
+    if not done_body:
+        done_body = ["No worker tasks were spawned for this mission."]
+
+    test_body = ["The verifier already ran each worker's live flow. To re-check "
+                 "manually, run each command below — exit 0 means the flow passes.\n"]
+    for i, w in enumerate(workers, 1):
+        test_body.append(f"- Worker {i}: `{w.spec.get('verify_cmd', '(none declared)')}`")
+
+    timeline = "\n".join(
+        f"{e.type.value:<22} {e.task_id}" for e in store.all_events()
+    )
+
+    sections = [
+        {"index": "01", "eyebrow": "Mission", "title": "Mission overview",
+         "lead": f"Verdict — {verdict}.",
+         "body": (f"**Intent.** {result.intent}\n\n"
+                  f"**Mission id.** `{result.mission_id}`\n\n"
+                  f"**Result.** {verified} of {len(workers)} worker task(s) "
+                  f"verified. Root final state: **{result.final_state.value}**.\n\n"
+                  f"Completion here is *derived* — the Oracle could not declare "
+                  f"itself done; the join barrier and the audit gate decided it.")},
+        {"index": "02", "eyebrow": "Work", "title": "What was done",
+         "lead": "Every worker, its final state, its audit score.",
+         "body": "\n".join(done_body)},
+        {"index": "03", "eyebrow": "Verification", "title": "What to test",
+         "lead": "The verifier ran the live flow — here is how to re-check it.",
+         "body": "\n".join(test_body)},
+        {"index": "04", "eyebrow": "Trace", "title": "Event timeline",
+         "lead": "The append-only event log — this mission, fully replayable.",
+         "body": "```\n" + (timeline or "(no events)") + "\n```"},
+    ]
+
+    return {
+        "template": "whitepaper",
+        "theme": "agentik",
+        "eyebrow": "OMEGA OS - MISSION REPORT",
+        "title": f"Mission Report - {result.intent[:56]}",
+        "subtitle": f"Verdict: {verdict}. {verified}/{len(workers)} tasks verified.",
+        "author": "Omega OS - Oracle",
+        "date": time.strftime("%d %B %Y"),
+        "docId": result.mission_id.upper(),
+        "brand": "AGENTIK",
+        "abstract": (
+            f"This report documents the Omega OS mission \"{result.intent}\". "
+            f"The Oracle planned the work; {len(workers)} worker task(s) executed "
+            f"it; the audit gate verified each one by running its live flow. "
+            f"{verified} of {len(workers)} were verified. The mission's final "
+            f"state is {result.final_state.value}. Every figure below is derived "
+            f"from the append-only event log — nothing here is self-declared."
+        ),
+        "sections": sections,
+    }
+
+
+def render_pdf(report_data: dict[str, Any], out_path: str | Path,
+               pdfgen_bin: str | None = None) -> Path:
+    """Render the whitepaper JSON to a PDF via the pdfgen tool."""
+    out = Path(out_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    binary = pdfgen_bin or _resolve_pdfgen()
+    fh = tempfile.NamedTemporaryFile("w", suffix=".json", delete=False)
+    try:
+        json.dump(report_data, fh, ensure_ascii=False)
+        fh.close()
+        proc = subprocess.run(
+            [binary, "--template=whitepaper", f"--data={fh.name}",
+             "--theme=agentik", f"--out={out}"],
+            capture_output=True, text=True, timeout=600,
+        )
+    finally:
+        os.unlink(fh.name)
+    if proc.returncode != 0 or not out.exists():
+        raise RuntimeError(
+            f"pdfgen failed: {(proc.stderr or proc.stdout)[-400:]}"
+        )
+    return out
+
+
+def generate_mission_report(result: MissionResult, store: EventStore,
+                            out_dir: str | Path,
+                            pdfgen_bin: str | None = None) -> Path:
+    """Build + render the mission report PDF. Returns the PDF path."""
+    data = build_report(result, store)
+    out = Path(out_dir) / f"mission-report-{result.mission_id}.pdf"
+    return render_pdf(data, out, pdfgen_bin=pdfgen_bin)

package/omega/Agentik_Engine/omega_engine/router.py

@@ -0,0 +1,34 @@
+"""The model router — resolve a task role to a provider.
+
+The router reasons in roles: a cheap model for triage, Claude for code, a
+different model for audit. Backed by Agentik_Providers/registry.yaml.
+"""
+from __future__ import annotations
+
+from omega_engine.provider import AgentProvider
+
+
+class ModelRouter:
+    """Maps a task role to a concrete provider instance."""
+
+    def __init__(
+        self,
+        providers: dict[str, AgentProvider],
+        role_provider: dict[str, str],
+        default: str,
+    ) -> None:
+        if default not in providers:
+            raise ValueError(f"default provider '{default}' is not registered")
+        self._providers = providers
+        self._role_provider = role_provider
+        self._default = default
+
+    def resolve(self, role: str) -> AgentProvider:
+        """Return the provider for a role, falling back to the default."""
+        pid = self._role_provider.get(role, self._default)
+        return self._providers.get(pid, self._providers[self._default])
+
+    @classmethod
+    def single(cls, provider: AgentProvider) -> "ModelRouter":
+        """A router that sends every role to one provider — used for tests."""
+        return cls({provider.id: provider}, {}, provider.id)

package/omega/Agentik_Engine/omega_engine/store.py

@@ -0,0 +1,97 @@
+"""The Event Store — append-only, the single source of runtime truth.
+
+SQLite in WAL mode. `EventStore` is the interface; `SQLiteStore` is the default
+implementation — simple, ample for a VPS. A `RedisStreamStore` can be dropped in
+later behind the same interface if you ever run hundreds of concurrent workers.
+
+Append-only by contract: there is no UPDATE and no DELETE. State is always a
+fold over events (see omega_engine.reducer).
+"""
+from __future__ import annotations
+
+import sqlite3
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Iterator
+
+from omega_engine.events import Event
+
+
+class EventStore(ABC):
+    """The store interface. Swap the implementation, keep the contract."""
+
+    @abstractmethod
+    def append(self, event: Event) -> None:
+        """Append one immutable event."""
+
+    @abstractmethod
+    def events_for(self, task_id: str) -> list[Event]:
+        """All events for one task, ordered by (ts, id)."""
+
+    @abstractmethod
+    def all_events(self, since_ts: float = 0.0) -> Iterator[Event]:
+        """Every event since `since_ts`, ordered — for the bus / projections."""
+
+    @abstractmethod
+    def task_ids(self) -> list[str]:
+        """Every distinct task id seen in the log."""
+
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS events (
+    id       TEXT PRIMARY KEY,
+    task_id  TEXT NOT NULL,
+    type     TEXT NOT NULL,
+    ts       REAL NOT NULL,
+    payload  TEXT NOT NULL DEFAULT '{}'
+);
+CREATE INDEX IF NOT EXISTS idx_events_task ON events(task_id, ts, id);
+CREATE INDEX IF NOT EXISTS idx_events_ts   ON events(ts, id);
+"""
+
+
+class SQLiteStore(EventStore):
+    """Append-only event log on SQLite (WAL). The default store for a VPS."""
+
+    def __init__(self, db_path: str | Path):
+        self.db_path = str(db_path)
+        Path(self.db_path).parent.mkdir(parents=True, exist_ok=True)
+        self._conn = sqlite3.connect(self.db_path, isolation_level=None)
+        self._conn.row_factory = sqlite3.Row
+        self._conn.execute("PRAGMA journal_mode=WAL;")
+        self._conn.execute("PRAGMA synchronous=NORMAL;")
+        self._conn.executescript(_SCHEMA)
+
+    def append(self, event: Event) -> None:
+        self._conn.execute(
+            "INSERT INTO events (id, task_id, type, ts, payload) "
+            "VALUES (:id, :task_id, :type, :ts, :payload)",
+            event.to_row(),
+        )
+
+    def events_for(self, task_id: str) -> list[Event]:
+        # ORDER BY rowid = insertion order — the only correct order for a reducer.
+        # Ordering by `ts` is unsafe: rapid emits can share a timestamp.
+        cur = self._conn.execute(
+            "SELECT * FROM events WHERE task_id = ? ORDER BY rowid", (task_id,)
+        )
+        return [Event.from_row(dict(r)) for r in cur.fetchall()]
+
+    def all_events(self, since_ts: float = 0.0) -> Iterator[Event]:
+        cur = self._conn.execute(
+            "SELECT * FROM events WHERE ts >= ? ORDER BY rowid", (since_ts,)
+        )
+        for r in cur.fetchall():
+            yield Event.from_row(dict(r))
+
+    def task_ids(self) -> list[str]:
+        cur = self._conn.execute("SELECT DISTINCT task_id FROM events")
+        return [r["task_id"] for r in cur.fetchall()]
+
+    def close(self) -> None:
+        self._conn.close()
+
+# NOTE — snapshotting. An append-only log grows without bound. A future
+# `snapshots` table (state of every task at a checkpoint ts) lets `reduce_task`
+# start from the last snapshot instead of replaying from genesis. Snapshots live
+# in Agentik_Runtime/snapshots/. Not required for correctness — only for scale.

package/omega/Agentik_Engine/omega_engine/supervisor.py

@@ -0,0 +1,69 @@
+"""The supervisor — deadman + watchdog.
+
+Every task carries a Budget (max iterations, wall deadline, heartbeat interval).
+The supervisor scans live tasks and, for any that breached its budget — silent
+past `heartbeat_interval_s`, past `deadline_epoch`, or past `max_iterations`
+retries — emits a `task.failed` event with a reason.
+
+The reducer's deadman clause turns that event into a terminal FAILED state,
+which is what guarantees every join barrier eventually resolves: no task, and
+therefore no scope, can hang forever.
+
+The cron is only a cold backstop; the live path is the event bus.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+from omega_engine.events import Event, EventType
+from omega_engine.reducer import reduce_task
+from omega_engine.store import EventStore
+from omega_engine.task import TERMINAL, Budget
+
+
+@dataclass
+class StallReport:
+    task_id: str
+    reason: str  # "heartbeat" | "deadline" | "max_iterations"
+
+
+def find_stalled(
+    store: EventStore,
+    budgets: dict[str, Budget],
+    now: float | None = None,
+) -> list[StallReport]:
+    """Scan live tasks; report those that breached their budget.
+
+    Read-only: returns reports, emits nothing. Safe to dry-run. The caller
+    decides whether to append the resulting `task.failed` events.
+    """
+    now = now if now is not None else time.time()
+    reports: list[StallReport] = []
+    for task_id in store.task_ids():
+        events = store.events_for(task_id)
+        if not events:
+            continue
+        if reduce_task(events) in TERMINAL:
+            continue
+        budget = budgets.get(task_id, Budget())
+        last_ts = max(e.ts for e in events)
+        if now - last_ts > budget.heartbeat_interval_s:
+            reports.append(StallReport(task_id, "heartbeat"))
+            continue
+        if budget.deadline_epoch is not None and now > budget.deadline_epoch:
+            reports.append(StallReport(task_id, "deadline"))
+            continue
+        retries = sum(1 for e in events if e.type is EventType.REJECTED)
+        if retries >= budget.max_iterations:
+            reports.append(StallReport(task_id, "max_iterations"))
+    return reports
+
+
+def deadman_event(report: StallReport) -> Event:
+    """Build the terminal `task.failed` event for a stalled task."""
+    return Event(
+        task_id=report.task_id,
+        type=EventType.FAILED,
+        payload={"reason": f"deadman:{report.reason}"},
+    )

package/omega/Agentik_Engine/omega_engine/task.py

@@ -0,0 +1,91 @@
+"""Core task model for the Omega OS orchestration engine.
+
+Everything the engine executes — AISB, oracle, worker, audit, autonomous agent —
+is a Task. The only thing that differs is `kind`.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+
+class TaskState(str, Enum):
+    """The completion FSM. See docs/ENGINE-SPEC.md.
+
+    The crux: a task is never trusted at CLAIMED_DONE. Only VERIFIED — set by an
+    independent verifier that ran the real flow — counts for a parent's barrier.
+    """
+
+    PENDING = "pending"
+    DISPATCHED = "dispatched"
+    RUNNING = "running"
+    CLAIMED_DONE = "claimed_done"  # the executor *thinks* it finished — NOT trusted
+    VERIFYING = "verifying"        # the audit gate is running
+    VERIFIED = "verified"          # validated by an independent third party
+    REJECTED = "rejected"          # audits failed → retry within budget
+    COMPLETED = "completed"        # terminal — success
+    FAILED = "failed"              # terminal — budget exhausted / stall / honest block
+
+
+#: The only states from which nothing further happens.
+TERMINAL: frozenset[TaskState] = frozenset({TaskState.COMPLETED, TaskState.FAILED})
+
+
+class Kind(str, Enum):
+    """What role a node plays in the graph. The engine treats all kinds uniformly
+    through the same reducer; only the orchestration layer assigns behaviour."""
+
+    DISPATCHER = "dispatcher"  # owns a scope, spawns children (AISB, oracle)
+    EXECUTOR = "executor"      # does bounded work (worker)
+    VERIFIER = "verifier"      # runs the audit gate — independent of the executor
+
+
+class Lifecycle(str, Enum):
+    """Ephemeral tasks end. Persistent tasks are autonomous agents."""
+
+    EPHEMERAL = "ephemeral"
+    PERSISTENT = "persistent"
+
+
+@dataclass(frozen=True)
+class Trigger:
+    """What wakes a task. Mission tasks have no trigger; autonomous agents do."""
+
+    type: str  # "cron" | "event" | "webhook" | "channel"
+    config: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Budget:
+    """Every task is bounded — no infinite loops, no infinite hangs (principle 6)."""
+
+    max_iterations: int = 3
+    deadline_epoch: Optional[float] = None  # wall-clock hard stop
+    heartbeat_interval_s: int = 120         # silence longer than this → deadman
+
+
+@dataclass
+class Task:
+    """A unit of execution at any level of the graph.
+
+    `state` here is a CACHE for convenience. The authoritative state is always
+    `reduce_task(events_for(task.id))` — events are the source of truth.
+    """
+
+    id: str
+    kind: Kind
+    role: str                          # "aisb" | "oracle" | "worker" | ...
+    spec: dict[str, Any]               # the brief
+    parent_id: Optional[str] = None
+    state: TaskState = TaskState.PENDING
+    lifecycle: Lifecycle = Lifecycle.EPHEMERAL
+    trigger: Optional[Trigger] = None
+    budget: Budget = field(default_factory=Budget)
+    provider: Optional[str] = None     # resolved by the model router
+    iteration: int = 0                 # incremented on each retry
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+    def is_terminal(self) -> bool:
+        return self.state in TERMINAL

package/omega/Agentik_Engine/omega_engine/telegram.py

@@ -0,0 +1,115 @@
+"""Telegram bridge — live progress in topics, PDF delivery, topic creation.
+
+Each project maps to a forum topic. A mission posts a progress message into its
+topic and edits it as work advances; the Oracle's final mission-report PDF is
+delivered into the same topic. Creating a project creates its topic.
+
+All calls go through `curl` — reliable, no extra dependency.
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import time
+from pathlib import Path
+
+
+class TelegramError(RuntimeError):
+    pass
+
+
+class TelegramBridge:
+    API = "https://api.telegram.org"
+
+    def __init__(self, token: str, group_chat_id: str) -> None:
+        self._token = token
+        self._group = str(group_chat_id)
+
+    @classmethod
+    def from_vault(cls, omega_home: str | Path | None = None) -> "TelegramBridge":
+        """Build the bridge from Agentik_Extra/etc/secrets/telegram.env."""
+        home = Path(omega_home or os.environ.get(
+            "OMEGA_HOME", str(Path.home() / "Omega")))
+        env_file = home / "Agentik_Extra" / "etc" / "secrets" / "telegram.env"
+        if not env_file.exists():
+            raise TelegramError(f"telegram secret not found: {env_file}")
+        vals: dict[str, str] = {}
+        for line in env_file.read_text().splitlines():
+            line = line.strip()
+            if "=" in line and not line.startswith("#"):
+                key, _, value = line.partition("=")
+                vals[key.strip()] = value.strip()
+        token = vals.get("TELEGRAM_TOKEN")
+        if not token:
+            raise TelegramError("TELEGRAM_TOKEN missing from the vault")
+        return cls(token, vals.get("TELEGRAM_GROUP_CHAT_ID", ""))
+
+    # -- low level ------------------------------------------------------------
+    def _call(self, method: str, fields: dict,
+              files: dict | None = None, _retry: bool = True) -> dict:
+        cmd = ["curl", "-s", "-X", "POST",
+               f"{self.API}/bot{self._token}/{method}"]
+        for key, value in fields.items():
+            cmd += ["-F", f"{key}={value}"]
+        for key, path in (files or {}).items():
+            cmd += ["-F", f"{key}=@{path}"]
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=180)
+        try:
+            data = json.loads(proc.stdout or "{}")
+        except json.JSONDecodeError as exc:
+            raise TelegramError(
+                f"bad Telegram response: {proc.stdout[:200]}") from exc
+        if not data.get("ok"):
+            # respect Telegram flood control: on 429, wait the advised delay
+            # and retry exactly once.
+            if data.get("error_code") == 429 and _retry:
+                wait = int(data.get("parameters", {}).get("retry_after", 5)) + 1
+                time.sleep(min(wait, 60))
+                return self._call(method, fields, files, _retry=False)
+            raise TelegramError(
+                f"{method}: {data.get('description', proc.stdout[:200])}")
+        return data["result"]
+
+    # -- public ---------------------------------------------------------------
+    def check(self) -> str:
+        """Validate the token; return the bot username."""
+        return self._call("getMe", {})["username"]
+
+    def post(self, topic_id: int, text: str) -> int:
+        """Post a message into a forum topic; return the message id."""
+        result = self._call("sendMessage", {
+            "chat_id": self._group,
+            "message_thread_id": topic_id,
+            "text": text,
+        })
+        return result["message_id"]
+
+    def edit(self, message_id: int, text: str) -> None:
+        """Edit a posted message — the live progress-bar update."""
+        self._call("editMessageText", {
+            "chat_id": self._group,
+            "message_id": message_id,
+            "text": text,
+        })
+
+    def delete(self, message_id: int) -> None:
+        self._call("deleteMessage",
+                   {"chat_id": self._group, "message_id": message_id})
+
+    def send_document(self, topic_id: int, path: str | Path,
+                      caption: str = "") -> int:
+        """Deliver a file (the mission-report PDF) into a topic."""
+        result = self._call(
+            "sendDocument",
+            {"chat_id": self._group, "message_thread_id": topic_id,
+             "caption": caption},
+            files={"document": str(path)},
+        )
+        return result["message_id"]
+
+    def create_topic(self, name: str) -> int:
+        """Create a forum topic — used when a new project is created."""
+        result = self._call("createForumTopic",
+                             {"chat_id": self._group, "name": name})
+        return result["message_thread_id"]

package/omega/Agentik_Engine/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "omega-engine"
+version = "0.1.0"
+description = "The Omega OS orchestration engine — event-sourced, verified-completion agent graphs."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+dependencies = [
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+providers = [
+    "anthropic>=0.40",
+]
+dev = [
+    "pytest>=8.0",
+]
+
+[project.scripts]
+omega = "omega_engine.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["omega_engine"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]