opencommand 0.1.0__py3-none-any.whl

opencommand/core/supervisor.py

@@ -0,0 +1,81 @@
+"""Supervisor: dispatches and monitors worker coroutines with crash containment.
+
+Uses asyncio.TaskGroup for structured concurrency. A failing worker is retried
+up to ``max_retries``; a worker crash never takes down the event loop.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Awaitable, Callable
+
+from .errors import RetryableError
+from .logging import get_logger
+
+log = get_logger("core.supervisor")
+
+
+@dataclass
+class WorkerHandle:
+    name: str
+    task: str
+    status: str = "pending"  # pending|running|done|failed|retrying
+    attempts: int = 0
+    result: str | None = None
+    error: str | None = None
+
+
+class Supervisor:
+    """Runs worker coroutines with supervision and restart policy."""
+
+    def __init__(self, max_retries: int = 3) -> None:
+        self.max_retries = max_retries
+        self.handles: dict[str, WorkerHandle] = {}
+
+    def register(self, name: str, task: str) -> WorkerHandle:
+        h = WorkerHandle(name=name, task=task)
+        self.handles[name] = h
+        return h
+
+    async def run_worker(self, name: str, coro_fn: Callable[[], Awaitable[str]]) -> str:
+        """Run ``coro_fn`` with retry/restart containment. Returns final result."""
+        handle = self.handles.get(name) or self.register(name, name)
+        last_err: Exception | None = None
+        while handle.attempts <= self.max_retries:
+            handle.attempts += 1
+            handle.status = "running" if handle.attempts == 1 else "retrying"
+            try:
+                result = await coro_fn()
+                handle.status = "done"
+                handle.result = result
+                return result
+            except RetryableError as e:
+                last_err = e
+                await asyncio.sleep(min(2**handle.attempts, 8))
+                log.warning("worker %s retryable error attempt=%d: %s",
+                            name, handle.attempts, e)
+                continue
+            except Exception as e:  # noqa: BLE001 - containment
+                handle.status = "failed"
+                handle.error = f"{type(e).__name__}: {e}"
+                last_err = e
+                log.error("worker %s failed: %s", name, handle.error)
+                break
+        handle.status = "failed"
+        handle.error = str(last_err)
+        return f"FAILED after {handle.attempts} attempt(s): {last_err}"
+
+    async def run_all(self, jobs: dict[str, Callable[[], Awaitable[str]]]) -> dict[str, str]:
+        """Run all jobs concurrently; each isolated by run_worker."""
+        for name in jobs:
+            self.register(name, name)
+        async with asyncio.TaskGroup() as tg:
+            tasks = {name: tg.create_task(self.run_worker(name, fn)) for name, fn in jobs.items()}
+        return {name: t.result() for name, t in tasks.items()}
+
+    def summary(self) -> str:
+        lines = ["Supervisor (in-process, crash-contained):"]
+        for h in self.handles.values():
+            lines.append(f"  - {h.name}: {h.status} (attempts={h.attempts})")
+        return "\n".join(lines)

opencommand/core/tools.py

@@ -0,0 +1,136 @@
+"""Tool registry and the BaseTool protocol used by agents."""
+
+from __future__ import annotations
+
+import inspect
+import json
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from .errors import ToolError
+
+
+@dataclass
+class ToolCall:
+    """A tool invocation requested by the model."""
+
+    id: str
+    name: str
+    arguments: dict[str, Any]
+
+
+@dataclass
+class ToolResult:
+    ok: bool
+    output: str
+    error: str | None = None
+
+
+class BaseTool:
+    """A tool an agent can call. Subclass and implement ``run``."""
+
+    name: str = "base"
+    description: str = ""
+    parameters: dict[str, Any] = field(default_factory=dict)
+
+    def schema(self) -> dict[str, Any]:
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters or {"type": "object", "properties": {}},
+            },
+        }
+
+    def run(self, **kwargs: Any) -> str:
+        raise NotImplementedError
+
+    async def arun(self, **kwargs: Any) -> str:
+        return self.run(**kwargs)
+
+
+class ToolRegistry:
+    """Holds the available tools and dispatches calls."""
+
+    def __init__(self) -> None:
+        self._tools: dict[str, BaseTool] = {}
+
+    def register(self, tool: BaseTool) -> None:
+        self._tools[tool.name] = tool
+
+    def get(self, name: str) -> BaseTool:
+        tool = self._tools.get(name)
+        if tool is None:
+            raise ToolError(f"Unknown tool: {name}")
+        return tool
+
+    def schemas(self) -> list[dict[str, Any]]:
+        return [t.schema() for t in self._tools.values()]
+
+    def dispatch(self, call: ToolCall) -> ToolResult:
+        try:
+            return ToolResult(ok=True, output=str(self.get(call.name).run(**call.arguments)))
+        except Exception as e:  # noqa: BLE001 - surface as tool error
+            return ToolResult(ok=False, output="", error=f"{type(e).__name__}: {e}")
+
+    async def adispatch(self, call: ToolCall) -> ToolResult:
+        try:
+            return ToolResult(ok=True, output=str(await self.get(call.name).arun(**call.arguments)))
+        except Exception as e:  # noqa: BLE001
+            return ToolResult(ok=False, output="", error=f"{type(e).__name__}: {e}")
+
+
+def parse_tool_calls(message: Any) -> list[ToolCall]:
+    """Extract tool calls from an OpenAI-compatible chat message object."""
+    calls: list[ToolCall] = []
+    raw = getattr(message, "tool_calls", None)
+    if not raw:
+        return calls
+    for tc in raw:
+        args = {}
+        if tc.function.arguments:
+            try:
+                args = json.loads(tc.function.arguments)
+            except json.JSONDecodeError:
+                args = {}
+        calls.append(ToolCall(id=tc.id, name=tc.function.name, arguments=args))
+    return calls
+
+
+def tool(
+    name: str, description: str, parameters: dict[str, Any] | None = None
+) -> Callable[[Callable[..., str]], BaseTool]:
+    """Decorator to turn a plain function into a registered BaseTool."""
+
+    def decorator(fn: Callable[..., str]) -> BaseTool:
+        sig = inspect.signature(fn)
+
+        class _FnTool(BaseTool):
+            @property
+            def name(self) -> str:  # type: ignore[override]
+                return name
+
+            @property
+            def description(self) -> str:  # type: ignore[override]
+                return description
+
+            @property
+            def parameters(self) -> dict[str, Any]:  # type: ignore[override]
+                return parameters or _default_params(sig)
+
+            def run(self, **kwargs: Any) -> str:
+                return fn(**kwargs)
+
+        return _FnTool()
+
+    return decorator
+
+
+def _default_params(sig: inspect.Signature) -> dict[str, Any]:
+    props: dict[str, Any] = {}
+    for pname, p in sig.parameters.items():
+        if pname in ("self", "cls"):
+            continue
+        props[pname] = {"type": "string", "description": pname}
+    return {"type": "object", "properties": props, "required": list(props)}

opencommand/engine/__init__.py

@@ -0,0 +1,66 @@
+"""Embedded model engine: load and manage built-in GGUF models."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .runner import CATALOG, LocalRunner
+
+DEFAULT_MODEL_DIR = Path(__file__).resolve().parent.parent.parent.parent / "models"
+
+
+class Engine:
+    """Owns the commander/worker/vision runners and lazy-loads them.
+
+    Each role has a small pool of runner instances so concurrent workers don't
+    serialize on a single model. `runner(role)` returns a shared instance for
+    sequential use (e.g. the Commander); `worker_runner(role, i)` returns a
+    dedicated instance per worker index for true parallelism.
+    """
+
+    def __init__(self, model_dir: Path | None = None, pool_size: int = 4) -> None:
+        self.model_dir = model_dir or DEFAULT_MODEL_DIR
+        self.pool_size = max(1, pool_size)
+        self._runners: dict[str, LocalRunner] = {}
+        self._pools: dict[str, list[LocalRunner]] = {}
+
+    def runner(self, role: str) -> LocalRunner:
+        if role not in self._runners:
+            spec = CATALOG.get(role)
+            if spec is None:
+                raise KeyError(f"No built-in model for role '{role}'")
+            self._runners[role] = LocalRunner(spec, self.model_dir / role)
+        return self._runners[role]
+
+    def worker_runner(self, role: str, index: int = 0) -> LocalRunner:
+        """Return a dedicated runner for worker `index` (round-robin pool)."""
+        spec = CATALOG.get(role)
+        if spec is None:
+            raise KeyError(f"No built-in model for role '{role}'")
+        pool = self._pools.setdefault(role, [])
+        i = index % self.pool_size
+        while len(pool) <= i:
+            pool.append(LocalRunner(spec, self.model_dir / role))
+        return pool[i]
+
+    def ensure_downloaded(self, role: str) -> Path:
+        """Download (if needed) and return the model path without loading weights."""
+        spec = CATALOG[role]
+        r = LocalRunner(spec, self.model_dir / role)
+        return r.download()
+
+    def download_all(self) -> dict[str, Path]:
+        return {role: self.ensure_downloaded(role) for role in CATALOG}
+
+    def status(self) -> str:
+        lines = [f"Engine model dir: {self.model_dir}"]
+        for role, spec in CATALOG.items():
+            runner = self._runners.get(role)
+            if runner is None:
+                state = "not loaded"
+            elif runner._llm is None:
+                state = "instantiated (lazy)"
+            else:
+                state = "loaded"
+            lines.append(f"  - {role}: {spec.repo_id} [{spec.kind}] {state}")
+        return "\n".join(lines)

opencommand/engine/runner.py

@@ -0,0 +1,275 @@
+"""OpenCommand embedded model runner.
+
+Loads GGUF models directly with llama-cpp-python (no server, no network at
+runtime). Supports text + native tool calling and vision (Qwen3-VL / MiniCPM-V
+via the MTMD handler). Models live under <workspace>/models and are
+downloaded on first use via Hugging Face Hub.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ..core.logging import get_logger
+from ..providers.provider import ChatMessage
+
+log = get_logger("engine.runner")
+
+
+@dataclass
+class ModelSpec:
+    """Declarative description of a built-in model."""
+
+    key: str
+    role: str  # commander | worker | vision
+    repo_id: str
+    filename: str  # glob matched against repo files
+    kind: str = "text"  # text | vision
+    chat_format: str | None = None  # None -> auto-detect from GGUF metadata
+    n_ctx: int = 8192
+    n_gpu_layers: int = 0  # 0 = CPU; -1 = all GPU layers
+    mmproj: str | None = None  # multimodal projector glob (vision)
+    description: str = ""
+
+
+# Catalog (verified July 2026). Commander = Ornith-1.0-9B (agentic coding, MIT).
+# Worker = Qwen3-4B-Instruct-2507 (text, native tool calling). Vision = Qwen3-VL-4B
+# (purpose-built GUI agent, MTMD + mmproj) as primary, with MiniCPM-V-4.6 (0.8B,
+# ~529MB) as a lightweight CPU fallback. chat_format is None for text roles so
+# llama.cpp auto-detects the native tool-calling template from GGUF metadata.
+CATALOG: dict[str, ModelSpec] = {
+    "commander": ModelSpec(
+        key="commander", role="commander",
+        repo_id="deepreinforce-ai/Ornith-1.0-9B-GGUF",
+        filename="ornith-1.0-9b-Q4_K_M.gguf",
+        kind="text", n_ctx=8192,
+        description="Commander/planner model (Ornith-1.0-9B, agentic coding).",
+    ),
+    "worker": ModelSpec(
+        key="worker", role="worker",
+        repo_id="unsloth/Qwen3-4B-Instruct-2507-GGUF",
+        filename="Qwen3-4B-Instruct-2507-Q4_K_M.gguf",
+        kind="text", n_ctx=8192,
+        description="Worker execution model (Qwen3-4B-Instruct, native tool calling).",
+    ),
+    "vision": ModelSpec(
+        key="vision", role="vision",
+        repo_id="unsloth/Qwen3-VL-4B-Instruct-GGUF",
+        filename="Qwen3-VL-4B-Instruct-Q4_K_M.gguf",
+        kind="vision", chat_format="mtmd", n_ctx=8192, mmproj="mmproj-F16.gguf",
+        description="Realtime vision model for screen understanding (Qwen3-VL-4B, GUI agent).",
+    ),
+    "vision_small": ModelSpec(
+        key="vision_small", role="vision_small",
+        repo_id="openbmb/MiniCPM-V-4.6-gguf",
+        filename="MiniCPM-V-4_6-Q4_K_M.gguf",
+        kind="vision", chat_format="mtmd", n_ctx=4096, mmproj="mmproj-model-f16.gguf",
+        description="Lightweight vision fallback (MiniCPM-V-4.6, 0.8B, ~529MB) for CPU/low-RAM.",
+    ),
+}
+
+
+class LocalRunner:
+    """Wraps a single llama_cpp.Llama instance; thread-safe for sync calls.
+
+    Loading is lazy: the model is only mapped into RAM on first inference, so
+    ensure_downloaded can fetch weights without requiring enough RAM (or a
+    compatible CPU) to actually run them.
+    """
+
+    def __init__(self, spec: ModelSpec, model_dir: Path) -> None:
+        self.spec = spec
+        self.model_dir = model_dir
+        self._llm = None
+        self._lock = threading.Lock()
+
+    def download(self) -> Path:
+        """Ensure weights exist locally; return the model path (no load)."""
+        return self._resolve_path()
+
+    def _resolve_path(self) -> Path:
+        import fnmatch
+        self.model_dir.mkdir(parents=True, exist_ok=True)
+        for f in self.model_dir.iterdir():
+            if fnmatch.fnmatch(f.name, self.spec.filename):
+                return f
+        return self._download()
+
+    def _download(self) -> Path:
+        import fnmatch
+        from huggingface_hub import hf_hub_download, list_repo_files
+        filename = self.spec.filename
+        # Resolve a glob to a concrete filename so HF can create a valid lock
+        # file (esp. on Windows).
+        if "*" in filename or "?" in filename:
+            repo_files = [f for f in list_repo_files(repo_id=self.spec.repo_id)
+                          if f.endswith(".gguf") and f != "README.md"]
+            hits = [f for f in repo_files if fnmatch.fnmatch(f, filename)]
+            if not hits:
+                raise FileNotFoundError(f"No file matching {filename!r} in {self.spec.repo_id}")
+            filename = sorted(hits, key=len)[0]
+        path = hf_hub_download(repo_id=self.spec.repo_id, filename=filename,
+                               local_dir=str(self.model_dir))
+        if self.spec.mmproj:
+            try:
+                hf_hub_download(repo_id=self.spec.repo_id, filename=self.spec.mmproj,
+                                local_dir=str(self.model_dir))
+            except Exception:  # noqa: BLE001 - mmproj optional
+                pass
+        return Path(path)
+
+    def _ensure_loaded(self) -> None:
+        # Guard construction with the lock so concurrent first-use from multiple
+        # worker threads can't build two Llama instances into the same slot.
+        with self._lock:
+            if self._llm is not None:
+                return
+            log.info("loading model role=%s path=%s", self.spec.role,
+                     self._resolve_path().name)
+            from llama_cpp import Llama
+            kwargs: dict[str, Any] = {
+                "model_path": str(self._resolve_path()),
+                "n_ctx": self.spec.n_ctx,
+                "n_gpu_layers": self.spec.n_gpu_layers,
+                "verbose": False,
+            }
+            if self.spec.kind == "vision":
+                from llama_cpp.llama_chat_format import MTMDChatHandler
+                mmproj = next((p for p in self.model_dir.glob("*.gguf")
+                              if "mmproj" in p.name.lower()), None)
+                if mmproj is None:
+                    raise FileNotFoundError(f"No mmproj file found in {self.model_dir} for vision model")
+                kwargs["chat_handler"] = MTMDChatHandler(clip_model_path=str(mmproj))
+                kwargs["chat_format"] = self.spec.chat_format or "mtmd"
+            elif self.spec.chat_format:
+                kwargs["chat_format"] = self.spec.chat_format
+            self._llm = Llama(**kwargs)
+
+    def chat(self, messages: list[dict[str, Any]], tools=None, temperature=0.2,
+             max_tokens=1024, json_mode: bool = False) -> dict[str, Any]:
+        self._ensure_loaded()
+        with self._lock:
+            payload: dict[str, Any] = {
+                "messages": messages,
+                "temperature": temperature,
+                "max_tokens": max_tokens,
+            }
+            if tools:
+                payload["tools"] = tools
+            if json_mode:
+                payload["response_format"] = {"type": "json_object"}
+            resp = self._llm.create_chat_completion(**payload)
+        # Qwen3.5 emits native <tool_call> XML in the content field rather than
+        # the structured tool_calls field. Parse it so parse_tool_calls() works.
+        self._extract_native_tool_calls(resp)
+        return resp
+
+    @staticmethod
+    def _extract_native_tool_calls(resp: dict[str, Any]) -> None:
+        """Populate message.tool_calls from Qwen3.5 native XML in content.
+
+        Qwen3.5 streams tool invocations as:
+            <tool_call><function=terminal><parameter=command>
+            pwd && ls -la</parameter></function></tool_call>
+        llama.cpp does not always surface these in the structured tool_calls
+        field, so we parse the content and synthesize the OpenAI-compatible
+        structure the rest of the codebase expects.
+        """
+        import re
+        try:
+            msg = resp["choices"][0]["message"]
+        except (KeyError, IndexError, TypeError):
+            return
+        if msg.get("tool_calls"):
+            return  # already structured
+        content = msg.get("content") or ""
+        if "<tool_call>" not in content and "<function=" not in content:
+            return
+        block_re = re.compile(r"<tool_call>(.*?)</tool_call>", re.DOTALL)
+        fn_re = re.compile(r"<function=([^>]+)>")
+        param_re = re.compile(r"<parameter=([^>]+)>(.*?)</parameter>", re.DOTALL)
+        calls: list[dict[str, Any]] = []
+        # Prefer explicit <tool_call> wrappers; fall back to bare <function=...>
+        # blocks (Qwen3.5 sometimes emits them without the wrapper).
+        blocks = block_re.findall(content) or [content]
+        for block in blocks:
+            fn_match = fn_re.search(block)
+            if not fn_match:
+                continue
+            name = fn_match.group(1).strip()
+            args: dict[str, Any] = {k.strip(): v.strip() for k, v in param_re.findall(block)}
+            calls.append({
+                "id": f"call_{len(calls)}",
+                "type": "function",
+                "function": {"name": name, "arguments": json.dumps(args, ensure_ascii=False)},
+            })
+        if calls:
+            msg["tool_calls"] = calls
+            # Drop any <think>...</think> reasoning trace (e.g. Ornith) and the
+            # tool-call wrapper so the remaining content is the final answer.
+            cleaned = block_re.sub("", content)
+            cleaned = re.sub(r"<think>.*?</think>", "", cleaned, flags=re.DOTALL)
+            msg["content"] = cleaned.strip()
+
+    def complete(self, prompt: str, temperature=0.2, max_tokens=256) -> str:
+        self._ensure_loaded()
+        with self._lock:
+            resp = self._llm(prompt, temperature=temperature, max_tokens=max_tokens)
+        return resp["choices"][0]["text"]
+
+    async def acomplete(self, messages: list, **kw) -> ChatMessage:
+        """Async wrapper so AgentLoop can call provider.acomplete unchanged."""
+        # Convert ChatMessage dataclasses to plain dicts for llama_cpp,
+        # preserving tool_calls / tool_call_id for multi-turn tool loops.
+        def _to_dict(m):
+            if isinstance(m, ChatMessage):
+                d: dict[str, Any] = {"role": m.role, "content": m.content}
+                if m.name:
+                    d["name"] = m.name
+                if getattr(m, "tool_calls", None):
+                    d["tool_calls"] = m.tool_calls
+                if getattr(m, "tool_call_id", None):
+                    d["tool_call_id"] = m.tool_call_id
+                return d
+            return m
+
+        msgs = [_to_dict(m) for m in messages]
+        # Run the (blocking) llama_cpp inference in a worker thread so the event
+        # loop is free for other concurrent workers. The GIL is released during
+        # the C++ generation, so genuinely parallel token generation happens when
+        # each worker uses its own runner instance.
+        loop = asyncio.get_running_loop()
+        resp = await loop.run_in_executor(
+            None,
+            lambda: self.chat(
+                msgs, tools=kw.get("tools"),
+                temperature=kw.get("temperature", 0.2),
+                max_tokens=kw.get("max_tokens", 1024),
+                json_mode=kw.get("json_mode", False),
+            ),
+        )
+        msg = resp["choices"][0]["message"]
+        cm = ChatMessage(role=msg.get("role", "assistant"),
+                         content=msg.get("content") or "", name=msg.get("name"))
+        # llama_cpp returns tool_calls as dicts; expose as objects so
+        # parse_tool_calls() works unchanged.
+        raw_tc = msg.get("tool_calls")
+        if raw_tc:
+
+            class _Fn:
+                def __init__(self, d):
+                    self.name = d["function"]["name"]
+                    self.arguments = d["function"].get("arguments", "{}")
+
+            class _TC:
+                def __init__(self, d):
+                    self.id = d.get("id", "call")
+                    self.function = _Fn(d)
+
+            cm.tool_calls = [_TC(d) for d in raw_tc]
+        return cm

opencommand/modules/knowledge.py

@@ -0,0 +1,85 @@
+"""Knowledge base: assembles the instruction context injected into workers.
+
+Each worker instance is bootstrapped with:
+  - SKILLS  (modules/skills/*.md)        -> how to do kinds of tasks
+  - TASKS   (<workspace>/.opencommand/tasks/*.md) -> reusable playbooks
+  - TOOLS   (registry schema summaries)  -> what actions are available
+  - DOCS    (<workspace>/.opencommand/docs/*.md)  -> learned reference docs
+
+This is what lets the Commander "load skills, tasks, and tools into each worker
+instance" and self-improve over time: new skills/tasks/docs written by the
+instructions tool are picked up on the next run (or next phase).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..core.tools import ToolRegistry
+from .tools.instructions import builtin_skills_dir, skills_dir
+
+_SKILLS_MAX_CHARS = 4000
+_TASKS_MAX_CHARS = 2500
+_DOCS_MAX_CHARS = 2500
+
+
+class KnowledgeBase:
+    """Reads skills/tasks/docs/tools and renders a bounded context string."""
+
+    def __init__(self, workspace: Path, tools: ToolRegistry) -> None:
+        self.workspace = workspace
+        self.tools = tools
+
+    def skills(self) -> str:
+        # Built-in skills ship with the package (read-only defaults); the swarm
+        # writes new/updated skills under the workspace, which take precedence.
+        builtin = self._read_bounded(builtin_skills_dir(), _SKILLS_MAX_CHARS, "SKILLS")
+        ws = self._read_bounded(skills_dir(self.workspace), _SKILLS_MAX_CHARS, "SKILLS")
+        parts = [p for p in (builtin, ws) if p]
+        return "\n\n".join(parts)
+
+    def tasks(self) -> str:
+        root = self.workspace / ".opencommand" / "tasks"
+        return self._read_bounded(root, _TASKS_MAX_CHARS, "TASKS")
+
+    def docs(self) -> str:
+        root = self.workspace / ".opencommand" / "docs"
+        return self._read_bounded(root, _DOCS_MAX_CHARS, "DOCS")
+
+    def tools_catalog(self) -> str:
+        lines = []
+        for t in self.tools._tools.values():
+            params = t.parameters or {}
+            props = params.get("properties", {})
+            args = ", ".join(props.keys()) or "none"
+            lines.append(f"- {t.name}({args}): {t.description}")
+        return "AVAILABLE TOOLS:\n" + "\n".join(lines)
+
+    def worker_context(self) -> str:
+        """Full instruction block for a worker's system prompt."""
+        parts = [self.tools_catalog()]
+        if sk := self.skills():
+            parts.append(sk)
+        if tk := self.tasks():
+            parts.append(tk)
+        if dc := self.docs():
+            parts.append(dc)
+        return "\n\n".join(parts)
+
+    @staticmethod
+    def _read_bounded(root: Path, limit: int, label: str) -> str:
+        if not root.exists():
+            return ""
+        chunks: list[str] = []
+        total = 0
+        for f in sorted(root.glob("*.md")):
+            text = f.read_text(encoding="utf-8")
+            if total + len(text) > limit:
+                text = text[: max(0, limit - total)]
+            chunks.append(f"## {f.stem}\n{text}")
+            total += len(text)
+            if total >= limit:
+                break
+        if not chunks:
+            return ""
+        return f"{label}:\n" + "\n\n".join(chunks)

opencommand/modules/memory/MEMORY.md

@@ -0,0 +1,14 @@
+# OpenCommand Memory
+
+Obsidian-style tagged memory store. Notes are saved per-topic as markdown files
+under `<workspace>/.opencommand/memory/` by the `memory` tool. Use `#tags` for
+retrieval. This file is the index.
+
+## Index
+- `goal_plan.md` — the Commander's multi-phase plan for the current goal.
+- `goal_report.md` — final report after executing a goal.
+
+## Conventions
+- One topic per file: `topic.md` with `# Topic #tag1 #tag2` header.
+- Workers and the Commander both read/write here; it is the shared long-term
+  memory of the swarm.

opencommand/modules/skills/bash.md

@@ -0,0 +1,14 @@
+# Bash Skill
+
+Use `bash` for Linux/macOS shell tasks. OpenCommand runs shell via the
+`terminal` tool, which on POSIX uses `/bin/sh -c`.
+
+## Conventions
+- Prefer portable POSIX sh; avoid bashisms unless the target is GNU/Linux.
+- Chain with `&&` and use `set -euo pipefail` in scripts for safety.
+- Use `uv` for Python: `uv add <pkg>`, `uv run <cmd>`, `uv sync`.
+- Inspect processes with `ps`, `pgrep`; logs with `tail -f`.
+- For long-running servers, background them and capture logs.
+
+## When to use
+- Installing system deps, running tests, git operations, build steps.