opencommand 0.1.0__py3-none-any.whl

opencommand/modules/skills/powershell.md

@@ -0,0 +1,15 @@
+# PowerShell Skill
+
+Use `powershell` for Windows automation. OpenCommand's `terminal` tool runs
+`cmd.exe /c` on Windows; for PowerShell-specific cmdlets, wrap with
+`powershell -NoProfile -Command "..."`.
+
+## Conventions
+- Use `;` to chain and `&&` (PowerShell 7+) for conditional chains.
+- Prefer `Get-ChildItem`, `Get-Content`, `Select-String` over `dir`/`type`.
+- Manage Python via `uv` (Windows-supported): `uv add`, `uv run`.
+- Services: `Get-Process`, `Start-Process -NoNewWindow`.
+- Paths use backslashes or forward slashes; quote paths with spaces.
+
+## When to use
+- Windows-only tooling, registry, WSL interop, native Windows builds.

opencommand/modules/skills/python.md

@@ -0,0 +1,20 @@
+# Python Skill
+
+OpenCommand targets **Python 3.14** (free-threaded build) and uses **`uv`** for
+all Python environment and task management.
+
+## Conventions
+- Use `uv` everywhere: `uv add <pkg>`, `uv run <module>`, `uv sync`, `uv build`.
+- Target Python >= 3.14; leverage free-threading for parallel worker I/O.
+- Prefer `asyncio` + `TaskGroup` for concurrency; `subprocess` (not `os.popen`,
+  which is soft-deprecated in 3.14) for shelling out.
+- Type hints required; `from __future__ import annotations` is fine (3.14
+  defers annotation evaluation).
+- Use `pathlib.Path`, `logging`, and `dataclasses` over manual boilerplate.
+
+## Testing
+- `uv run pytest` for unit tests; `uv run pytest -q` in CI.
+- For interactive/UI testing, use the `desktop` tool (vision + pyautogui).
+
+## When to use
+- Implementing agents, tools, providers, and the CLI/TUI in OpenCommand.

opencommand/modules/skills/system.md

@@ -0,0 +1,38 @@
+# System Skill
+
+OpenCommand's `system` tool gives the swarm **situational awareness** and
+**safety introspection** over the host machine. Use it for monitoring, scanning,
+and scheduled automation.
+
+## `system` tool actions
+- `list_processes` — snapshot of running processes (pid/name/cpu/mem). Use to
+  spot runaway agents, duplicate loops, or suspicious apps before/after actions.
+- `scan_file <path> <rules>` — run YARA rules over a single file. `rules` is a
+  path to a `.yar` file or inline YARA rule text.
+- `scan_directory <path> <rules>` — recursive YARA scan of a directory
+  (e.g. `Downloads`, build artifacts). `recursive` defaults to true.
+- `watch <path> [seconds=10]` — use `watchdog` to report filesystem changes in
+  a directory (catches new downloads, temp files, agent writes).
+
+> YARA is invoked via the `yara` CLI when present on PATH. If the binary is
+> missing the tool reports it clearly instead of crashing. Install YARA
+> (https://github.com/VirusTotal/yara) to enable scanning.
+
+## Cron utility (`modules/system/cron.py`)
+Schedule recurring tasks without external services. A `CronScheduler` runs jobs
+in the background (asyncio).
+
+Schedule syntax:
+- `every 30m` / `every 1h` — fixed interval
+- `hourly :15` — every hour at minute 15
+- `daily 09:00` — every day at 09:00 local time
+- `*/5 * * * *` — full 5-field cron (requires optional `croniter`)
+
+CLI:
+- `opencommand cron add <name> <schedule> "<command>"` — register a shell job
+- `opencommand cron status` — show scheduler info
+
+## When to use
+- Pre-flight safety checks (list processes, scan a downloaded binary).
+- Watching `Downloads` / build dirs for changes during long autonomous runs.
+- Scheduling maintenance (e.g. `daily 03:00` cleanup, `every 1h` health ping).

opencommand/modules/system/automatic.py

@@ -0,0 +1,151 @@
+"""Automatic mode: the long-running, self-correcting loop.
+
+Runs the Commander's pipeline for a goal, then verifies the result with a real
+test command (exit-code gate, not string matching). On failure it re-dispatches
+a focused fixer with the failing report as context, preserving the original goal
+so the Commander never re-plans from a fix prompt. Loops until tests pass or
+max iterations is hit. This is the main mode for large codebases and hours-long
+autonomous runs.
+
+Phase 6 adds two gates on top of the exit-code check:
+  * a Commander review gate (evaluator-optimizer) that can reject work even when
+    tests pass (wrong thing built, requirements missing);
+  * an optional live-verify hook (the `desktop` tool) for interactive validation
+    when the goal is UI/UX facing.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+
+from ...core.logging import get_logger
+from ...swarm.agents.commander import Commander
+from .notify import default_notifier
+
+log = get_logger("system.automatic")
+
+
+async def run_automatic(commander: Commander, goal: str, max_iterations: int = 5,
+                        verify_cmd: str | None = None, pipeline: str = "standard",
+                        live_verify: bool = False) -> str:
+    """Iteratively execute the goal, auto-fixing failures, until 100% met.
+
+    ``pipeline`` is "standard" or "advanced" (scaffold + research loop +
+    commander review gate + test/debug loop). ``live_verify`` runs the desktop
+    tool as a final interactive check when the goal is UI/UX facing.
+
+    The loop only returns success when BOTH the exit-code verify gate AND the
+    Commander review gate pass (and, if enabled, the live-verify check). If the
+    Commander flags the work as off-track, the whole pipeline is re-run with the
+    failing report as fix context so the swarm re-grounds on the goal.
+    """
+    original_goal = goal
+    if default_notifier.enabled:
+        default_notifier.send(f"Started autonomous run for: {goal[:120]}",
+                              title="OpenCommand: started", priority=3,
+                              tags=["rocket", "opencommand"])
+    last = ""
+    for i in range(max_iterations):
+        log.info("iteration=%d/%d goal=%r pipeline=%s", i + 1, max_iterations,
+                 original_goal, pipeline)
+        last = await _execute(commander, original_goal, pipeline,
+                              verify_cmd=verify_cmd, live_verify=live_verify)
+        # Exit-code gate (real verification, not string matching).
+        if verify_cmd:
+            rc, out = _verify(commander, verify_cmd)
+            if rc != 0:
+                last = (f"{last}\n\n[verify] {verify_cmd} -> FAIL (exit {rc})\n{out}")
+                log.warning("verify FAIL exit=%d iteration=%d", rc, i + 1)
+            else:
+                # Tests pass: now the Commander review gate (evaluator-optimizer).
+                review = await commander.review_goal(original_goal, last)
+                if review.passed and not review.off_track:
+                    if live_verify:
+                        lv = await _live_verify(commander, goal)
+                        if not lv.ok:
+                            last = (f"{last}\n\n[live-verify] FAIL: {lv.summary}\n"
+                                    f"{lv.detail}")
+                            goal = _fix_prompt(original_goal, last)
+                            continue
+                        last = f"{last}\n\n[live-verify] PASS: {lv.summary}"
+                    if default_notifier.enabled:
+                        default_notifier.send(f"Goal complete after {i + 1} iteration(s).",
+                                              title="OpenCommand: success", priority=4,
+                                              tags=["white_check_mark", "opencommand"])
+                    log.info("goal complete after %d iteration(s)", i + 1)
+                    return f"{last}\n\n[verify] {verify_cmd} -> PASS (exit 0)"
+                # Tests pass but Commander says wrong thing built / off track.
+                reason = "OFF TRACK" if review.off_track else "REJECTED"
+                last = (f"{last}\n\n[review] {reason}: {review.feedback}\n"
+                        f"missing: {', '.join(review.missing)}")
+                log.warning("commander %s iteration=%d missing=%s", reason.lower(),
+                            i + 1, review.missing)
+        else:
+            # No verification command: fall back to the old string heuristic.
+            if "FAILED" not in last and "ERROR" not in last:
+                if default_notifier.enabled:
+                    default_notifier.send(f"Goal complete after {i + 1} iteration(s).",
+                                          title="OpenCommand: success", priority=4,
+                                          tags=["white_check_mark", "opencommand"])
+                return last
+        goal = _fix_prompt(original_goal, last)
+    if default_notifier.enabled:
+        default_notifier.send(f"Stopped after {max_iterations} iterations (not resolved).",
+                              title="OpenCommand: stopped", priority=5,
+                              tags=["warning", "opencommand"])
+    return f"(automatic mode stopped after {max_iterations} iterations)\n{last}"
+
+
+async def _execute(commander: Commander, goal: str, pipeline: str,
+                   verify_cmd: str | None = None, live_verify: bool = False) -> str:
+    if pipeline == "advanced":
+        return await commander.execute_advanced(
+            goal, verify_cmd=verify_cmd, live_verify=live_verify)
+    return await commander.execute(goal)
+
+
+def _fix_prompt(original_goal: str, last: str) -> str:
+    return (f"Previous attempt failed. The original goal is still:\n{original_goal}\n\n"
+            f"Fix the issues shown below, then re-run the verification command.\n\n{last}")
+
+
+async def _live_verify(commander: Commander, goal: str) -> "LiveVerifyResult":
+    """Interactive validation via the desktop tool (vision + action loop).
+
+    Returns a LiveVerifyResult. Only meaningful when the desktop tool is wired
+    and vision is enabled; otherwise reports a no-op pass so the pipeline can
+    continue without a UI target.
+    """
+    from ...modules.tools.desktop import DesktopTool
+
+    desktop = next((t for t in commander.tools._tools.values()
+                    if isinstance(t, DesktopTool)), None)
+    if desktop is None or not getattr(desktop, "vision", None):
+        return LiveVerifyResult(ok=True, summary="no desktop tool/vision; skipped",
+                                detail="")
+    try:
+        out = desktop.run(f"Verify the goal is satisfied on screen: {goal}", steps=8)
+    except Exception as e:  # noqa: BLE001
+        return LiveVerifyResult(ok=False, summary="desktop tool error",
+                                detail=str(e))
+    ok = "ERROR" not in out and "done" in out.lower()
+    return LiveVerifyResult(ok=ok, summary="interactive check completed", detail=out)
+
+
+@dataclass
+class LiveVerifyResult:
+    ok: bool = False
+    summary: str = ""
+    detail: str = ""
+
+
+def _verify(commander: Commander, cmd: str) -> tuple[int, str]:
+    """Run the verification command in the workspace; return (rc, output)."""
+    try:
+        proc = subprocess.run(cmd, shell=True, cwd=str(commander.workspace),
+                              capture_output=True, text=True, timeout=600)
+    except subprocess.TimeoutExpired as e:
+        return 124, f"verify timed out: {e}"
+    out = f"STDOUT:\n{proc.stdout}\nSTDERR:\n{proc.stderr}"[:4000]
+    return proc.returncode, out

opencommand/modules/system/cron.py

@@ -0,0 +1,193 @@
+"""Lightweight cron utility for OpenCommand.
+
+Schedules tasks at configurable times without external services. A single
+CronScheduler runs in the background (asyncio) and fires jobs when their
+schedule matches. Supported syntax:
+  - "every 30m" / "every 1h"   fixed interval
+  - "hourly :15"               every hour at minute 15
+  - "daily 09:00"              every day at 09:00 local time
+  - "*/5 * * * *"              5-field cron (requires optional croniter)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Awaitable, Callable
+
+JobFn = Callable[[], Awaitable[None] | None]
+
+
+@dataclass
+class CronJob:
+    name: str
+    schedule: str
+    fn: JobFn
+    command: str = ""  # shell command (serializable)
+    goal: str = ""      # swarm goal (serializable); takes precedence over command
+    last_run: datetime | None = None
+    _interval: timedelta | None = field(default=None, repr=False)
+    _daily_at: tuple[int, int] | None = field(default=None, repr=False)
+    _croniter = None  # optional croniter object
+
+    def __post_init__(self) -> None:
+        self._parse()
+
+    def _parse(self) -> None:
+        s = self.schedule.strip().lower()
+        m = re.fullmatch(r"every\s+(\d+)\s*([mh])", s)
+        if m:
+            n = int(m.group(1))
+            self._interval = timedelta(minutes=n) if m.group(2) == "m" else timedelta(hours=n)
+            return
+        m = re.fullmatch(r"hourly\s*:(\d{1,2})", s)
+        if m:
+            self._daily_at = (0, int(m.group(1)))  # sentinel: hourly at minute
+            return
+        m = re.fullmatch(r"daily\s*(\d{1,2}):(\d{2})", s)
+        if m:
+            self._daily_at = (int(m.group(1)), int(m.group(2)))
+            return
+        try:
+            from croniter import croniter  # type: ignore
+            self._croniter = croniter(s, datetime.now())
+        except Exception:
+            raise ValueError(f"Unsupported cron schedule: {self.schedule!r}")
+
+    def next_run(self, now: datetime) -> datetime:
+        if self._interval is not None:
+            return (self.last_run or now) + self._interval
+        if self._daily_at is not None:
+            hh, mm = self._daily_at
+            if hh == 0:  # hourly at minute mm
+                nxt = now.replace(minute=mm, second=0, microsecond=0)
+                if nxt <= now:
+                    nxt += timedelta(hours=1)
+                return nxt
+            nxt = now.replace(hour=hh, minute=mm, second=0, microsecond=0)
+            if nxt <= now:
+                nxt += timedelta(days=1)
+            return nxt
+        if self._croniter is not None:
+            # get_next() advances the iterator, so compute a non-advancing preview
+            # for status/display; the loop uses _next_fire() which advances once.
+            return self._croniter.get_next(datetime, start_time=now)
+        raise ValueError("no schedule parsed")
+
+    def _next_fire(self, now: datetime) -> datetime:
+        """Advance the croniter to the next fire time (mutates the iterator)."""
+        if self._croniter is not None:
+            return self._croniter.get_next(datetime)
+        return self.next_run(now)
+
+    async def _call(self) -> None:
+        result = self.fn()
+        if asyncio.iscoroutine(result):
+            await result
+
+
+class CronScheduler:
+    """Runs registered jobs in the background until stopped.
+
+    Persisted jobs are either shell ``command``s or swarm ``goal``s. A goal job
+    is dispatched through a callback (set via ``on_goal``) so the scheduler can
+    drive the real Commander/Worker loop instead of just a subprocess.
+    """
+
+    def __init__(self, tick: float = 15.0) -> None:
+        self._jobs: list[CronJob] = []
+        self._tick = tick
+        self._task: asyncio.Task | None = None
+        self._stop = asyncio.Event()
+        self.on_goal: Callable[[str], Awaitable[None]] | None = None
+
+    def add(self, name: str, schedule: str, fn: JobFn) -> CronJob:
+        job = CronJob(name=name, schedule=schedule, fn=fn)
+        self._jobs.append(job)
+        return job
+
+    def schedule_command(self, name: str, schedule: str, command: str) -> CronJob:
+        """Schedule a shell command (runs via subprocess)."""
+        async def _run() -> None:
+            proc = await asyncio.create_subprocess_shell(
+                command, stdout=asyncio.subprocess.DEVNULL, stderr=asyncio.subprocess.DEVNULL)
+            await proc.wait()
+        job = self.add(name, schedule, _run)
+        job.command = command
+        return job
+
+    def schedule_goal(self, name: str, schedule: str, goal: str) -> CronJob:
+        """Schedule a swarm goal; dispatched through ``on_goal`` when fired."""
+        async def _run() -> None:
+            if self.on_goal is not None:
+                res = self.on_goal(goal)
+                if asyncio.iscoroutine(res):
+                    await res
+        job = self.add(name, schedule, _run)
+        job.goal = goal
+        return job
+
+    def save(self, path: Path) -> None:
+        """Persist serializable jobs to <workspace>/.opencommand/cron.json."""
+        path.parent.mkdir(parents=True, exist_ok=True)
+        data = [{"name": j.name, "schedule": j.schedule,
+                 "command": j.command, "goal": j.goal}
+                for j in self._jobs if j.command or j.goal]
+        path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+    @classmethod
+    def load(cls, path: Path) -> "CronScheduler":
+        """Load persisted jobs from cron.json (if present)."""
+        sched = cls()
+        if not path.exists():
+            return sched
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except Exception:
+            return sched
+        for item in data:
+            if item.get("goal"):
+                sched.schedule_goal(item["name"], item["schedule"], item["goal"])
+            else:
+                sched.schedule_command(item["name"], item["schedule"], item.get("command", ""))
+        return sched
+
+    def start(self) -> None:
+        if self._task is None or self._task.done():
+            self._stop.clear()
+            self._task = asyncio.create_task(self._loop())
+
+    async def _loop(self) -> None:
+        while not self._stop.is_set():
+            now = datetime.now()
+            for job in self._jobs:
+                try:
+                    if now >= job._next_fire(now):
+                        job.last_run = now
+                        await job._call()
+                except Exception:  # noqa: BLE001 - a bad job shouldn't kill the loop
+                    pass
+            try:
+                await asyncio.wait_for(self._stop.wait(), timeout=self._tick)
+            except asyncio.TimeoutError:
+                continue
+
+    def stop(self) -> None:
+        self._stop.set()
+
+    def status(self) -> str:
+        now = datetime.now()
+        lines = [f"Cron jobs ({len(self._jobs)}):"]
+        for j in self._jobs:
+            try:
+                nxt = j.next_run(now).strftime("%Y-%m-%d %H:%M:%S")
+            except Exception:
+                nxt = "?"
+            last = j.last_run.strftime("%Y-%m-%d %H:%M:%S") if j.last_run else "never"
+            kind = "goal" if j.goal else ("cmd" if j.command else "fn")
+            lines.append(f"  - {j.name} [{j.schedule}] ({kind}) next={nxt} last={last}")
+        return "\n".join(lines)

opencommand/modules/system/notify.py

@@ -0,0 +1,85 @@
+"""ntfy push notifications for OpenCommand.
+
+Lets the swarm push status / completion / failure alerts to an ntfy topic so
+long-running autonomous runs can be monitored from a phone or another machine.
+Uses the ntfy package with a requests POST fallback. Configure via env vars
+(no secrets in code):
+  NTFY_TOPIC    e.g. https://ntfy.sh/my-secret-topic  (required to send)
+  NTFY_TOKEN    optional bearer token for private servers
+  NTFY_PRIORITY optional 1..5 (default 3)
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+try:
+    from ntfy import notify  # type: ignore
+    _HAVE_NTFY = True
+except Exception:  # pragma: no cover - ntfy is a hard dep but keep import soft
+    notify = None  # type: ignore
+    _HAVE_NTFY = False
+
+
+@dataclass
+class Notifier:
+    """Thin wrapper around ntfy with env-var configuration."""
+
+    topic: str | None = None
+    token: str | None = None
+    priority: int = 3
+    default_tags: list[str] = field(default_factory=lambda: ["robot"])
+
+    def __post_init__(self) -> None:
+        self.topic = self.topic or os.environ.get("NTFY_TOPIC")
+        self.token = self.token or os.environ.get("NTFY_TOKEN")
+        if os.environ.get("NTFY_PRIORITY"):
+            try:
+                self.priority = int(os.environ["NTFY_PRIORITY"])
+            except ValueError:
+                pass
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self.topic)
+
+    def send(self, message: str, *, title: str | None = None,
+             priority: int | None = None, tags: list[str] | None = None) -> bool:
+        """Send a notification. Returns True if sent, False if disabled/unavailable."""
+        if not self.topic:
+            return False
+        prio = priority or self.priority
+        all_tags = (tags or []) + self.default_tags
+        if _HAVE_NTFY and notify is not None:
+            try:
+                notify(message=message, title=title or "OpenCommand", topic=self.topic,
+                        priority=prio, tags=all_tags, auth=self.token)
+                return True
+            except Exception:
+                pass  # fall through to requests fallback
+        return self._send_requests(message, title=title, priority=prio, tags=all_tags)
+
+    def _send_requests(self, message: str, *, title: str | None,
+                       priority: int, tags: list[str]) -> bool:
+        try:
+            import requests
+        except Exception:
+            return False
+        headers = {
+            "Title": (title or "OpenCommand").replace("\n", " "),
+            "Priority": str(priority),
+            "Tags": ",".join(tags),
+        }
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        try:
+            resp = requests.post(self.topic, data=message.encode("utf-8"),
+                                 headers=headers, timeout=15)
+            return resp.ok
+        except Exception:
+            return False
+
+
+# Module-level default notifier (configured from env). Import and call .send().
+default_notifier = Notifier()