pilot-workers 0.2.0__py3-none-any.whl

pilot_workers/cli/install.py

@@ -0,0 +1,259 @@
+#!/usr/bin/env python3
+"""Install integration files (agents, commands, skills) to host config directories."""
+
+from __future__ import annotations
+
+import argparse
+import importlib.metadata
+import json
+import os
+import shutil
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+from pilot_workers import providers
+
+
+INTEGRATIONS_DIR = Path(__file__).resolve().parent.parent / "integrations"
+
+MANIFEST_SCHEMA_VERSION = 1
+
+
+def _manifest_path() -> Path:
+    return providers.pilot_home() / "install-manifest.json"
+
+
+def _package_version() -> str:
+    try:
+        return importlib.metadata.version("pilot-workers")
+    except importlib.metadata.PackageNotFoundError:
+        return "unknown"
+
+
+def _load_manifest(path: Path) -> dict:
+    if not path.exists():
+        return {"schema_version": MANIFEST_SCHEMA_VERSION, "hosts": {}}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(f"corrupt install manifest {path}: {exc}") from exc
+
+
+def _write_manifest(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary_name: str | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w", encoding="utf-8", dir=path.parent,
+            prefix=".install-manifest.", suffix=".tmp", delete=False,
+        ) as temporary:
+            temporary_name = temporary.name
+            json.dump(data, temporary, indent=2)
+            temporary.write("\n")
+            temporary.flush()
+            os.fsync(temporary.fileno())
+        os.replace(temporary_name, path)
+    finally:
+        if temporary_name and os.path.exists(temporary_name):
+            os.unlink(temporary_name)
+
+
+def _purge_previous(host: str, manifest: dict) -> None:
+    """Remove files recorded by a previous install of the same host."""
+    entry = manifest.get("hosts", {}).get(host)
+    if not entry:
+        return
+    removed = 0
+    for name in entry.get("files", []):
+        try:
+            os.unlink(name)
+            removed += 1
+        except OSError:
+            pass
+    # Drop directories the previous install created, if now empty
+    # (deepest first, so nested dirs like dispatch/references/ go before dispatch/).
+    # Only use created_dirs — do not try to rmdir file parents that the user may own.
+    candidates = {Path(d) for d in entry.get("created_dirs", [])}
+    for directory in sorted(candidates, key=lambda p: len(p.parts), reverse=True):
+        try:
+            directory.rmdir()
+        except OSError:
+            pass
+    print(f"  removed {removed} stale file(s) from previous {host} install")
+
+
+def install_claude(target: Path | None = None) -> dict:
+    """Copy Claude Code agent and command definitions."""
+    base = (target or Path.home() / ".claude").resolve()
+    src = INTEGRATIONS_DIR / "claude-host"
+    if not src.is_dir():
+        raise RuntimeError(f"integration source not found: {src}")
+
+    files: list[str] = []
+    created_dirs: list[str] = []
+
+    def _mkdir(path: Path) -> None:
+        if not path.exists():
+            created_dirs.append(str(path))
+        path.mkdir(parents=True, exist_ok=True)
+
+    agents_src = src / "agents"
+    commands_src = src / "commands"
+
+    if agents_src.is_dir():
+        agents_dst = base / "agents"
+        _mkdir(agents_dst)
+        for f in agents_src.glob("*.md"):
+            shutil.copy2(f, agents_dst / f.name)
+            files.append(str(agents_dst / f.name))
+            print(f"  installed agent: {f.name}")
+
+    if commands_src.is_dir():
+        for provider_dir in commands_src.iterdir():
+            if not provider_dir.is_dir():
+                continue
+            dst = base / "commands" / provider_dir.name
+            _mkdir(dst)
+            for f in provider_dir.glob("*.md"):
+                shutil.copy2(f, dst / f.name)
+                files.append(str(dst / f.name))
+                print(f"  installed command: {provider_dir.name}/{f.name}")
+
+    return {"files": files, "created_dirs": created_dirs}
+
+
+def install_codex(target: Path | None = None) -> dict:
+    """Copy Codex skill definitions."""
+    codex_home = Path(os.environ.get("CODEX_HOME", Path.home() / ".codex"))
+    base = (target or codex_home / "skills").resolve()
+    src = INTEGRATIONS_DIR / "codex-host"
+    if not src.is_dir():
+        raise RuntimeError(f"integration source not found: {src}")
+
+    files: list[str] = []
+    created_dirs: list[str] = []
+
+    for skill_dir in src.iterdir():
+        if not skill_dir.is_dir():
+            continue
+        dst = base / skill_dir.name
+        dst.mkdir(parents=True, exist_ok=True)
+        # Copy files individually (do not rmtree — that would delete user content)
+        for src_file in sorted(skill_dir.rglob("*")):
+            if src_file.is_dir():
+                continue
+            rel = src_file.relative_to(skill_dir)
+            dest_file = dst / rel
+            dest_file.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(src_file, dest_file)
+        created_dirs.append(str(dst))
+        for f in sorted(dst.rglob("*")):
+            if f.is_dir():
+                created_dirs.append(str(f))
+            elif f.is_file():
+                files.append(str(f))
+        print(f"  installed skill: {skill_dir.name}/")
+
+    return {"files": files, "created_dirs": created_dirs}
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Install pilot-workers integrations.")
+    parser.add_argument("host", choices=["claude", "codex", "all"], help="Target host.")
+    parser.add_argument("--target", type=Path, help="Override target directory.")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    try:
+        manifest_path = _manifest_path()
+        manifest = _load_manifest(manifest_path)
+        manifest["schema_version"] = MANIFEST_SCHEMA_VERSION
+        manifest.setdefault("hosts", {})
+        for host, label, installer in (
+            ("claude", "Claude Code", install_claude),
+            ("codex", "Codex", install_codex),
+        ):
+            if args.host not in (host, "all"):
+                continue
+            print(f"Installing {label} integrations...")
+            _purge_previous(host, manifest)
+            result = installer(args.target)
+            manifest["hosts"][host] = {
+                "installed_at": datetime.now(timezone.utc).isoformat(),
+                "package_version": _package_version(),
+                "files": result["files"],
+                "created_dirs": result["created_dirs"],
+            }
+            _write_manifest(manifest_path, manifest)
+        print("Done.")
+        return 0
+    except (OSError, RuntimeError) as exc:
+        print(f"error: {exc}")
+        return 1
+
+
+def _uninstall_host(entry: dict) -> None:
+    for name in entry.get("files", []):
+        path = Path(name)
+        if not path.exists():
+            print(f"note: already gone: {name}")
+            continue
+        path.unlink()
+        print(f"removed: {name}")
+    dirs = sorted(entry.get("created_dirs", []),
+                  key=lambda p: len(Path(p).parts), reverse=True)
+    for name in dirs:
+        try:
+            os.rmdir(name)
+            print(f"removed: {name}")
+        except OSError:
+            print(f"note: kept non-empty directory: {name}")
+
+
+def uninstall_main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Uninstall pilot-workers integrations.")
+    parser.add_argument("host", choices=["claude", "codex", "all"], help="Target host.")
+    args = parser.parse_args(argv)
+
+    hosts = ["claude", "codex"] if args.host == "all" else [args.host]
+    manifest_path = _manifest_path()
+    if not manifest_path.exists():
+        print(f"error: no install manifest found at {manifest_path}", file=sys.stderr)
+        return 1
+    try:
+        manifest = _load_manifest(manifest_path)
+    except (OSError, RuntimeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    entries = manifest.get("hosts", {})
+    present = [h for h in hosts if h in entries]
+    missing = [h for h in hosts if h not in entries]
+    if missing and not present:
+        print(f"error: no manifest entry for host(s): {', '.join(missing)}",
+              file=sys.stderr)
+        return 1
+    if missing:
+        for h in missing:
+            print(f"note: no manifest entry for {h}, skipping", file=sys.stderr)
+    try:
+        for host in present:
+            print(f"Uninstalling {host} integrations...")
+            _uninstall_host(entries.pop(host))
+        if entries:
+            manifest["hosts"] = entries
+            _write_manifest(manifest_path, manifest)
+        else:
+            manifest_path.unlink()
+        print("Done.")
+        return 0
+    except (OSError, RuntimeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pilot_workers/cli/main.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""Unified CLI entry: pilot-workers <subcommand> ..."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import subprocess
+import sys
+
+
+USAGE = """usage: pilot-workers <subcommand> [args]
+
+subcommands:
+  run          Dispatch a bounded task to an isolated LLM worker.
+  dispatch     Deterministic outer shell around run (started + verdict JSON).
+  template     Print the task template for a mode (code|explore|test|review).
+  install      Install worker integration assets.
+  uninstall    Remove worker integration assets.
+  credentials  Configure isolated worker credentials.
+  maintain     Worker log and worktree lifecycle tools.
+  runtime      Manage the worker runtime (runtime install).
+
+Use 'pilot-workers <subcommand> --help' for subcommand-specific help.
+"""
+
+
+def _with_argv(program: str, rest: list[str], fn) -> int:
+    """Call a no-arg main() that parses sys.argv, with a temporary argv."""
+    original = sys.argv
+    sys.argv = [program] + rest
+    try:
+        return fn()
+    finally:
+        sys.argv = original
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    if not args or args[0] in ("-h", "--help"):
+        print(USAGE, end="")
+        return 0
+
+    subcommand, rest = args[0], args[1:]
+
+    if subcommand == "run":
+        from pilot_workers.cli.run import main as run_main
+
+        return run_main(rest)
+
+    if subcommand == "dispatch":
+        from pilot_workers.cli.dispatch import main as dispatch_main
+
+        return dispatch_main(rest)
+
+    if subcommand == "template":
+        import pilot_workers
+
+        modes = ("code", "explore", "test", "review")
+        if len(rest) != 1 or rest[0] not in modes:
+            print(f"usage: pilot-workers template {{{'|'.join(modes)}}}", file=sys.stderr)
+            return 2
+        path = (
+            Path(pilot_workers.__file__).resolve().parent
+            / "data" / "templates" / f"{rest[0]}.md"
+        )
+        if not path.is_file():
+            print(f"error: template missing from package: {path}", file=sys.stderr)
+            return 1
+        sys.stdout.write(path.read_text(encoding="utf-8"))
+        return 0
+
+    if subcommand == "install":
+        from pilot_workers.cli.install import main as install_main
+
+        return install_main(rest)
+
+    if subcommand == "uninstall":
+        from pilot_workers.cli import install as install_mod
+
+        fn = getattr(install_mod, "uninstall_main", None)
+        if fn is None:
+            print("error: uninstall not available in this build", file=sys.stderr)
+            return 1
+        return fn(rest)
+
+    if subcommand == "credentials":
+        from pilot_workers.credentials import main as credentials_main
+
+        return _with_argv("pilot-workers credentials", rest, credentials_main)
+
+    if subcommand == "maintain":
+        from pilot_workers.maintain import main as maintain_main
+
+        return _with_argv("pilot-workers maintain", rest, maintain_main)
+
+    if subcommand == "runtime":
+        if rest != ["install"]:
+            print("usage: pilot-workers runtime install", file=sys.stderr)
+            return 2
+        import pilot_workers
+
+        script = (
+            Path(pilot_workers.__file__).resolve().parent
+            / "scripts"
+            / "install_runtime.sh"
+        )
+        return subprocess.run(["bash", str(script)]).returncode
+
+    print(f"error: unknown subcommand: {subcommand}", file=sys.stderr)
+    print(USAGE, end="", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pilot_workers/cli/run.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""CLI entry: pilot-workers run — dispatch a worker task."""
+
+from __future__ import annotations
+
+import argparse
+from datetime import datetime, timezone
+import json
+import os
+from pathlib import Path
+import secrets
+import sys
+
+from pilot_workers import fmt_events, policy, providers, runtime
+from pilot_workers.runners import get_runner
+
+
+DEFAULT_TIMEOUT_S = 3600
+DEFAULT_IDLE_TIMEOUT_S = 900
+
+
+def load_task(args: argparse.Namespace) -> str:
+    if args.task is not None:
+        task = args.task
+    else:
+        path = Path(args.task_file).expanduser().resolve()
+        if not path.is_file():
+            raise RuntimeError(f"task file does not exist: {path}")
+        if path.stat().st_size > providers.MAX_TASK_BYTES:
+            raise RuntimeError(f"task file exceeds {providers.MAX_TASK_BYTES} bytes: {path}")
+        task = path.read_text(encoding="utf-8")
+    if not task.strip():
+        raise RuntimeError("task must not be empty")
+    if len(task.encode("utf-8")) > providers.MAX_TASK_BYTES:
+        raise RuntimeError(f"task exceeds {providers.MAX_TASK_BYTES} bytes")
+    return task.strip()
+
+
+def validate_mode_arguments(args: argparse.Namespace) -> None:
+    if args.mode == "resume" and not args.session:
+        raise RuntimeError("--session is required when --mode resume is used")
+    if args.mode != "resume" and args.session:
+        raise RuntimeError("--session is only valid with --mode resume")
+    if args.mode == "resume" and args.worktree:
+        raise RuntimeError("resume the previously reported work directory; do not create a new worktree")
+
+
+def dry_run_summary(provider: providers.Provider, mode: str, workdir: Path, *, permission_profile: str | None = None) -> dict:
+    runner = get_runner(provider.runner)
+    config = runner.build_config(provider, mode, permission_profile=permission_profile)
+    paths = providers.profile_paths(provider)
+    effective_profile = permission_profile or provider.permissions
+    bp = runner.binary_path()
+    return {
+        "type": "worker_runner.dry_run",
+        "provider": provider.key,
+        "runner": provider.runner,
+        "provider_id": provider.provider_id,
+        "endpoint": provider.base_url,
+        "model": provider.model,
+        "agent": policy.MODE_TO_AGENT[mode],
+        "mode": mode,
+        "workdir": str(workdir),
+        "sharing": config["share"],
+        "enabled_providers": config["enabled_providers"],
+        "permission_profile": effective_profile,
+        "profile": str(paths["root"]),
+        "credential": runtime.credential_metadata(provider, runner),
+        "runtime": str(bp) if bp else None,
+        "runtime_present": bp.is_file() if bp else False,
+    }
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Dispatch a bounded task to an isolated LLM worker.")
+    parser.add_argument("--provider", required=True, choices=sorted(providers.PROVIDERS))
+    parser.add_argument("--mode", required=True, choices=sorted(policy.MODE_TO_AGENT))
+    parser.add_argument("--workdir", required=True, help="Existing project directory.")
+    task_group = parser.add_mutually_exclusive_group(required=True)
+    task_group.add_argument("--task", help="Short task contract as a string.")
+    task_group.add_argument("--task-file", help="UTF-8 file containing the task contract.")
+    parser.add_argument("--session", help="Session ID for resume mode.")
+    parser.add_argument("--worktree", action="store_true", help="Create a detached worktree from HEAD.")
+    parser.add_argument("--timeout", type=int, default=DEFAULT_TIMEOUT_S)
+    parser.add_argument("--idle-timeout", type=int, default=DEFAULT_IDLE_TIMEOUT_S)
+    parser.add_argument("--permissions", help="Permission profile name (overrides provider YAML).")
+    parser.add_argument("--dry-run", action="store_true", help="Show routing metadata without invoking a model.")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    try:
+        validate_mode_arguments(args)
+        if args.timeout < 0 or args.idle_timeout < 0:
+            raise RuntimeError("--timeout and --idle-timeout must be >= 0")
+        provider = providers.PROVIDERS[args.provider]
+        workdir = Path(args.workdir).expanduser().resolve()
+        if not workdir.is_dir():
+            raise RuntimeError(f"work directory does not exist: {workdir}")
+        task = load_task(args)
+
+        if args.dry_run:
+            print(json.dumps(dry_run_summary(provider, args.mode, workdir, permission_profile=args.permissions), indent=2))
+            return 0
+
+        runner = get_runner(provider.runner)
+        binary = runner.resolve_binary()
+        secret = runtime.credential_key(provider, runner)
+        if args.worktree:
+            workdir = runtime.create_detached_worktree(workdir, providers.worktrees_root())
+
+        config = runner.build_config(provider, args.mode, permission_profile=args.permissions)
+        env = runtime.build_environment(provider, runner.runner_environment(provider, config))
+        logs = providers.logs_root(provider)
+        runtime.ensure_private_directory(logs)
+        run_id = f"{datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%SZ')}-{secrets.token_hex(4)}"
+        log_path = logs / f"{run_id}.jsonl"
+        stderr_path = logs / f"{run_id}.stderr.log"
+        agent = policy.MODE_TO_AGENT[args.mode]
+        prompt = runner.format_task_input(task, args.mode)
+        command = runner.build_command(binary, provider, args.mode, workdir, run_id, args.session)
+
+        try:
+            renderer = fmt_events.FmtWriter(logs, provider.key, run_id, os.getpid())
+        except Exception as exc:
+            print(f"note: live log rendering unavailable ({exc})", file=sys.stderr)
+            renderer = None
+
+        started = {
+            "type": "worker_runner.started",
+            "provider": provider.key,
+            "runner": provider.runner,
+            "model": provider.model,
+            "mode": args.mode,
+            "agent": agent,
+            "run_id": run_id,
+            "workdir": str(workdir),
+            "log": str(log_path),
+            "stderr_log": str(stderr_path),
+            "rendered_log": str(logs / "latest.log") if renderer else None,
+            "timeout_s": args.timeout,
+            "idle_timeout_s": args.idle_timeout,
+        }
+        print(json.dumps(started), flush=True)
+        if renderer is not None:
+            try:
+                renderer.write_event(started)
+            except Exception as exc:
+                print(f"note: live log rendering disabled ({exc})", file=sys.stderr)
+                renderer = None
+
+        result = runtime.run_process(
+            command, env, prompt, log_path, stderr_path, secret,
+            renderer=renderer, timeout_s=args.timeout, idle_timeout_s=args.idle_timeout,
+            runner=runner,
+        )
+        secret = ""
+        summary = {
+            "type": "worker_runner.summary",
+            "provider": provider.key,
+            "runner": provider.runner,
+            "model": provider.model,
+            "mode": args.mode,
+            "agent": agent,
+            "run_id": run_id,
+            "session_id": result.session_id or args.session,
+            "workdir": str(workdir),
+            "log": str(log_path),
+            "stderr_log": str(stderr_path),
+            "rendered_log": started["rendered_log"],
+            "timed_out": result.timed_out,
+            "idle_timed_out": result.idle_timed_out,
+            "interrupted": result.interrupted,
+            "exit_code": result.exit_code,
+        }
+        print(json.dumps(summary))
+        if renderer is not None:
+            try:
+                renderer.write_event(summary)
+                renderer.finalize()
+            except Exception as exc:
+                print(f"note: live log rendering disabled ({exc})", file=sys.stderr)
+        return result.exit_code
+    except (OSError, RuntimeError, UnicodeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pilot_workers/credentials.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""Store worker credentials in provider-isolated auth files."""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+import os
+import tempfile
+
+from pilot_workers.providers import PROVIDERS, workers_root
+from pilot_workers.runners import get_runner
+
+
+def credential_status(provider_key: str) -> dict[str, object]:
+    provider = PROVIDERS[provider_key]
+    runner = get_runner(provider.runner)
+    path = runner.credential_path(provider)
+    configured = False
+    secure_mode = False
+    error: str | None = None
+    if path.is_file():
+        secure_mode = (path.stat().st_mode & 0o077) == 0
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+            try:
+                key = runner.parse_credential(provider, payload)
+            except (RuntimeError, TypeError, AttributeError) as exc:
+                error = str(exc)
+                key = ""
+            configured = bool(key and key.strip())
+        except (OSError, json.JSONDecodeError) as exc:
+            error = str(exc)
+    return {
+        "provider": provider_key,
+        "runner": provider.runner,
+        "provider_id": provider.provider_id,
+        "configured": configured,
+        "secure_mode": secure_mode,
+        "path": str(path),
+        "error": error,
+    }
+
+
+def ensure_private_directories(destination) -> None:
+    current = workers_root()
+    target = destination.parent
+    while True:
+        current.mkdir(mode=0o700, parents=True, exist_ok=True)
+        current.chmod(0o700)
+        if current == target:
+            return
+        current = current / target.relative_to(current).parts[0]
+
+
+def configure(provider_key: str) -> None:
+    provider = PROVIDERS[provider_key]
+    runner = get_runner(provider.runner)
+    key = getpass.getpass(f"{provider_key} API key (input hidden): ").strip()
+    if not key:
+        raise SystemExit(f"error: empty {provider_key} API key; no file was changed")
+    destination = runner.credential_path(provider)
+    ensure_private_directories(destination)
+    payload = runner.credential_payload(provider, key)
+    temporary_name: str | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w", encoding="utf-8", dir=destination.parent,
+            prefix=".auth.", suffix=".tmp", delete=False,
+        ) as temporary:
+            temporary_name = temporary.name
+            os.chmod(temporary_name, 0o600)
+            json.dump(payload, temporary, separators=(",", ":"))
+            temporary.write("\n")
+            temporary.flush()
+            os.fsync(temporary.fileno())
+        os.replace(temporary_name, destination)
+        os.chmod(destination, 0o600)
+    finally:
+        key = ""
+        if temporary_name and os.path.exists(temporary_name):
+            os.unlink(temporary_name)
+    print(f"Configured {provider_key} in {destination} (mode 0600); key not displayed")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Configure isolated worker credentials.")
+    parser.add_argument("provider", choices=[*sorted(PROVIDERS), "all"])
+    parser.add_argument("--status", action="store_true", help="Show metadata only; never show keys.")
+    args = parser.parse_args()
+    keys = sorted(PROVIDERS) if args.provider == "all" else [args.provider]
+    if args.status:
+        print(json.dumps([credential_status(item) for item in keys], indent=2))
+        return 0
+    for provider_key in keys:
+        configure(provider_key)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())