opencommand 0.1.2__tar.gz → 0.1.3__tar.gz

{opencommand-0.1.2 → opencommand-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: opencommand
-Version: 0.1.2
+Version: 0.1.3
 Summary: Local-first swarm agent framework: a Commander plans and dispatches a swarm of Workers that research, code, test, and interactively drive the computer to complete long-horizon codebase goals.
 Author: DSiENT
 Author-email: DSiENT <w.caskey7@gmail.com>
@@ -16,6 +16,7 @@ Requires-Dist: llama-cpp-python>=0.3.33
 Requires-Dist: huggingface-hub>=0.30.0
 Requires-Dist: watchdog>=6.0.0
 Requires-Dist: ntfy>=2.7.1
+Requires-Dist: yara-python>=4.5.0
 Requires-Python: >=3.14
 Project-URL: Homepage, https://github.com/D5-Interactive/OpenCommand
 Project-URL: Repository, https://github.com/D5-Interactive/OpenCommand

{opencommand-0.1.2 → opencommand-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "opencommand"
-version = "0.1.2"
+version = "0.1.3"
 description = "Local-first swarm agent framework: a Commander plans and dispatches a swarm of Workers that research, code, test, and interactively drive the computer to complete long-horizon codebase goals."
 readme = "README.md"
 authors = [
@@ -20,6 +20,7 @@ dependencies = [
     "huggingface_hub>=0.30.0",
     "watchdog>=6.0.0",
     "ntfy>=2.7.1",
+    "yara-python>=4.5.0",
 ]
 
 [project.scripts]

{opencommand-0.1.2 → opencommand-0.1.3}/src/opencommand/cli.py

@@ -47,7 +47,10 @@ def _build_tools(engine: Engine, cfg: OpenCommandConfig) -> ToolRegistry:
     reg.register(PlaywrightTool())
     reg.register(SystemTool())
     vision_role = cfg.vision_model if cfg.vision else None
-    reg.register(DesktopTool(engine.runner(vision_role) if vision_role else None))
+    from .modules.tools.desktop_safety import DesktopPolicy
+    desktop_policy = DesktopPolicy.from_dict(cfg.desktop_policy)
+    reg.register(DesktopTool(engine.runner(vision_role) if vision_role else None,
+                             policy=desktop_policy))
     return reg
 
 
@@ -57,7 +60,7 @@ def _load_cfg(path: str | None) -> OpenCommandConfig:
 
 
 @click.group()
-@click.version_option(version="0.1.1")
+@click.version_option(version="0.1.3")
 @click.option("-v", "--verbose", is_flag=True, help="Enable verbose (DEBUG) logging.")
 def cli(verbose: bool) -> None:
     """OpenCommand  -  all-in-one local model runner & command center."""
@@ -149,6 +152,8 @@ def _build_rebuild_command(cmake_args: str) -> tuple:
 @click.argument("path", required=False)
 def config(path: str | None) -> None:
     """Interactive menu to set advanced swarm settings (persisted to config.json)."""
+    from .modules.tools.desktop_safety import DesktopPolicy
+
     cfg = _load_cfg(path)
     click.echo(click.style("OpenCommand configuration", fg="cyan", bold=True))
     click.echo(f"Workspace: {cfg.workspace}\n")
@@ -179,6 +184,21 @@ def config(path: str | None) -> None:
     cfg.goal_file = click.prompt(
         "Session goal spec file name", default=cfg.goal_file)
 
+    # --- Desktop takeover safety policy ------------------------------------
+    click.echo(click.style("\nDesktop takeover safety policy", fg="cyan", bold=True))
+    click.echo("Defines exactly what the desktop agent is allowed to do.")
+    pol = DesktopPolicy.from_dict(cfg.desktop_policy)
+    pol.allow_mouse = click.confirm("  Allow mouse control (click)?", default=pol.allow_mouse)
+    pol.allow_keyboard = click.confirm("  Allow keyboard control (key)?", default=pol.allow_keyboard)
+    pol.allow_type = click.confirm("  Allow typing text?", default=pol.allow_type)
+    pol.require_confirm = click.confirm(
+        "  Require confirmation for risky-but-permitted actions?", default=pol.require_confirm)
+    pol.max_steps = click.prompt(
+        "  Max desktop interaction steps per run", type=int, default=pol.max_steps)
+    pol.pause_seconds = click.prompt(
+        "  Pause (seconds) between actions", type=float, default=pol.pause_seconds)
+    cfg.desktop_policy = pol.to_dict()
+
     cfg.save()
     click.echo(click.style(f"\nSaved config -> {cfg._path()}", fg="green"))
 
@@ -267,6 +287,33 @@ def cron_remove(name: str, path: str | None) -> None:
     click.echo(f"Removed cron job '{name}'.")
 
 
+@cron.command("edit")
+@click.argument("name")
+@click.option("--schedule", default=None, help="New schedule expression.")
+@click.option("--command", default=None, help="New shell command.")
+@click.option("--goal", default=None, help="New swarm goal (replaces command).")
+@click.option("--path", default=None, help="Workspace directory.")
+def cron_edit(name: str, schedule: str | None, command: str | None,
+              goal: str | None, path: str | None) -> None:
+    """Edit an existing cron job NAME (change schedule/command/goal)."""
+    from .modules.system.cron import CronScheduler
+
+    if schedule is None and command is None and goal is None:
+        click.echo("Nothing to change: pass --schedule, --command, or --goal.")
+        return
+    cfg = _load_cfg(path)
+    cron_file = cfg.workspace / ".opencommand" / "cron.json"
+    sched = CronScheduler.load(cron_file)
+    try:
+        sched.edit(name, schedule=schedule, command=command, goal=goal)
+    except KeyError:
+        click.echo(f"No cron job named '{name}'.")
+        return
+    sched.save(cron_file)
+    click.echo(f"Updated cron job '{name}'.")
+    click.echo(f"Persisted to {cron_file}")
+
+
 @cron.command("status")
 @click.option("--path", default=None, help="Workspace directory.")
 def cron_status(path: str | None) -> None:

{opencommand-0.1.2 → opencommand-0.1.3}/src/opencommand/core/config.py

@@ -24,6 +24,8 @@ class OpenCommandConfig:
     batch_size: int = 4  # workers spawned per swarm batch
     n_gpu_layers: int = 0  # 0 = CPU; -1 = all GPU layers
     goal_file: str = "Goal.md"  # session goal spec file name
+    # --- Desktop takeover safety policy (see modules/tools/desktop_safety.py) -
+    desktop_policy: dict = field(default_factory=dict)  # empty -> safe defaults
 
     def save(self) -> None:
         self._path().parent.mkdir(parents=True, exist_ok=True)
@@ -45,6 +47,7 @@ class OpenCommandConfig:
             "batch_size": self.batch_size,
             "n_gpu_layers": self.n_gpu_layers,
             "goal_file": self.goal_file,
+            "desktop_policy": self.desktop_policy,
         }, indent=2)
 
     @classmethod
@@ -68,6 +71,7 @@ class OpenCommandConfig:
             batch_size=d.get("batch_size", 4),
             n_gpu_layers=d.get("n_gpu_layers", 0),
             goal_file=d.get("goal_file", "Goal.md"),
+            desktop_policy=d.get("desktop_policy", {}),
         )
 
     def _path(self) -> Path:

opencommand-0.1.3/src/opencommand/modules/skills/desktop_linux.md

@@ -0,0 +1,41 @@
+---
+name: desktop-linux
+category: desktop-safety
+updated: 2026-07-12
+tags: [desktop, linux, safety, pyautogui]
+---
+
+# Desktop Agent — Safe Operation on Linux
+
+Guidance for the OpenCommand desktop takeover agent when driving a **Linux**
+host (X11/Wayland). The goal is to accomplish UI goals without destabilizing
+the session.
+
+## Hard rules (enforced by policy, do not bypass)
+- Never trigger `Ctrl+Alt+Del`/`Ctrl+Alt+Backspace` (session kill),
+  `Ctrl+Alt+F1..F12` (VT switch), or `Super+L` (lock) unless the goal requires it.
+- Never type destructive shell commands: `rm -rf`, `dd if=`, `mkfs`, `shutdown`,
+  `reboot`, `:(){:|:&};:` (fork bomb), or anything piped to `| sh` / `| bash`.
+- Do not escalate to root (no `sudo`, no `pkexec`). If a polkit prompt appears,
+  STOP and report.
+
+## pyautogui on Linux
+- `pyautogui.FAILSAFE = True` is always on: move the mouse to the top-left
+  corner to abort. Respect that escape hatch.
+- Screenshot support needs `scrot` (or `gnome-screenshot`); install it if
+  `locateOnScreen` is needed. Wayland may require `gnome-screenshot`/`grim`
+  instead of `scrot`.
+- `type()` targets the focused window. Click into the field first and confirm
+  focus before typing.
+- Prefer `click(x, y)` via image matching over blind key combos.
+
+## Safe interaction patterns
+1. Capture screen → locate the target control (image match or window title).
+2. Click the control; `wait(1)` for the UI to settle.
+3. For text entry, click the field, then `type()` a small specific string.
+4. Verify with another capture before `done`.
+
+## Verification before `done`
+- Confirm the intended window/state is visible and no error dialog is open.
+- If an unexpected confirmation/save dialog appeared, report it rather than
+  dismissing system dialogs blindly.

opencommand-0.1.3/src/opencommand/modules/skills/desktop_macos.md

@@ -0,0 +1,42 @@
+---
+name: desktop-macos
+category: desktop-safety
+updated: 2026-07-12
+tags: [desktop, macos, safety, pyautogui]
+---
+
+# Desktop Agent — Safe Operation on macOS
+
+Guidance for the OpenCommand desktop takeover agent when driving a **macOS**
+host. The goal is to accomplish UI goals without destabilizing the session.
+
+## Hard rules (enforced by policy, do not bypass)
+- Never trigger `Cmd+Q` (quit all / app), `Cmd+Shift+Q` (log out),
+  `Cmd+Ctrl+Power` (force restart), `Ctrl+Power` (dialog), or `Cmd+Option+Esc`
+  (force quit) unless the goal explicitly requires it.
+- Never type destructive shell commands: `rm -rf`, `sudo`, `diskutil erase`,
+  `shutdown`, `reboot`, or anything piped to `| sh` / `| bash`.
+- Do not approve a Touch ID / admin password prompt on the agent's behalf. If
+  one appears, STOP and report.
+
+## pyautogui on macOS
+- `pyautogui.FAILSAFE = True` is always on: move the mouse to the top-left
+  corner to abort. Respect that escape hatch.
+- macOS key names differ: use `command` (not `cmd`), `option` (not `alt`),
+  `control`, `shift`, `return`, `escape`, `space`, `delete` (backspace),
+  `backspace` (forward delete). The policy normalizes these.
+- `type()` targets the focused window. Click into the field first and confirm
+  focus before typing. Note `typewrite` is the underlying call; accented
+  characters may need explicit key names.
+- Prefer `click(x, y)` via image matching over blind key combos.
+
+## Safe interaction patterns
+1. Capture screen → locate the target control (image match or window title).
+2. Click the control; `wait(1)` for the UI to settle.
+3. For text entry, click the field, then `type()` a small specific string.
+4. Verify with another capture before `done`.
+
+## Verification before `done`
+- Confirm the intended window/state is visible and no error dialog is open.
+- If an unexpected confirmation/save dialog appeared, report it rather than
+  dismissing system dialogs blindly.

opencommand-0.1.3/src/opencommand/modules/skills/desktop_windows.md

@@ -0,0 +1,44 @@
+---
+name: desktop-windows
+category: desktop-safety
+updated: 2026-07-12
+tags: [desktop, windows, safety, pyautogui]
+---
+
+# Desktop Agent — Safe Operation on Windows
+
+Guidance for the OpenCommand desktop takeover agent when driving a **Windows**
+host. The goal is to accomplish UI goals without ever destabilizing the system.
+
+## Hard rules (enforced by policy, do not bypass)
+- Never trigger `Win+L` (lock), `Win+R` (Run), `Win+X` (admin menu), `Win+I`
+  (Settings), `Alt+F4` on the desktop/shell, or `Ctrl+Alt+Del`.
+- Never type destructive shell commands: `rmdir /s`, `del /q`, `format`,
+  `shutdown`, `deltree`, or anything piped to `iex`/`powershell -enc`.
+- Never open an admin/UAC prompt on the agent's own behalf. If a UAC dialog
+  appears, STOP and report — do not click "Yes".
+
+## pyautogui on Windows
+- `pyautogui.FAILSAFE = True` is always on: a human can slam the mouse into the
+  top-left corner to abort the agent instantly. Respect that escape hatch.
+- `pyautogui.PAUSE` is set (default 0.5s) so actions are paced and interruptible.
+- Use `click(x, y)` with coordinates from `locateOnScreen`/`locateCenterOnScreen`
+  rather than blind `key` combos wherever possible.
+- Prefer `pyautogui.hotkey('ctrl', 'c')` over `key('ctrl+c')` for combos; the
+  policy only permits safe combos.
+- `type()` writes to whatever has focus — only type after you have clicked into
+  the correct field and confirmed focus.
+
+## Safe interaction patterns
+1. Capture screen → identify the target control by image match or by reading
+   the window.
+2. Click the control (single left click). Wait for the UI to settle (use
+   `wait(1)`).
+3. If text entry is needed, click the field first, then `type()` a small,
+   specific string. Avoid pasting long shell one-liners.
+4. Verify the result with another screen capture before declaring done.
+
+## Verification before `done`
+- Confirm the intended window/state is visible and no error dialog is open.
+- If a confirmation or save dialog appeared unexpectedly, report it; do not
+  dismiss system dialogs blindly.

{opencommand-0.1.2 → opencommand-0.1.3}/src/opencommand/modules/system/cron.py

@@ -131,6 +131,25 @@ class CronScheduler:
         job.goal = goal
         return job
 
+    def edit(self, name: str, schedule: str | None = None,
+             command: str | None = None, goal: str | None = None) -> CronJob:
+        """Edit an existing job's schedule/command/goal in place.
+
+        Returns the updated job, or raises KeyError if no such job exists.
+        At least one of schedule/command/goal must be provided.
+        """
+        for job in self._jobs:
+            if job.name == name:
+                if schedule is not None:
+                    job.schedule = schedule
+                    job._parse()
+                if command is not None:
+                    job.command = command
+                if goal is not None:
+                    job.goal = goal
+                return job
+        raise KeyError(f"No cron job named {name!r}")
+
     def save(self, path: Path) -> None:
         """Persist serializable jobs to <workspace>/.opencommand/cron.json."""
         path.parent.mkdir(parents=True, exist_ok=True)

opencommand-0.1.3/src/opencommand/modules/tools/desktop.py

@@ -0,0 +1,202 @@
+"""Desktop control tool: realtime vision + mouse/keyboard action loop.
+
+Captures the screen, asks a small embedded vision-language model what is
+happening and what to do next, then executes the chosen action via
+pyautogui/pynput. Used for fully interactive testing (e.g. clicking UI,
+verifying behavior). The vision model is the built-in Qwen3-VL (or MiniCPM-V)
+the Engine (no external server).
+
+Safety: every action is vetted by a `DesktopPolicy` (configured via
+`opencommand config`) BEFORE it is executed. Destructive actions (restart,
+shutdown, deleting unspecified files, dangerous key combos) are refused. The
+native action execution runs inside a subinterpreter pool (Python 3.14) so a
+segfault in pyautogui/pynput cannot take down the supervisor; on older Python
+it falls back to a thread pool. pyautogui FAILSAFE + PAUSE are always enabled
+so a human can abort by slamming the mouse to the top-left corner.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+from dataclasses import dataclass
+
+from ...core.tools import BaseTool
+from ...engine.runner import LocalRunner
+from .desktop_safety import DesktopPolicy
+
+try:
+    import pyautogui
+    import mss
+    _HAVE_DESKTOP = True
+except Exception:  # pragma: no cover
+    _HAVE_DESKTOP = False
+
+
+@dataclass
+class DesktopStep:
+    observation: str
+    action: str
+    ok: bool
+    reason: str = ""
+
+
+def capture_screen() -> bytes:
+    """Return a PNG screenshot of the primary monitor as bytes."""
+    if not _HAVE_DESKTOP:
+        raise RuntimeError("pyautogui/mss not available")
+    with mss.mss() as sct:
+        img = sct.grab(sct.monitors[1])
+        import PIL.Image
+        buf = io.BytesIO()
+        PIL.Image.frombytes("RGB", img.size, img.rgb).save(buf, format="PNG")
+        return buf.getvalue()
+
+
+def _raw_act(action: str) -> None:
+    """Execute a high-level action string with NO policy checks.
+
+    This is the only function that touches pyautogui directly. It is run inside
+    an isolated subinterpreter so a native crash is contained. Callers must pass
+    already-vetted actions (see `act`).
+    """
+    if not _HAVE_DESKTOP:
+        raise RuntimeError("pyautogui not available")
+    action = action.strip()
+    if action.startswith("click("):
+        import re
+        m = re.match(r"click\((\d+),\s*(\d+)\)", action)
+        if m:
+            pyautogui.click(int(m.group(1)), int(m.group(2)))
+    elif action.startswith("type("):
+        pyautogui.write(action[len("type("):-1], interval=0.02)
+    elif action.startswith("key("):
+        pyautogui.press(action[len("key("):-1])
+    elif action.startswith("wait("):
+        import time
+        time.sleep(float(action[len("wait("):-1]))
+    else:
+        raise ValueError(f"unknown action: {action}")
+
+
+# --- Native action isolation ------------------------------------------------
+# The desktop tool drives real hardware through native extension modules
+# (pyautogui/pynput). A crash there must not kill the supervisor. On Python
+# 3.14 we use InterpreterPoolExecutor (each worker has its own interpreter +
+# GIL); otherwise we fall back to a plain thread pool. Model runners are NOT
+# isolated here (llama-cpp-python is not multi-interpreter safe) — only the
+# native desktop action execution is.
+def _make_executor(max_workers: int = 1):
+    if not _HAVE_DESKTOP:
+        return None
+    try:
+        from concurrent.futures import InterpreterPoolExecutor  # type: ignore
+        return InterpreterPoolExecutor(max_workers=max_workers)
+    except Exception:
+        from concurrent.futures import ThreadPoolExecutor
+        return ThreadPoolExecutor(max_workers=max_workers)
+
+
+_EXECUTOR = _make_executor()
+
+
+def act(action: str, policy: DesktopPolicy | None = None) -> tuple[bool, str]:
+    """Vet ``action`` against ``policy`` and execute it if allowed.
+
+    Returns ``(ok, reason)``. When ``policy`` is None a safe default policy is
+    used (everything except the built-in forbidden set). Execution happens in
+    the isolated executor so native crashes are contained.
+    """
+    policy = policy or DesktopPolicy()
+    allowed, reason = policy.check(action)
+    if not allowed:
+        return False, f"BLOCKED: {reason}"
+    if not _HAVE_DESKTOP:
+        return False, "desktop control libs (pyautogui/mss) not installed"
+    if _EXECUTOR is None:
+        try:
+            _raw_act(action)
+        except Exception as e:  # noqa: BLE001
+            return False, f"ERROR: {e}"
+        return True, "ok"
+    import concurrent.futures as cf
+    fut = _EXECUTOR.submit(_raw_act, action)
+    try:
+        fut.result()
+    except Exception as e:  # noqa: BLE001
+        return False, f"ERROR: {e}"
+    _ = cf  # keep import referenced when executor path is taken
+    return True, "ok"
+
+
+class DesktopTool(BaseTool):
+    name = "desktop"
+    description = (
+        "Realtime computer control: capture screen, ask a small vision model what "
+        "to do, and execute mouse/keyboard actions. Every action is vetted by a "
+        "safety policy before execution; destructive actions are refused."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "goal": {"type": "string", "description": "What to accomplish on screen."},
+            "steps": {"type": "integer", "description": "Max interaction steps (default 10)."},
+        },
+        "required": ["goal"],
+    }
+
+    def __init__(self, vision_runner: LocalRunner | None = None,
+                 policy: DesktopPolicy | None = None) -> None:
+        self.vision = vision_runner
+        self.policy = policy or DesktopPolicy()
+
+    def run(self, goal: str, steps: int = 10) -> str:
+        if not _HAVE_DESKTOP:
+            return "ERROR: desktop control libs (pyautogui/mss) not installed"
+        if self.vision is None:
+            return "ERROR: no vision model configured for desktop tool"
+        # Pace actions and keep the human abort escape hatch enabled.
+        import pyautogui as _pg
+        _pg.FAILSAFE = True
+        _pg.PAUSE = self.policy.pause_seconds
+        max_steps = min(steps, self.policy.max_steps)
+        history: list[DesktopStep] = []
+        for i in range(max_steps):
+            b64 = base64.b64encode(capture_screen()).decode()
+            content = [
+                {"type": "text", "text": (
+                    f"Goal: {goal}\nStep {i+1}. Describe the screen and decide the "
+                    "next single action as: click(x,y) | type(text) | key(name) | "
+                    "wait(secs) | done. Reply with ACTION: <action> and a short WHY.")},
+                {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{b64}"}},
+            ]
+            resp = self.vision.chat([{"role": "user", "content": content}],
+                                    temperature=0.1, max_tokens=256)
+            text = resp["choices"][0]["message"].get("content") or ""
+            action = self._extract_action(text)
+            if action == "done" or action == "":
+                history.append(DesktopStep(text, "done", True, "completion"))
+                break
+            # Commander-style watch: record intent + enforce policy.
+            ok, reason = act(action, self.policy)
+            history.append(DesktopStep(text, action, ok, reason))
+            if not ok:
+                # Surface the block/error and stop rather than retry blindly.
+                return (f"STOPPED at step {i+1}: {reason}\n"
+                        f"{self._summarize(history)}")
+        return self._summarize(history)
+
+    @staticmethod
+    def _extract_action(text: str) -> str:
+        for line in text.splitlines():
+            if line.strip().upper().startswith("ACTION:"):
+                return line.split(":", 1)[1].strip()
+        return ""
+
+    @staticmethod
+    def _summarize(history: list[DesktopStep]) -> str:
+        lines = [f"desktop loop: {len(history)} steps"]
+        for i, s in enumerate(history, 1):
+            status = "ok" if s.ok else "BLOCKED"
+            lines.append(f"  {i}. {s.action} -> {status} ({s.reason})")
+        return "\n".join(lines)

opencommand-0.1.3/src/opencommand/modules/tools/desktop_safety.py

@@ -0,0 +1,162 @@
+"""Desktop takeover safety policy for OpenCommand.
+
+The desktop agent drives the real mouse/keyboard, so it is the single most
+dangerous capability in the swarm. This module defines a declarative policy
+that the Commander configures (via `opencommand config`) and that the
+`DesktopTool` enforces *before* any action is executed. The policy is a
+deny-list + allow-list hybrid:
+
+  * ``forbidden_actions``  — action types that must NEVER run (e.g. restart,
+    shutdown, sleep, logoff).
+  * ``forbidden_keys``     — key names / combos that are destructive or
+    system-level (e.g. ``win+r`` to open Run, ``ctrl+alt+del``, ``alt+f4``
+    on the desktop, ``cmd``-entering-admin prompts).
+  * ``forbidden_paths``    — files/dirs the agent may never delete or move
+    unless the goal explicitly names them (handled by the files tool; here we
+    just refuse ``key``/``type`` sequences that would trigger a destructive
+    shell command).
+  * ``allow_mouse`` / ``allow_keyboard`` / ``allow_type`` — coarse capability
+    switches so the user can lock the agent to observe-only or click-only.
+  * ``require_confirm``    — when True, destructive-but-permitted actions are
+    surfaced to the Commander for a confirmation step instead of auto-running.
+  * ``max_steps`` / ``pause_seconds`` — pacing so a runaway loop can be
+    interrupted (pyautogui FAILSAFE still lets a human yank the mouse to the
+    top-left corner to abort).
+
+The policy is serializable to/from the workspace config so it persists and is
+auditable. ``DesktopPolicy.check(action)`` returns ``(allowed, reason)`` and is
+the single choke point the tool calls for every parsed action.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+# Action verbs the parser understands. Anything else is rejected by default.
+KNOWN_ACTIONS = ("click", "type", "key", "wait", "done")
+
+# System-level actions that are never safe for an autonomous agent to trigger.
+DEFAULT_FORBIDDEN_ACTIONS = (
+    "restart", "shutdown", "sleep", "hibernate", "logoff", "lock",
+    "signout", "forcequit", "kill", "terminate",
+)
+
+# Key names / combos that are destructive or escape the agent's sandbox.
+# Matched case-insensitively against the full key string the parser produces.
+DEFAULT_FORBIDDEN_KEYS = (
+    "ctrl+alt+del", "ctrl+alt+delete", "alt+f4", "alt+shift+f4",
+    "win+l", "win+r", "win+x", "win+i", "cmd+shift+q", "cmd+q",
+    "cmd+ctrl+power", "power", "eject", "volume_mute",
+)
+
+# Key names that are individually forbidden (no combo needed).
+DEFAULT_FORBIDDEN_KEY_NAMES = (
+    "win", "cmd", "super", "meta", "f4", "f13", "f14", "f15",
+)
+
+# Shell-ish tokens that, if typed, would escalate to a destructive command.
+# The agent must not be allowed to type these into a terminal it controls.
+DANGEROUS_TYPE_TOKENS = (
+    "rm -rf", "rm -r", "del /q", "deltree", "format ", "mkfs",
+    "shutdown", "restart", "poweroff", "halt", ":(){", "dd if=",
+    "sudo ", "runas ", "curl | sh", "wget | sh", "iwr | iex",
+)
+
+
+@dataclass
+class DesktopPolicy:
+    """Declarative safety policy for the desktop takeover agent."""
+
+    allow_mouse: bool = True
+    allow_keyboard: bool = True
+    allow_type: bool = True
+    require_confirm: bool = False
+    max_steps: int = 10
+    pause_seconds: float = 0.5
+    forbidden_actions: tuple[str, ...] = DEFAULT_FORBIDDEN_ACTIONS
+    forbidden_keys: tuple[str, ...] = DEFAULT_FORBIDDEN_KEYS
+    forbidden_key_names: tuple[str, ...] = DEFAULT_FORBIDDEN_KEY_NAMES
+
+    # --- Serialization ----------------------------------------------------
+
+    def to_dict(self) -> dict:
+        return {
+            "allow_mouse": self.allow_mouse,
+            "allow_keyboard": self.allow_keyboard,
+            "allow_type": self.allow_type,
+            "require_confirm": self.require_confirm,
+            "max_steps": self.max_steps,
+            "pause_seconds": self.pause_seconds,
+            "forbidden_actions": list(self.forbidden_actions),
+            "forbidden_keys": list(self.forbidden_keys),
+            "forbidden_key_names": list(self.forbidden_key_names),
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "DesktopPolicy":
+        if not d:
+            return cls()
+        return cls(
+            allow_mouse=d.get("allow_mouse", True),
+            allow_keyboard=d.get("allow_keyboard", True),
+            allow_type=d.get("allow_type", True),
+            require_confirm=d.get("require_confirm", False),
+            max_steps=d.get("max_steps", 10),
+            pause_seconds=d.get("pause_seconds", 0.5),
+            forbidden_actions=tuple(d.get("forbidden_actions", DEFAULT_FORBIDDEN_ACTIONS)),
+            forbidden_keys=tuple(d.get("forbidden_keys", DEFAULT_FORBIDDEN_KEYS)),
+            forbidden_key_names=tuple(d.get("forbidden_key_names", DEFAULT_FORBIDDEN_KEY_NAMES)),
+        )
+
+    # --- Enforcement ------------------------------------------------------
+
+    def check(self, action: str) -> tuple[bool, str]:
+        """Return (allowed, reason). ``action`` is the raw parsed verb+args.
+
+        The Commander is expected to call this for every action the vision
+        model proposes and to refuse anything not explicitly allowed. This is
+        the single choke point that keeps the takeover agent inside its lane.
+        """
+        action = action.strip()
+        if not action or action == "done":
+            return True, "no-op / completion"
+        verb = action.split("(", 1)[0].strip().lower()
+        if verb not in KNOWN_ACTIONS:
+            return False, f"unknown action verb '{verb}' (not in allow-list)"
+
+        if verb == "click":
+            if not self.allow_mouse:
+                return False, "mouse control disabled by policy"
+            return True, "click permitted"
+        if verb == "wait":
+            return True, "wait permitted"
+        if verb == "type":
+            if not self.allow_type:
+                return False, "typing disabled by policy"
+            text = action[action.find("(") + 1:action.rfind(")")].lower()
+            for tok in DANGEROUS_TYPE_TOKENS:
+                if tok in text:
+                    return False, f"typed text contains destructive token '{tok.strip()}'"
+            return True, "type permitted"
+        if verb == "key":
+            if not self.allow_keyboard:
+                return False, "keyboard control disabled by policy"
+            keys = self._normalize_keys(action)
+            for name in keys:
+                if name in self.forbidden_key_names:
+                    return False, f"forbidden key '{name}'"
+            combo = "+".join(keys)
+            for fk in self.forbidden_keys:
+                if fk in combo:
+                    return False, f"forbidden key combo '{fk}'"
+            return True, "key permitted"
+        return False, f"action '{verb}' not permitted"
+
+    @staticmethod
+    def _normalize_keys(action: str) -> list[str]:
+        """Extract individual key tokens from a ``key(a+b+c)`` action."""
+        inner = action[action.find("(") + 1:action.rfind(")")]
+        # pyautogui hotkey uses '+' or ','; normalize both.
+        parts = re.split(r"[+,]", inner)
+        return [p.strip().lower() for p in parts if p.strip()]