opencommand 0.1.0__py3-none-any.whl

opencommand/modules/tools/instructions.py

@@ -0,0 +1,163 @@
+"""Instructions tool: the swarm's self-improvement surface.
+
+Lets the Commander (and workers) create, update, and list the project's
+*instruction* artifacts that shape future runs:
+
+  - skills   -> ``modules/skills/*.md``   (how to do a kind of task)
+  - tasks    -> ``modules/tasks/*.md``    (reusable task/playbook templates)
+  - memory   -> ``<workspace>/.opencommand/memory/*.md`` (shared long-term notes)
+  - docs     -> ``<workspace>/.opencommand/docs/*.md``    (learned reference docs)
+
+The Commander calls this at the end of a run to distill what worked (new skills,
+corrected instructions, gotchas) so the next run starts smarter. Workers read
+these via the knowledge base that is injected into their system prompt.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+from ...core.tools import BaseTool
+from ..templates import validate_markdown
+
+# Built-in skills ship with the package (read-only defaults). The swarm writes
+# NEW/updated skills under the workspace so an installed (read-only) package is
+# never mutated; tasks/docs/memory already live under the workspace.
+_PKG_ROOT = Path(__file__).resolve().parents[2]
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def builtin_skills_dir() -> Path:
+    return _PKG_ROOT / "modules" / "skills"
+
+
+def skills_dir(workspace: Path) -> Path:
+    d = workspace / ".opencommand" / "skills"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def tasks_dir(workspace: Path) -> Path:
+    d = workspace / ".opencommand" / "tasks"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def docs_dir(workspace: Path) -> Path:
+    d = workspace / ".opencommand" / "docs"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _memory_dir(workspace: Path) -> Path:
+    from .memory import memory_dir
+
+    return memory_dir(workspace)
+
+
+class InstructionsTool(BaseTool):
+    name = "instructions"
+    description = (
+        "Self-improvement surface: create/update/list the swarm's instruction "
+        "artifacts (skills, tasks, docs, memory) so future runs start smarter. "
+        "Use after a goal to distill what worked."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "action": {"type": "string",
+                       "enum": ["save", "update", "list", "read"]},
+            "kind": {"type": "string",
+                     "enum": ["skill", "task", "doc", "memory"],
+                     "description": "Which instruction store to target."},
+            "name": {"type": "string",
+                     "description": "File name without extension (for save/update/read)."},
+            "body": {"type": "string",
+                     "description": "Markdown content (for save/update)."},
+            "tags": {"type": "array", "items": {"type": "string"},
+                     "description": "Tags for memory/docs (optional)."},
+            "query": {"type": "string",
+                      "description": "Name or topic to read/list (optional)."},
+        },
+        "required": ["action", "kind"],
+    }
+
+    def __init__(self, workspace: Path) -> None:
+        self.workspace = workspace
+
+    def _root(self, kind: str) -> Path:
+        if kind == "skill":
+            return skills_dir(self.workspace)
+        if kind == "task":
+            return tasks_dir(self.workspace)
+        if kind == "doc":
+            return docs_dir(self.workspace)
+        if kind == "memory":
+            return _memory_dir(self.workspace)
+        raise ValueError(f"unknown kind: {kind}")
+
+    def run(self, action: str, kind: str, name: str | None = None,
+            body: str | None = None, tags: list[str] | None = None,
+            query: str | None = None) -> str:
+        root = self._root(kind)
+        if action == "list":
+            items = sorted(p.name for p in root.glob("*.md"))
+            return "\n".join(items) if items else f"(no {kind} files)"
+        if action == "read":
+            if not name and not query:
+                return "ERROR: read requires name or query"
+            target = root / f"{(name or query)}.md"
+            if not target.exists():
+                # fuzzy match by substring
+                matches = [p for p in root.glob("*.md")
+                           if (name or query or "") in p.stem]
+                if not matches:
+                    return f"ERROR: no {kind} file named {name or query}"
+                target = matches[0]
+            return target.read_text(encoding="utf-8")
+        if action in ("save", "update"):
+            if not name:
+                return "ERROR: save/update requires name"
+            if body is None:
+                return "ERROR: save/update requires body"
+            path = root / f"{name}.md"
+            existed = path.exists()
+            content = self._render(kind, name, body, tags)
+            missing = validate_markdown(kind, content)
+            if missing:
+                return (f"ERROR: {kind} '{name}' is missing required elements: "
+                        f"{', '.join(missing)}. Use the template shape.")
+            path.write_text(content, encoding="utf-8")
+            verb = "Updated" if existed else "Created"
+            return f"{verb} {kind}: {path.name}"
+        return f"ERROR: unknown action {action}"
+
+    @staticmethod
+    def _render(kind: str, name: str, body: str,
+                tags: list[str] | None) -> str:
+        """Normalize body into the required template shape for ``kind``.
+
+        Emits the full YAML front-matter with every required field so the
+        artifact passes template validation and is machine-readable.
+        """
+        from ..templates import template_for
+
+        tpl = template_for(kind)
+        tag_csv = ",".join(tags or [])
+        now = _now()
+        # Map required front-matter fields to values we can derive.
+        fm_values = {"name": name, "topic": name, "category": name,
+                     "goal": name, "updated": now, "created": now,
+                     "tags": f"[{tag_csv}]", "phase": name, "index": "0",
+                     "iteration": "0", "status": "draft", "phases": "0"}
+        lines = ["---"]
+        for fld in tpl.required_fields:
+            lines.append(f"{fld}: {fm_values.get(fld, '')}")
+        front = "\n".join(lines) + "\n---\n\n"
+        if body.startswith("#"):
+            return front + body + "\n"
+        return f"{front}# {name}\n\n{body}\n"

opencommand/modules/tools/memory.py

@@ -0,0 +1,78 @@
+"""Memory tool: Obsidian-style tagged markdown memory stored under modules/memory.
+
+Supports saving notes (with #tags), listing, and searching across memory files.
+Workspace-specific memory lives in <workspace>/.opencommand/memory/.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ...core.tools import BaseTool
+
+
+def memory_dir(workspace: Path) -> Path:
+    d = workspace / ".opencommand" / "memory"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def save_note(workspace: Path, topic: str, body: str, tags: list[str] | None = None) -> str:
+    d = memory_dir(workspace)
+    tags = tags or []
+    tag_line = " " + " ".join(f"#{t}" for t in tags) if tags else ""
+    path = d / f"{topic.replace(' ', '_').lower()}.md"
+    path.write_text(f"# {topic}{tag_line}\n\n{body}\n", encoding="utf-8")
+    return f"Saved memory: {path.name}"
+
+
+def search_memory(workspace: Path, query: str) -> str:
+    d = memory_dir(workspace)
+    if not d.exists():
+        return "(no memory yet)"
+    q = query.lower()
+    hits: list[str] = []
+    for f in d.glob("*.md"):
+        text = f.read_text(encoding="utf-8")
+        if q in text.lower():
+            hits.append(f"- {f.name}: {text[:400].replace(chr(10), ' ')}")
+    return "\n".join(hits) if hits else "(no matches)"
+
+
+def list_memory(workspace: Path) -> str:
+    d = memory_dir(workspace)
+    if not d.exists():
+        return "(no memory yet)"
+    files = sorted(p.name for p in d.glob("*.md"))
+    return "\n".join(files) if files else "(empty)"
+
+
+class MemoryTool(BaseTool):
+    name = "memory"
+    description = "Manage OpenCommand memory: save a tagged note, list notes, or search notes."
+    parameters = {
+        "type": "object",
+        "properties": {
+            "action": {"type": "string", "enum": ["save", "list", "search"]},
+            "topic": {"type": "string", "description": "Note topic (for save)."},
+            "body": {"type": "string", "description": "Note body (for save)."},
+            "tags": {"type": "array", "items": {"type": "string"}, "description": "Tags (for save)."},
+            "query": {"type": "string", "description": "Search query (for search)."},
+        },
+        "required": ["action"],
+    }
+
+    def __init__(self, workspace: Path) -> None:
+        self.workspace = workspace
+
+    def run(self, action: str, topic: str | None = None, body: str | None = None,
+            tags: list[str] | None = None, query: str | None = None) -> str:
+        if action == "save":
+            if not topic or body is None:
+                return "ERROR: save requires topic and body"
+            return save_note(self.workspace, topic, body, tags)
+        if action == "list":
+            return list_memory(self.workspace)
+        if action == "search":
+            return search_memory(self.workspace, query or "")
+        return f"ERROR: unknown action {action}"

opencommand/modules/tools/playwright.py

@@ -0,0 +1,61 @@
+"""Playwright browser automation tool (web testing / interaction).
+
+Distinct from research: drives a real browser (click, type, navigate, extract
+DOM) for interactive web testing. Requires playwright + browsers installed.
+"""
+
+from __future__ import annotations
+
+from ...core.tools import BaseTool
+
+
+class PlaywrightTool(BaseTool):
+    name = "playwright"
+    description = "Automate a browser: navigate, click, type, read page text/DOM."
+    parameters = {
+        "type": "object",
+        "properties": {
+            "action": {"type": "string", "enum": ["goto", "click", "type", "text", "screenshot"]},
+            "url": {"type": "string", "description": "URL for goto."},
+            "selector": {"type": "string", "description": "CSS selector for click/type."},
+            "value": {"type": "string", "description": "Text to type."},
+        },
+        "required": ["action"],
+    }
+
+    def __init__(self, headless: bool = True) -> None:
+        self.headless = headless
+        self._page = None
+
+    def _ensure(self):
+        if self._page is None:
+            from playwright.sync_api import sync_playwright
+            self._pw = sync_playwright().start()
+            self._browser = self._pw.chromium.launch(headless=self.headless)
+            self._page = self._browser.new_page()
+        return self._page
+
+    def run(self, action: str, url: str | None = None,
+            selector: str | None = None, value: str | None = None) -> str:
+        page = self._ensure()
+        if action == "goto" and url:
+            page.goto(url)
+            return f"Navigated to {url}; title={page.title()}"
+        if action == "click" and selector:
+            page.click(selector)
+            return f"Clicked {selector}"
+        if action == "type" and selector and value is not None:
+            page.fill(selector, value)
+            return f"Typed into {selector}"
+        if action == "text":
+            return page.inner_text("body")[:4000]
+        if action == "screenshot":
+            path = "/tmp/opencommand_shot.png"
+            page.screenshot(path=path)
+            return f"Screenshot saved: {path}"
+        return "ERROR: invalid action/args"
+
+    def close(self) -> None:
+        if getattr(self, "_browser", None):
+            self._browser.close()
+            self._pw.stop()

opencommand/modules/tools/research.py

@@ -0,0 +1,46 @@
+"""Research tool: multi-batch web research via HTTP + lightweight scraping.
+
+Not a browser-automation tool (see playwright.py). Fetches pages and pulls out
+readable text for research/planning agents.
+"""
+
+from __future__ import annotations
+
+import re
+
+import requests
+
+from ...core.tools import BaseTool
+
+_TAG_RE = re.compile(r"<[^>]+>")
+_WS_RE = re.compile(r"\s+")
+_HEAD_RE = re.compile(r"<(script|style|head)[^>]*>.*?</\1>", re.IGNORECASE | re.DOTALL)
+
+
+def fetch_text(url: str, timeout: int = 30) -> str:
+    resp = requests.get(url, timeout=timeout, headers={"User-Agent": "OpenCommand/0.1"})
+    resp.raise_for_status()
+    text = _WS_RE.sub(" ", _TAG_RE.sub(" ", _HEAD_RE.sub("", resp.text))).strip()
+    return text[:8000]
+
+
+class ResearchTool(BaseTool):
+    name = "research"
+    description = "Fetch one or more URLs and return cleaned readable text for research."
+    parameters = {
+        "type": "object",
+        "properties": {
+            "urls": {"type": "array", "items": {"type": "string"}, "description": "URLs to fetch."},
+            "query": {"type": "string", "description": "Optional note describing the research goal."},
+        },
+        "required": ["urls"],
+    }
+
+    def run(self, urls: list[str], query: str | None = None) -> str:
+        out: list[str] = []
+        for u in urls:
+            try:
+                out.append(f"## {u}\n{fetch_text(u)}")
+            except Exception as e:  # noqa: BLE001
+                out.append(f"## {u}\nERROR: {e}")
+        return "\n\n".join(out)

opencommand/modules/tools/system.py

@@ -0,0 +1,163 @@
+"""System introspection & security tool: processes, file watching, YARA scans.
+
+Situational-awareness tool for the swarm: list running processes, scan files or
+directories with YARA rules, and watch a path for changes via watchdog. YARA is
+used through the yara CLI when present on PATH (the Python binding needs a C
+toolchain to build on Windows, so we shell out instead). If yara is unavailable
+the tool reports it clearly rather than crashing.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+from ...core.tools import BaseTool
+
+
+def _yara_available() -> bool:
+    return shutil.which("yara") is not None
+
+
+def list_processes() -> list[dict[str, str]]:
+    """Return a snapshot of running processes (name, pid, maybe cmdline)."""
+    out: list[dict[str, str]] = []
+    try:
+        proc = subprocess.run(["ps", "-eo", "pid,comm,pcpu,pmem"],
+                               capture_output=True, text=True, timeout=20)
+        for line in proc.stdout.strip().splitlines()[1:]:
+            parts = line.split(None, 3)
+            if len(parts) >= 2:
+                out.append({
+                    "pid": parts[0], "name": parts[1],
+                    "cpu": parts[2] if len(parts) > 2 else "",
+                    "mem": parts[3] if len(parts) > 3 else "",
+                })
+    except (FileNotFoundError, subprocess.SubprocessError):
+        # Windows fallback (wmic is deprecated; use tasklist).
+        proc = subprocess.run(["tasklist", "/fo", "csv", "/nh"],
+                               capture_output=True, text=True, timeout=30)
+        for line in proc.stdout.strip().splitlines():
+            parts = [p.strip('"') for p in line.split('","')]
+            if len(parts) >= 2:
+                out.append({"pid": parts[1], "name": parts[0]})
+    return out
+
+
+def scan_file(path: str, rules: str) -> str:
+    """Scan a single file with YARA rules (rules = path to .yar or rule text)."""
+    if not _yara_available():
+        return "ERROR: yara CLI not found on PATH (install YARA to enable scanning)"
+    target = Path(path)
+    if not target.exists():
+        return f"ERROR: path does not exist: {path}"
+    # If rules looks like a file, pass it; otherwise write a temp rule file.
+    rule_arg = rules
+    tmp = None
+    if not Path(rules).exists():
+        tmp = Path(target.parent) / ".opencommand_yara_tmp.yar"
+        tmp.write_text(rules, encoding="utf-8")
+        rule_arg = str(tmp)
+    try:
+        proc = subprocess.run(["yara", rule_arg, str(target)],
+                              capture_output=True, text=True, timeout=60)
+        result = proc.stdout.strip() or "(no matches)"
+        if proc.stderr.strip():
+            result += f"\n[stderr] {proc.stderr.strip()}"
+        return result
+    finally:
+        if tmp and tmp.exists():
+            tmp.unlink(missing_ok=True)
+
+
+def scan_directory(path: str, rules: str, recursive: bool = True) -> str:
+    """Recursively scan a directory with YARA rules."""
+    if not _yara_available():
+        return "ERROR: yara CLI not found on PATH (install YARA to enable scanning)"
+    target = Path(path)
+    if not target.is_dir():
+        return f"ERROR: not a directory: {path}"
+    cmd = ["yara", "-r", rules, str(target)] if recursive else ["yara", rules, str(target)]
+    proc = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
+    return proc.stdout.strip() or "(no matches)"
+
+
+def watch_path(path: str, seconds: int = 10) -> str:
+    """Watch a directory for filesystem changes for ``seconds`` and report them."""
+    try:
+        from watchdog.events import FileSystemEventHandler
+        from watchdog.observers import Observer
+    except Exception as e:  # pragma: no cover
+        return f"ERROR: watchdog unavailable: {e}"
+    target = Path(path)
+    if not target.is_dir():
+        return f"ERROR: not a directory: {path}"
+    events: list[str] = []
+
+    class _Handler(FileSystemEventHandler):
+        def on_any_event(self, event):
+            events.append(f"{event.event_type}: {event.src_path}")
+
+    observer = Observer()
+    observer.schedule(_Handler(), str(target), recursive=True)
+    observer.start()
+    try:
+        import time
+        time.sleep(seconds)
+    finally:
+        observer.stop()
+        observer.join(timeout=5)
+    return "\n".join(events) if events else "(no changes observed)"
+
+
+class SystemTool(BaseTool):
+    name = "system"
+    description = (
+        "System introspection & security: list running processes, scan files or "
+        "directories with YARA rules, and watch a path for filesystem changes. "
+        "Use for situational awareness and safety checks."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "action": {
+                "type": "string",
+                "enum": ["list_processes", "scan_file", "scan_directory", "watch"],
+                "description": "Which system operation to perform.",
+            },
+            "path": {"type": "string", "description": "File or directory path (for scan/watch)."},
+            "rules": {
+                "type": "string",
+                "description": "Path to a .yar rule file, or inline YARA rule text (for scans).",
+            },
+            "recursive": {
+                "type": "boolean",
+                "description": "Recurse into subdirectories for scan_directory (default true).",
+            },
+            "seconds": {
+                "type": "integer",
+                "description": "How long to watch a path in seconds (default 10).",
+            },
+        },
+        "required": ["action"],
+    }
+
+    def run(self, action: str, path: str | None = None, rules: str | None = None,
+            recursive: bool = True, seconds: int = 10) -> str:
+        if action == "list_processes":
+            return json.dumps(list_processes(), indent=2)
+        if action == "scan_file":
+            if not path or not rules:
+                return "ERROR: scan_file requires 'path' and 'rules'"
+            return scan_file(path, rules)
+        if action == "scan_directory":
+            if not path or not rules:
+                return "ERROR: scan_directory requires 'path' and 'rules'"
+            return scan_directory(path, rules, recursive=recursive)
+        if action == "watch":
+            if not path:
+                return "ERROR: watch requires 'path'"
+            return watch_path(path, seconds=seconds)
+        return f"ERROR: unknown action '{action}'"

opencommand/modules/tools/terminal.py

@@ -0,0 +1,53 @@
+"""Cross-platform terminal command execution tool.
+
+Agents call Terminal.run to execute shell commands and get the output back.
+Uses subprocess (not os.popen, which is soft-deprecated in 3.14) and detects
+the platform shell automatically.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from dataclasses import dataclass
+
+from ...core.tools import BaseTool
+
+
+@dataclass
+class TerminalResult:
+    returncode: int
+    stdout: str
+    stderr: str
+
+
+def _shell() -> list[str]:
+    return ["cmd.exe", "/c"] if sys.platform.startswith("win") else ["/bin/sh", "-c"]
+
+
+def run_command(command: str, cwd: str | None = None, timeout: int = 120) -> TerminalResult:
+    """Run ``command`` in the platform shell; return stdout/stderr/rc."""
+    proc = subprocess.run(_shell() + [command], cwd=cwd, capture_output=True,
+                          text=True, timeout=timeout)
+    return TerminalResult(proc.returncode, proc.stdout, proc.stderr)
+
+
+class TerminalTool(BaseTool):
+    name = "terminal"
+    description = "Run a shell command on the host and return its stdout/stderr/exit code."
+    parameters = {
+        "type": "object",
+        "properties": {
+            "command": {"type": "string", "description": "The shell command to run."},
+            "cwd": {"type": "string", "description": "Working directory (optional)."},
+            "timeout": {"type": "integer", "description": "Timeout in seconds (default 120)."},
+        },
+        "required": ["command"],
+    }
+
+    def run(self, command: str, cwd: str | None = None, timeout: int = 600) -> str:
+        try:
+            r = run_command(command, cwd=cwd, timeout=timeout)
+        except subprocess.TimeoutExpired:
+            return "ERROR: command timed out"
+        return f"[exit={r.returncode}]\nSTDOUT:\n{r.stdout}\nSTDERR:\n{r.stderr}"