@agentikos/omega-os 0.1.0

package/docs/MCP-AND-PLUGINS.md

@@ -0,0 +1,121 @@
+# Omega OS — MCP Servers & Claude Code Plugins
+
+> Where MCP lives, how the installer offers it, and how it reaches every
+> provider.
+
+---
+
+## 1. An MCP is three things
+
+An MCP server is not one artifact — it has three aspects, each with a natural
+home in the 8-block rack:
+
+| Aspect | Block | Why |
+|---|---|---|
+| The **server binary** (Composio, Higgsfield, filesystem…) | `Agentik_Tools/` | third-party installed software — like n8n or ollama |
+| The **catalog + canonical config** (which MCP, args, scopes) | `Agentik_SSOT/mcp/` | truth/config — neutral, versioned, projected to each provider by its adapter |
+| The **secrets** (API keys for Composio, GitHub tokens…) | `Agentik_Extra/etc/secrets/` | sensitive — encrypted vault, never in git |
+
+So the answer to *"SSOT or Orchestration?"* is: **the catalog and config live in
+`Agentik_SSOT/mcp/`** — it is truth/config, not orchestration logic. The
+`connection-educator` (which lives in `Agentik_Orchestration/educators/`)
+*generates and maintains* that config into the SSOT. Orchestration owns the
+educator; the SSOT owns the artifact.
+
+---
+
+## 2. The catalog
+
+`Agentik_SSOT/mcp/mcp-catalog.yaml` lists every MCP server (and Claude Code
+plugin) the installer can offer. Each entry:
+
+```yaml
+- id: composio
+  name: Composio
+  description: 250+ app integrations behind one MCP server
+  category: integrations
+  install: { method: npx, package: "@composio/mcp" }
+  secrets: [COMPOSIO_API_KEY]
+  recommended: true
+```
+
+The installer's `40-mcp` step reads this catalog and presents it as a checklist
+(interactive) or applies a selection from the manifest (headless).
+
+## 3. Canonical config → per-provider projection
+
+The selected MCPs are written to `Agentik_SSOT/mcp/mcp-config.yaml` in a
+neutral form. Each provider adapter *projects* it into that provider's native
+shape:
+
+```
+Agentik_SSOT/mcp/mcp-config.yaml   (neutral, canonical)
+        │  provider adapter
+        ├──▶ claude  →  ~/.claude/.mcp.json  /  settings.json  mcpServers
+        ├──▶ glm     →  <glm-native MCP config>
+        └──▶ openai  →  <openai-native tool/MCP config>
+```
+
+Add a new LLM later → write one adapter projection; the MCP catalog and config
+are reused as-is.
+
+---
+
+## 4. The curated catalog (shipped)
+
+The installer ships a curated catalog. Defaults marked ✓ are pre-selected:
+
+| MCP / Plugin | Category | Default |
+|---|---|---|
+| filesystem | core | ✓ |
+| git | core | ✓ |
+| github | dev | ✓ |
+| Composio (250+ app connectors) | integrations | ✓ |
+| Higgsfield (image / video generation) | media | |
+| Notion | docs | |
+| Slack | comms | |
+| Linear | project mgmt | |
+| Playwright (browser / runtime audits) | testing | ✓ |
+| context7 (live library docs) | dev | ✓ |
+| fetch (web fetch) | core | ✓ |
+| memory (knowledge graph) | core | |
+| sequential-thinking | reasoning | |
+| Sentry | observability | |
+| Postgres | data | |
+| Brave Search | search | |
+
+Plus the **Claude Code plugin marketplace** — the same plugins offered in the
+Claude desktop app under *Connectors → Customize*. The installer queries the
+marketplace and lists them in the same checklist, so a fresh VPS can be brought
+up with the full plugin suite in one pass.
+
+---
+
+## 5. Install flow (`40-mcp` step)
+
+```
+read Agentik_SSOT/mcp/mcp-catalog.yaml
+   │
+   ├─ interactive  → TUI checklist (recommended pre-ticked)
+   └─ headless     → apply `mcp:` list from the manifest
+   │
+for each selected entry:
+   ├─ install the server binary into Agentik_Tools/<id>/
+   ├─ prompt for / read its secrets → Agentik_Extra/etc/secrets/ (vault)
+   └─ add it to Agentik_SSOT/mcp/mcp-config.yaml
+   │
+omega sync   → each provider adapter projects mcp-config.yaml to its native format
+```
+
+The step is idempotent: re-running it adds new selections without disturbing
+existing ones.
+
+---
+
+## 6. Security
+
+MCP secrets never touch the git-tracked tree. They live in
+`Agentik_Extra/etc/secrets/` — an encrypted vault (age/sops or the OS keyring).
+The installer writes a *reference* to the secret in `mcp-config.yaml`
+(`secret_ref: COMPOSIO_API_KEY`), never the value. Provider adapters resolve the
+reference at projection time.

package/docs/RUNTIME-PLAN.md

@@ -0,0 +1,63 @@
+# Omega OS — Runtime Build Plan
+
+> From "scaffold" to "runs a real mission". Every item below is **coded and
+> tested**, not specified. Done = the e2e test passes and a real PDF is produced.
+
+## Goal
+
+OmegaOS executes a real mission end-to-end — `AISB → Oracle → Manager → Worker →
+Verifier → VERIFIED` — an Oracle finishing **always** emits a whitepaper PDF
+report, progress is tracked live to Telegram topics with a progress bar, and
+creating a project builds its structure + Telegram topic.
+
+## Phase A — the runtime core (missions actually run)
+
+| Module | Role |
+|---|---|
+| `bus.py` | in-process event bus — append to store + push to subscribers |
+| `provider.py` | `AgentProvider` contract + `MockProvider` (deterministic, testable) + `ClaudeProvider` (real Anthropic SDK) |
+| `router.py` | model router — role → provider |
+| `audit.py` | the audit gate — `CLAIMED_DONE → VERIFIED/REJECTED`, incl. a runtime audit |
+| `executor.py` | **the topology executor** — runs the graph, scopes, join barrier, dispatch, audit |
+
+**Done when:** `tests/test_executor.py` runs a full mission with `MockProvider`
+and asserts it reaches `VERIFIED`, the barrier resolved, all events legal.
+
+## Phase B — reporting (Oracle → PDF, always)
+
+| Module | Role |
+|---|---|
+| `report.py` | mission + event log → whitepaper JSON → `pdfgen` → PDF |
+| Tools integration | `pdfgen` registered in `Agentik_Tools/` (registry + installer step) |
+
+**Done when:** a finished mission produces a real `.pdf` via `pdfgen
+--template=whitepaper --theme=agentik`, verified on disk.
+
+## Phase C — Telegram & progress
+
+| Module | Role |
+|---|---|
+| `progress.py` | bus subscriber — per-mission progress model + progress-bar render |
+| `telegram.py` | Telegram bridge — post/edit progress in a topic, deliver the PDF |
+
+**Done when:** a live progress message posts and updates in a Telegram topic;
+the PDF is delivered.
+
+## Phase D — projects
+
+| Module | Role |
+|---|---|
+| `project.py` | `create_project(name)` — structure + registry + Telegram topic + routing |
+
+**Done when:** `omega project create <name>` builds the project tree and a bound
+Telegram topic.
+
+## Phase E — wire-up
+
+`cli.py` gains `omega run`, `omega project`, `omega report`. The installer
+registers `pdfgen`. Docs updated. Full verification re-run, green.
+
+## Test discipline
+
+Every module ships with a test. The terminal proof is the e2e: a mission runs,
+an Oracle finishes, a PDF lands. No module is "done" until its test passes.

package/install.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Omega OS — installer entry point.
+#
+# Usage:
+#   bash install.sh [--profile vps|workstation|minimal]
+#                   [--manifest FILE] [--non-interactive] [--force]
+#
+# Idempotent and resumable: completed steps are recorded; re-running resumes.
+set -euo pipefail
+
+REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=bootstrap/lib/common.sh
+source "$REPO_DIR/bootstrap/lib/common.sh"
+# shellcheck source=bootstrap/lib/steps.sh
+source "$REPO_DIR/bootstrap/lib/steps.sh"
+
+PROFILE="vps"; MANIFEST=""; NONINTERACTIVE=0; FORCE=0
+[ "$(uname -s)" = "Darwin" ] && PROFILE="workstation"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --profile)         PROFILE="${2:?}"; shift 2 ;;
+    --manifest)        MANIFEST="${2:?}"; NONINTERACTIVE=1; shift 2 ;;
+    --non-interactive) NONINTERACTIVE=1; shift ;;
+    --force)           FORCE=1; shift ;;
+    -h|--help)         grep '^#' "$0" | tail -n +2 | sed 's/^#\{1,\} \{0,1\}//'; exit 0 ;;
+    *)                 die "unknown argument: $1" ;;
+  esac
+done
+export PROFILE MANIFEST NONINTERACTIVE FORCE OMEGA_REPO="$REPO_DIR"
+
+detect_os
+mkdir -p "$STATE_DIR/logs"
+[ "$FORCE" = "1" ] && reset_state
+
+echo
+echo "  Omega OS — installer"
+echo "  profile=$PROFILE  os=$OMEGA_OS  home=$OMEGA_HOME"
+echo
+
+run_step 00-preflight    step_preflight
+run_step 10-system-deps  step_system_deps
+run_step 20-structure    step_structure
+run_step 30-engine       step_engine
+run_step 40-mcp          step_mcp
+if [ "$PROFILE" != "minimal" ]; then
+  run_step 50-telegram   step_telegram
+fi
+run_step 60-services     step_services
+run_step 70-doctor       step_doctor
+
+echo
+ok "Omega OS installed at $OMEGA_HOME"
+log "  next:  export OMEGA_HOME=$OMEGA_HOME && \"$OMEGA_HOME/Agentik_Tools/bin/omega\" status"

package/omega/Agentik_Coding/README.md

@@ -0,0 +1,21 @@
+# Agentik_Coding — your projects
+
+> **Nature:** your work · **Lifecycle:** very fluid · **Git:** each project is its own repo
+
+Every project Omega OS works on lives here. One sub-folder per project; each
+project maps to a **topic** in the Telegram forum group — reply in a topic and
+the mission routes to that project.
+
+```
+Agentik_Coding/
+├── projects/      one sub-folder per project (each its own git repo)
+└── worktrees/     ephemeral git worktrees — workers check out here so parallel
+                   workers never collide on the same working tree
+```
+
+Both `projects/` and `worktrees/` are populated per deployment and are
+git-ignored by the OmegaOS repo (they are *your* repos, not part of the product).
+
+A worker that touches files in a project does so inside a dedicated worktree in
+`worktrees/`; its file scope (`spec.scope.files_owned`) is the lock that lets the
+Manager run scope-disjoint workers in parallel.

package/omega/Agentik_Engine/README.md

@@ -0,0 +1,58 @@
+# Agentik_Engine — the orchestration engine
+
+> **Nature:** the engine + runtime · **Lifecycle:** the core of the system · **Git:** dedicated repo
+
+This block runs missions. It is business-agnostic: it executes graphs of `Task`s
+with verified completion. *Who* is an oracle and *which* topology runs lives in
+`Agentik_Orchestration/` — the engine never hard-codes it.
+
+## Modules — all implemented, all tested
+
+| Module | Role |
+|---|---|
+| `task.py` | `Task` model, `TaskState` FSM, `Kind`, `Lifecycle`, `Trigger`, `Budget` |
+| `events.py` | immutable `Event` + `EventType` — the source of truth |
+| `reducer.py` | the **pure** reducer `(state, event) → state` + legal transition table |
+| `barrier.py` | the join barrier — `RUNNING / PARTIAL / JOINABLE` |
+| `store.py` | append-only `EventStore` + `SQLiteStore` (WAL, rowid-ordered) |
+| `bus.py` | the event bus — append to the store, push to subscribers |
+| `provider.py` | `AgentProvider` contract + `MockProvider` + `ClaudeProvider` |
+| `router.py` | the model router — role → provider |
+| `audit.py` | the simple audit gate — `CLAIMED_DONE → VERIFIED/REJECTED`, incl. a runtime audit |
+| `audit_arsenal.py` | the Quality Arsenal — 18 forensic audits as the verification gate |
+| `executor.py` | **the topology executor** — runs the mission graph, scopes, barrier |
+| `progress.py` | live progress tracking — a bus subscriber → progress bar |
+| `report.py` | mission → whitepaper JSON → `pdfgen` → PDF |
+| `telegram.py` | the Telegram bridge — topics, live progress, PDF delivery |
+| `project.py` | project creation — structure, registry, bound Telegram topic |
+| `mission.py` | the mission coordinator — `run_mission()` ties it all together |
+| `supervisor.py` | the deadman / watchdog — stall → `task.failed` |
+| `cli.py` | the `omega` CLI — `run`, `project`, `doctor`, `status`, `account`, … |
+
+## Tests
+
+```bash
+cd Agentik_Engine
+for t in reducer executor progress project report mission; do
+  python3 tests/test_$t.py
+done
+```
+
+23 tests, all green — including an **end-to-end mission** (a real mission runs to
+`VERIFIED`) and **live PDF generation** through the `pdfgen` tool.
+
+## Run a mission
+
+```bash
+omega run "fix the pricing bug"      # Oracle plans → workers → verifier → PDF report
+omega project "My Project"           # structure + registry + Telegram topic
+omega status                         # every task and its derived state
+```
+
+`omega run` uses the real `ClaudeProvider` when `ANTHROPIC_API_KEY` is set,
+otherwise the deterministic `MockProvider` — so it always works.
+
+## The one rule
+
+No agent ever writes a `TaskState`. Agents append `Event`s; the state is always
+`reduce_task(store.events_for(task_id))`.

package/omega/Agentik_Engine/omega_engine/__init__.py

@@ -0,0 +1,58 @@
+"""Omega OS orchestration engine.
+
+Event-sourced, verified-completion agent graphs. The engine is business-agnostic:
+it executes graphs of Tasks. Who is an "oracle" and which topology runs lives in
+Agentik_Orchestration/, never here.
+"""
+from omega_engine.audit import AuditFinding, AuditGate, AuditVerdict
+from omega_engine.audit_arsenal import (
+    ArsenalGate,
+    ArsenalVerdict,
+    Audit,
+    AuditRegistry,
+    run_forensic_audit,
+)
+from omega_engine.barrier import ScopeStatus, scope_status
+from omega_engine.bus import EventBus
+from omega_engine.events import Event, EventType
+from omega_engine.executor import Executor, MissionResult
+from omega_engine.progress import MissionProgress, ProgressTracker
+from omega_engine.provider import (
+    AgentProvider,
+    AgentRequest,
+    AgentResult,
+    ClaudeProvider,
+    MockProvider,
+)
+from omega_engine.reducer import IllegalTransition, reduce, reduce_task
+from omega_engine.router import ModelRouter
+from omega_engine.store import EventStore, SQLiteStore
+from omega_engine.task import (
+    TERMINAL,
+    Budget,
+    Kind,
+    Lifecycle,
+    Task,
+    TaskState,
+    Trigger,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # task model + FSM
+    "Task", "TaskState", "TERMINAL", "Kind", "Lifecycle", "Trigger", "Budget",
+    # events + reducer
+    "Event", "EventType", "reduce", "reduce_task", "IllegalTransition",
+    # barrier
+    "ScopeStatus", "scope_status",
+    # store + bus
+    "EventStore", "SQLiteStore", "EventBus",
+    # providers + router
+    "AgentProvider", "AgentRequest", "AgentResult", "MockProvider",
+    "ClaudeProvider", "ModelRouter",
+    # audit + executor + progress
+    "AuditGate", "AuditVerdict", "AuditFinding",
+    "Executor", "MissionResult", "ProgressTracker", "MissionProgress",
+]

package/omega/Agentik_Engine/omega_engine/audit.py

@@ -0,0 +1,96 @@
+"""The audit gate — the CLAIMED_DONE -> VERIFIED transition.
+
+A task is VERIFIED only if the gate passes. The gate runs a set of audit checks
+and aggregates a score. One check — the runtime audit — actually EXECUTES a
+command (the real flow). The verifier is independent: it never trusts the
+worker's claim, it observes the system running.
+"""
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+
+@dataclass
+class AuditFinding:
+    audit: str
+    score: int          # 0-100
+    detail: str = ""
+
+
+@dataclass
+class AuditVerdict:
+    score: int          # aggregate 0-100
+    verified: bool
+    findings: list[AuditFinding] = field(default_factory=list)
+
+
+#: An audit check: inspect the task context, return a finding.
+AuditCheck = Callable[[dict[str, Any]], AuditFinding]
+
+
+def audit_artifacts_present(ctx: dict[str, Any]) -> AuditFinding:
+    """Static audit — the worker actually produced something."""
+    artifacts = ctx.get("artifacts", {}) or {}
+    ok = bool(artifacts.get("files") or artifacts.get("summary"))
+    return AuditFinding(
+        "artifacts-present",
+        100 if ok else 0,
+        "artifacts found" if ok else "no artifacts produced",
+    )
+
+
+def audit_runtime_flow(ctx: dict[str, Any]) -> AuditFinding:
+    """Runtime audit — RUN the real flow.
+
+    `ctx['runtime_cmd']` is executed; exit 0 = pass. This is validate-live: the
+    verifier does not read code and nod, it runs the thing. No command declared
+    is itself a finding (you cannot verify what you cannot run).
+    """
+    cmd = ctx.get("runtime_cmd")
+    if not cmd:
+        return AuditFinding("runtime-flow", 0, "no runtime command declared")
+    try:
+        proc = subprocess.run(
+            cmd, shell=True, capture_output=True, text=True, timeout=120
+        )
+    except subprocess.TimeoutExpired:
+        return AuditFinding("runtime-flow", 0, "runtime command timed out")
+    if proc.returncode == 0:
+        return AuditFinding("runtime-flow", 100, "live flow passed")
+    return AuditFinding(
+        "runtime-flow", 0,
+        f"exit {proc.returncode}: {(proc.stderr or proc.stdout)[:200]}",
+    )
+
+
+class AuditGate:
+    """Runs the audit checks, aggregates, decides VERIFIED vs REJECTED.
+
+    Default gate = artifacts-present + runtime-flow. The runtime audit is what
+    makes completion un-fakeable: a task is VERIFIED only if its real flow ran.
+    """
+
+    def __init__(
+        self,
+        checks: list[AuditCheck] | None = None,
+        threshold: int = 85,
+    ) -> None:
+        self._checks: list[AuditCheck] = (
+            checks if checks is not None
+            else [audit_artifacts_present, audit_runtime_flow]
+        )
+        self._threshold = threshold
+
+    def verify(self, ctx: dict[str, Any]) -> AuditVerdict:
+        findings = [check(ctx) for check in self._checks]
+        score = (
+            round(sum(f.score for f in findings) / len(findings))
+            if findings else 0
+        )
+        return AuditVerdict(
+            score=score,
+            verified=score >= self._threshold,
+            findings=findings,
+        )