pilot-workers 0.2.0__py3-none-any.whl

pilot_workers/policy.py

@@ -0,0 +1,295 @@
+#!/usr/bin/env python3
+"""Mode policy: agents, shell permission rules, prompts, and runner config.
+
+Permission-matching facts (read from the pinned OpenCode binary,
+confirmed by live probes):
+
+- Resolution is LAST-MATCH-WINS (`findLast` over insertion-ordered rules).
+  Deny rules must be inserted AFTER the allow rules they override.
+- Each bash command is parsed with tree-sitter; every AST command node is
+  checked separately. Operator-symbol rules (`*|*`, `*&&*`, etc.) are dead
+  weight — each segment already hits the real allow/deny on its own.
+- Redirected statements match with FULL text, so read-only modes keep a
+  `*>*` deny inserted LAST to block redirect writes.
+
+This layer guards against mistakes, not malicious models. Not an OS sandbox.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+try:
+    import yaml  # type: ignore[import-untyped]
+except ImportError:
+    yaml = None  # type: ignore[assignment]
+
+from pilot_workers.providers import Provider
+
+PERMISSIONS_DIR = Path(__file__).resolve().parent / "data" / "permissions"
+
+VALID_MODES = ("code", "explore", "test", "review")
+
+MODE_TO_AGENT = {
+    "code": "worker-code",
+    "explore": "worker-explore",
+    "test": "worker-test",
+    "review": "worker-review",
+    "resume": "worker-code",
+}
+
+STEPS_BY_MODE = {"code": 120, "resume": 120, "review": 120, "explore": 80, "test": 80}
+
+PROMPTS_DIR = Path(__file__).resolve().parent / "prompts"
+
+
+def load_prompt(mode: str) -> str:
+    prompt_mode = "code" if mode == "resume" else mode
+    parts = []
+    for name in ("common.md", f"{prompt_mode}.md"):
+        path = PROMPTS_DIR / name
+        if not path.is_file():
+            raise RuntimeError(f"worker prompt file missing: {path}")
+        text = path.read_text(encoding="utf-8").strip()
+        if not text:
+            raise RuntimeError(f"worker prompt file is empty: {path}")
+        parts.append(text)
+    return "\n\n".join(parts)
+
+
+def denied_shell_patterns() -> dict[str, str]:
+    return {
+        "git push*": "deny",
+        "git pull*": "deny",
+        "git fetch*": "deny",
+        "git clone*": "deny",
+        "git remote add*": "deny",
+        "gh *": "deny",
+        "curl *": "deny",
+        "wget *": "deny",
+        "ssh *": "deny",
+        "scp *": "deny",
+        "sftp *": "deny",
+        "rsync *": "deny",
+        "nc *": "deny",
+        "ncat *": "deny",
+        "npm publish*": "deny",
+        "pnpm publish*": "deny",
+        "yarn publish*": "deny",
+        "rm -rf /*": "deny",
+        "rm -rf ~*": "deny",
+        "sudo *": "deny",
+        "*auth.json*": "deny",
+        "*.env*": "deny",
+    }
+
+
+def readonly_shell_permissions() -> dict[str, str]:
+    rules = {
+        "*": "deny",
+        "pwd": "allow",
+        "ls*": "allow",
+        "cat *": "allow",
+        "echo *": "allow",
+        "find *": "allow",
+        "rg *": "allow",
+        "grep *": "allow",
+        "sed *": "allow",
+        "awk *": "allow",
+        "head *": "allow",
+        "tail *": "allow",
+        "wc *": "allow",
+        "file *": "allow",
+        "stat *": "allow",
+        "npx tsc*": "allow",
+        "git status*": "allow",
+        "git diff*": "allow",
+        "git log*": "allow",
+        "git show*": "allow",
+        "git blame*": "allow",
+        "git branch*": "allow",
+        "git grep*": "allow",
+        "git rev-parse*": "allow",
+        "git ls-files*": "allow",
+    }
+    rules.update(denied_shell_patterns())
+    rules["*>*"] = "deny"
+    return rules
+
+
+def test_shell_permissions() -> dict[str, str]:
+    rules = readonly_shell_permissions()
+    rules.update(
+        {
+            "npm test*": "allow",
+            "npm run test*": "allow",
+            "npm run lint*": "allow",
+            "npm run typecheck*": "allow",
+            "npm run build*": "allow",
+            "pnpm test*": "allow",
+            "pnpm run test*": "allow",
+            "pnpm run lint*": "allow",
+            "pnpm run typecheck*": "allow",
+            "pnpm run build*": "allow",
+            "yarn test*": "allow",
+            "yarn lint*": "allow",
+            "yarn build*": "allow",
+            "bun test*": "allow",
+            "pytest*": "allow",
+            "python -m pytest*": "allow",
+            "go test*": "allow",
+            "cargo test*": "allow",
+            "npx vitest run*": "allow",
+            "dart test*": "allow",
+            "flutter test*": "allow",
+            "make test*": "allow",
+            "make check*": "allow",
+            "make lint*": "allow",
+            "just test*": "allow",
+            "composer test*": "allow",
+            "php artisan test*": "allow",
+            "mvn test*": "allow",
+            "./gradlew test*": "allow",
+        }
+    )
+    rules.update(denied_shell_patterns())
+    return rules
+
+
+def code_shell_permissions() -> dict[str, str]:
+    rules = {"*": "allow"}
+    rules.update(denied_shell_patterns())
+    return rules
+
+
+def agent_permissions(mode: str) -> dict[str, Any]:
+    effective_mode = "code" if mode == "resume" else mode
+    editable = effective_mode == "code"
+    if effective_mode == "code":
+        bash = code_shell_permissions()
+    elif effective_mode == "test":
+        bash = test_shell_permissions()
+    else:
+        bash = readonly_shell_permissions()
+    return {
+        "*": "deny",
+        "read": "allow",
+        "edit": "allow" if editable else "deny",
+        "glob": "allow",
+        "grep": "allow",
+        "list": "allow",
+        "bash": bash,
+        "task": "deny",
+        "todowrite": "allow",
+        "webfetch": "deny",
+        "websearch": "deny",
+        "external_directory": "deny",
+        "lsp": "allow",
+        "skill": "deny",
+        "question": "deny",
+        "doom_loop": "deny",
+        "mcp_*": "deny",
+    }
+
+
+def load_permission_profile(name: str) -> dict[str, Any]:
+    """Load a permission profile YAML from the permissions/ directory."""
+    path = PERMISSIONS_DIR / f"{name}.yaml"
+    if not path.is_file():
+        raise RuntimeError(f"permission profile not found: {path}")
+    if yaml is None:
+        raise RuntimeError(
+            f"pyyaml is required for custom permission profiles; "
+            f"install it with: pip install pyyaml"
+        )
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise RuntimeError(f"permission profile must be a YAML mapping: {path}")
+    for key in data:
+        if key != "_all" and key not in VALID_MODES:
+            raise RuntimeError(
+                f"permission profile has unknown section '{key}' "
+                f"(expected _all or one of {VALID_MODES}): {path}"
+            )
+    return data
+
+
+def _merge_permissions(
+    base: dict[str, Any], profile: dict[str, Any] | None, mode: str,
+) -> dict[str, Any]:
+    """Merge a permission profile into base agent permissions.
+
+    Shell rules from the profile are appended after the base rules
+    (last-match-wins in OpenCode). Tool rules overwrite base values.
+    """
+    if profile is None:
+        return base
+
+    sections = []
+    if "_all" in profile:
+        sections.append(profile["_all"])
+    effective_mode = "code" if mode == "resume" else mode
+    if effective_mode in profile:
+        sections.append(profile[effective_mode])
+    if not sections:
+        return base
+
+    result = dict(base)
+    bash_rules = dict(result.get("bash", {}))
+
+    for section in sections:
+        if not isinstance(section, dict):
+            continue
+        for pattern, action in (section.get("shell") or {}).items():
+            bash_rules[pattern] = action
+        for tool, action in (section.get("tools") or {}).items():
+            result[tool] = action
+
+    result["bash"] = bash_rules
+    return result
+
+
+def build_config(provider: Provider, mode: str, *, permission_profile: str | None = None) -> dict[str, Any]:
+    profile_name = permission_profile or provider.permissions
+    profile = load_permission_profile(profile_name) if profile_name else None
+    agent_name = MODE_TO_AGENT[mode]
+    prompt_mode = "code" if mode == "resume" else mode
+    model = provider.model
+    permissions = _merge_permissions(agent_permissions(mode), profile, mode)
+    return {
+        "$schema": "https://opencode.ai/config.json",
+        "autoupdate": False,
+        "share": "disabled",
+        "model": model,
+        "small_model": model,
+        "default_agent": agent_name,
+        "enabled_providers": [provider.provider_id],
+        "provider": {
+            provider.provider_id: {
+                "npm": "@ai-sdk/openai-compatible",
+                "name": provider.display_name,
+                "options": {"baseURL": provider.base_url},
+                "models": {
+                    provider.model_id: {
+                        "name": provider.display_name,
+                        "limit": {
+                            "context": provider.context_tokens,
+                            "output": provider.output_tokens,
+                        },
+                    }
+                },
+            }
+        },
+        "permission": {"*": "deny"},
+        "agent": {
+            agent_name: {
+                "description": f"Isolated {prompt_mode} worker controlled by the main planner",
+                "mode": "primary",
+                "model": model,
+                "steps": STEPS_BY_MODE[mode],
+                "prompt": load_prompt(mode),
+                "permission": permissions,
+            }
+        },
+    }

pilot_workers/prompts/code.md

@@ -0,0 +1,6 @@
+Mode: code (edits allowed).
+
+- Implement only the approved behavior. Make the smallest convention-aligned edits; follow the codebase's existing patterns and naming.
+- If the task gives a file whitelist, never touch files outside it.
+- Self-validate before finishing: run the checks the task specifies; if none are specified, use the project's standard test/lint commands. Do not finish with failing checks unless you can prove the failure is pre-existing — then include that proof in VALIDATION.
+- Report problems you noticed but deliberately did not touch (out-of-scope, pre-existing, suspicious) in REMAINING_RISKS.

pilot_workers/prompts/common.md

@@ -0,0 +1,24 @@
+You are an execution worker controlled by a main planner process (Codex or Claude). Follow the supplied task contract exactly. Do not invent requirements, broaden scope, delegate to subagents, access credentials, share the session, or contact unrelated network services. Inspect the named implementation paths before making claims. Fail visibly when a required action is blocked.
+
+Workspace discipline:
+
+- The workspace may contain pre-existing uncommitted changes. That is normal: do not explain them, do not revert them, and do not count them in your own change list.
+- Stay inside the given work directory. Do not touch paths outside it.
+
+Permission preview — these command classes are denied at the permission layer, in every mode. Do not attempt them; if the task seems to require one, stop and report it as blocked instead of retrying or working around it:
+
+- Remote Git operations (`git push/pull/fetch/clone/remote add`, `gh`).
+- Network clients (`curl`, `wget`, `ssh`, `scp`, `sftp`, `rsync`, `nc`).
+- Package publishing (`npm/pnpm/yarn publish`).
+- Credential paths (anything touching `auth.json` or `.env` files), `sudo`, and destructive root/home deletion.
+
+A blocked call returns a permission error once; never retry it verbatim.
+
+Final report — end with exactly these four sections:
+
+1. `STATUS`: complete, incomplete, or blocked.
+2. `FILES_CHANGED`: exact paths with a one-line purpose each, or `none`.
+3. `VALIDATION`: the commands you ran and their verbatim key output (counts, failing test names, error text). Quote real output; never paraphrase it.
+4. `REMAINING_RISKS`: unmet boundaries, assumptions, pre-existing problems you noticed but did not touch, or `none`.
+
+The main planner will independently review and verify your work; your completion claim is not the acceptance decision.

pilot_workers/prompts/explore.md

@@ -0,0 +1,7 @@
+Mode: explore (read-only; file edits are denied at the permission layer).
+
+- Investigate read-only. Do not edit files; do not retry denied write attempts.
+- Every conclusion must carry a `file:line` reference. A conclusion without a reference is invalid.
+- Output structured items, one fact per item; no preamble, summaries, or commentary.
+- Quote at most 3 lines of code per item; for anything longer give the `file:line` reference instead.
+- Cap conclusions at 20 items unless the task sets a different budget; if you exceed the cap, list the most important ones and note how many more exist and in which directories.

pilot_workers/prompts/review.md

@@ -0,0 +1,5 @@
+Mode: review (read-only; file edits are denied at the permission layer).
+
+- Review read-only. Do not edit files and do not fix anything.
+- Report only substantiated findings: each finding needs a severity, an exact `file:line` location, the observed behavior, the concrete impact, and a specific fix direction.
+- Do not pad the report with style opinions or unverified suspicions; if something is a hunch, label it as unverified in one line or drop it.

pilot_workers/prompts/test.md

@@ -0,0 +1,6 @@
+Mode: test (read-only for source; only test/lint/build and read-only commands are allowed).
+
+- Validate without editing source files.
+- Run only the approved checks from the task contract.
+- Report complete failure output verbatim: full failing test names, assertion messages, and exit statuses — enough for the planner to diagnose without rerunning.
+- Do not attempt fixes; diagnosis and fixing belong to the planner.

pilot_workers/providers.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""Provider registry: loads provider definitions from YAML files.
+
+The single source of truth for provider routing is the `data/providers/`
+directory inside this package. Each `.yaml` file defines one provider.
+Adding a new model only requires dropping a new YAML file — no Python changes.
+
+The shared path helpers also live here so that every other module imports
+facts from one place.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from pathlib import Path
+from typing import Any
+
+try:
+    import yaml  # type: ignore[import-untyped]
+except ImportError:
+    yaml = None  # type: ignore[assignment]
+
+
+MAX_TASK_BYTES = 512_000
+
+PROVIDERS_DIR = Path(__file__).resolve().parent / "data" / "providers"
+
+
+@dataclass(frozen=True)
+class Provider:
+    key: str
+    provider_id: str
+    model_id: str
+    base_url: str
+    display_name: str
+    context_tokens: int
+    output_tokens: int
+    permissions: str | None = None
+    runner: str = "opencode"
+
+    @property
+    def model(self) -> str:
+        return f"{self.provider_id}/{self.model_id}"
+
+
+def _parse_yaml(path: Path) -> dict[str, Any]:
+    """Parse a YAML file, with a stdlib fallback for simple flat files."""
+    text = path.read_text(encoding="utf-8")
+    if yaml is not None:
+        return yaml.safe_load(text)
+    # Minimal fallback: flat key: value files without nesting.
+    result: dict[str, Any] = {}
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if ":" not in line:
+            continue
+        key, _, value = line.partition(":")
+        value = value.strip()
+        if value.isdigit():
+            result[key.strip()] = int(value)
+        else:
+            result[key.strip()] = value
+    return result
+
+
+def load_providers(providers_dir: Path | None = None) -> dict[str, Provider]:
+    """Discover and load all provider YAML files from the given directory."""
+    directory = providers_dir or PROVIDERS_DIR
+    if not directory.is_dir():
+        raise RuntimeError(f"providers directory does not exist: {directory}")
+    providers: dict[str, Provider] = {}
+    for path in sorted(directory.glob("*.yaml")):
+        data = _parse_yaml(path)
+        required = ("key", "provider_id", "model_id", "base_url", "display_name",
+                     "context_tokens", "output_tokens")
+        missing = [f for f in required if f not in data]
+        if missing:
+            raise RuntimeError(f"provider {path.name} missing fields: {', '.join(missing)}")
+        provider = Provider(
+            key=data["key"],
+            provider_id=data["provider_id"],
+            model_id=data["model_id"],
+            base_url=data["base_url"],
+            display_name=data["display_name"],
+            context_tokens=int(data["context_tokens"]),
+            output_tokens=int(data["output_tokens"]),
+            permissions=data.get("permissions") or None,
+            runner=data.get("runner") or "opencode",
+        )
+        if provider.key in providers:
+            raise RuntimeError(f"duplicate provider key: {provider.key}")
+        providers[provider.key] = provider
+    if not providers:
+        raise RuntimeError(f"no provider YAML files found in {directory}")
+    return providers
+
+
+# Eagerly loaded at import time for backwards compatibility with existing code
+# that does `from providers import PROVIDERS`. Callers that need a custom
+# directory can call load_providers() directly.
+PROVIDERS = load_providers()
+
+
+def pilot_home() -> Path:
+    """Root for all pilot-workers runtime data (credentials, logs, worktrees)."""
+    return Path(os.environ.get("PILOT_WORKERS_HOME",
+                os.environ.get("CODEX_HOME", Path.home() / ".codex"))).expanduser().resolve()
+
+
+def workers_root() -> Path:
+    return pilot_home() / "opencode-workers"
+
+
+def profile_root(provider: Provider) -> Path:
+    return workers_root() / "providers" / provider.key
+
+
+def profile_paths(provider: Provider) -> dict[str, Path]:
+    root = profile_root(provider)
+    return {
+        "root": root,
+        "config": root / "config",
+        "data": root / "data",
+        "state": root / "state",
+        "cache": root / "cache",
+    }
+
+
+def logs_root(provider: Provider) -> Path:
+    return workers_root() / "logs" / provider.key
+
+
+def worktrees_root() -> Path:
+    return workers_root() / "worktrees"

pilot_workers/runners/__init__.py

@@ -0,0 +1,28 @@
+"""Runner abstraction layer.
+
+A runner is the execution carrier that takes a task contract and runs it
+through a model. OpenCode is the first implementation; others (Aider,
+Continue, etc.) can be added by implementing the same interface.
+
+The registry below is the single entry point: callers ask for a runner by
+name via ``get_runner`` and receive a singleton ``Runner`` instance.
+"""
+
+from pilot_workers.runners.base import (
+    Runner,
+    TokenUsage,
+    ToolCall,
+    UnifiedEvent,
+)
+from pilot_workers.runners.opencode_runner import OpenCodeRunner
+
+RUNNERS: dict[str, Runner] = {"opencode": OpenCodeRunner()}
+
+
+def get_runner(name: str) -> Runner:
+    try:
+        return RUNNERS[name]
+    except KeyError:
+        raise RuntimeError(
+            f"unknown runner: {name} (available: {sorted(RUNNERS)})"
+        )

pilot_workers/runners/base.py

@@ -0,0 +1,123 @@
+"""Runner abstraction: unified event model + Runner interface.
+
+A runner is the execution carrier that takes a task contract and runs it
+through a model. The unified event types below are the lingua franca that
+dispatchers, renderers, and verdict logic consume; each concrete Runner
+parses its engine's native events into this shape on the read side.
+
+Design notes:
+
+- `worker_runner.started/summary/heartbeat/verdict` are pilot-workers-owned
+  events; they bypass `parse_events` and go straight to rendering/verdict.
+- `kind="step"` must fire exactly once per engine step; `build_config` must
+  hard-stop the engine at its step cap. STEPS_BY_MODE is currently calibrated
+  to OpenCode's step granularity and MUST be re-calibrated when a new runner
+  is added.
+- Runners that do not support session resume MUST raise RuntimeError on a
+  non-None `session` argument to `build_command` rather than silently ignore.
+- The on-disk JSONL always stores the runner's raw events; `parse_events`
+  only translates on the read side.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+
+@dataclass(frozen=True)
+class TokenUsage:
+    input: int = 0
+    output: int = 0
+    reasoning: int = 0
+    cache_read: int = 0
+    cache_write: int = 0
+
+
+@dataclass(frozen=True)
+class ToolCall:
+    name: str
+    status: str                    # runner-reported status, e.g. "completed" / "error"
+    input_brief: str               # single-line human-readable summary, "" if none
+    output_brief: str              # first informative output line, "" if none
+    error: str | None              # error text when status == "error"
+    is_permission_denied: bool     # whether the runner flagged a permission denial
+    silent_output: bool            # True = renderer should hide the output line
+
+
+@dataclass(frozen=True)
+class UnifiedEvent:
+    kind: Literal["step", "text", "reasoning", "tool", "error", "session"]
+    ts: int | None = None          # epoch milliseconds of the raw event, None if absent
+    text: str | None = None        # text/reasoning payload
+    tokens: TokenUsage | None = None   # step usage
+    tool: ToolCall | None = None       # tool invocation info
+    session_id: str | None = None      # session id for kind="session"
+
+
+class Runner(ABC):
+    """Worker runner adapter.
+
+    Contract (required reading for new runner implementations):
+
+    - `worker_runner.started/summary/heartbeat/verdict` are pilot-workers-owned
+      events; they do not flow through parse_events and reach rendering and
+      verdict logic directly.
+    - `kind="step"` must fire exactly once per engine step; build_config must
+      make the engine hard-stop at its steps cap. STEPS_BY_MODE is currently
+      calibrated to OpenCode's step granularity and MUST be re-calibrated
+      when a new runner is wired in.
+    - Runners that do not support session resume MUST raise RuntimeError on a
+      non-None `session` argument; they MUST NOT silently ignore it.
+    - The on-disk JSONL always stores the runner's raw events; parse_events
+      only translates on the read side.
+    """
+
+    name: str
+
+    @abstractmethod
+    def build_config(self, provider: Any, mode: str, permission_profile: str | None = None) -> dict: ...
+
+    @abstractmethod
+    def build_command(self, binary: Path, provider: Any, mode: str,
+                      workdir: Path, run_id: str, session: str | None) -> list[str]: ...
+
+    @abstractmethod
+    def runner_environment(self, provider: Any, config: dict) -> dict[str, str]:
+        """Only the env vars specific to this runner; neutral parts
+        (SAFE_ENV_KEYS / XDG) are owned by the runtime layer."""
+
+    @abstractmethod
+    def format_task_input(self, task: str, mode: str) -> str:
+        """Wrap the task text into the engine's expected first-turn input
+        (delivered via stdin)."""
+
+    @abstractmethod
+    def parse_events(self, raw: dict) -> list[UnifiedEvent]:
+        """Translate one raw event into 0..n unified events.
+        Unrecognized events return []."""
+
+    @abstractmethod
+    def resolve_binary(self) -> Path:
+        """Locate and verify the runner executable; raise RuntimeError if it
+        is missing or its version does not match."""
+
+    @abstractmethod
+    def credential_path(self, provider: Any) -> Path: ...
+
+    @abstractmethod
+    def credential_payload(self, provider: Any, key: str) -> dict:
+        """Produce the credential-file payload structure; the actual file
+        write (atomic write / 0600 mode) is owned by the neutral layer."""
+
+    @abstractmethod
+    def parse_credential(self, provider: Any, payload: dict) -> str:
+        """Extract the API key from a credential-file payload; raise
+        RuntimeError if the shape does not match."""
+
+    def binary_path(self) -> Path | None:
+        """Best-effort binary location WITHOUT verification (for dry-run display).
+        Default: None (unknown until resolve_binary)."""
+        return None