orchestrator-runner 0.1.0__py3-none-any.whl

orchestrator_runner/__init__.py

@@ -0,0 +1,12 @@
+"""orchestrator-runner — the local runner for the SDD Orchestrator.
+
+Run your own LLM subscription (Claude / Codex / Gemini) from your own machine: pair once against your
+orchestrator deployment, then ``orchestrator-runner run`` leases generation (and, with ``--allow-build``,
+build) tasks and runs them on your local seat CLIs — your subscription login and your code never leave your
+computer. The server only ever receives generated text (or a patch it independently verifies).
+
+A standalone client with **no dependency on the (private) orchestrator server package** — pure stdlib, so it
+installs cleanly from PyPI with ``pipx install orchestrator-runner``.
+"""
+
+__version__ = "0.1.0"

orchestrator_runner/backends.py

@@ -0,0 +1,273 @@
+"""Model backends — the LLM/harness-agnostic seam.
+
+A backend turns ``(system, prompt)`` into text + real token usage. This protocol is where
+"LLM-agnostic, harness-agnostic, works with everyone's subscription" actually lives: swap the
+backend, the rest of the orchestrator is unchanged.
+
+Shipped here:
+- ``ClaudeCliBackend`` — shells to the ``claude`` CLI (uses the user's subscription, no API key),
+  the proven invocation the loop uses: ``claude -p --output-format json --model <id>`` with the
+  nested-session env markers stripped so the spawn runs at full strength.
+- ``FakeBackend`` — deterministic, for unit tests (a test double, not a product path).
+
+Next adapters plug in here with no other change: an Anthropic-API backend (SDK + key), OpenAI,
+or a local model (Ollama). That is the "primitives for everyone" promise, made concrete.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+
+class BackendError(RuntimeError):
+    """A backend failed to produce a generation (bad invocation, API error, timeout, no output)."""
+
+
+@dataclass(frozen=True, slots=True)
+class Generation:
+    """One model response with real usage (what the cost ledger and router training consume)."""
+
+    text: str
+    model: str
+    input_tokens: int
+    output_tokens: int
+    cost_usd: float | None = None
+    cache_read_tokens: int = 0  # prompt tokens served from cache (a cache hit)
+    cache_write_tokens: int = 0  # prompt tokens written to cache (a cache miss that populates it)
+
+
+@runtime_checkable
+class ModelBackend(Protocol):
+    name: str
+
+    def generate(self, *, system: str, prompt: str, model: str | None = None) -> Generation: ...
+
+
+def _clean_claude_env() -> dict[str, str]:
+    """``os.environ`` without Claude Code's own session markers. If the orchestrator runs inside a
+    Claude Code session, a nested ``claude -p`` that inherits ``CLAUDECODE`` / ``CLAUDE_CODE_*`` runs
+    in a degraded nested mode and under-drives the agent; stripping them makes it a top-level run."""
+    return {k: v for k, v in os.environ.items() if k != "CLAUDECODE" and not k.startswith("CLAUDE_CODE_")}
+
+
+class ClaudeCliBackend:
+    """Real backend over the ``claude`` CLI (subscription auth; no API key required)."""
+
+    name = "claude-cli"
+
+    def __init__(
+        self,
+        *,
+        runtime: str = "claude",
+        model: str | None = None,
+        timeout_s: int = 1200,
+        permission_mode: str | None = None,
+        cwd: str | None = None,
+    ) -> None:
+        self.runtime = runtime
+        self.model = model or os.environ.get("ORCHESTRATOR_MODEL", "claude-sonnet-5")
+        self.timeout_s = timeout_s
+        self.permission_mode = permission_mode
+        self.cwd = cwd
+
+    def generate(self, *, system: str, prompt: str, model: str | None = None) -> Generation:
+        chosen = model or self.model
+        full_prompt = f"{system}\n\n{prompt}" if system else prompt
+        argv = [self.runtime, "-p", "--output-format", "json", "--model", chosen]
+        if self.permission_mode:
+            argv += ["--permission-mode", self.permission_mode]
+        argv.append(full_prompt)
+        try:
+            proc = subprocess.run(
+                argv,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                check=False,
+                env=_clean_claude_env(),
+                cwd=self.cwd,
+                timeout=self.timeout_s,
+            )
+        except FileNotFoundError as exc:
+            raise BackendError(f"`{self.runtime}` not found on PATH") from exc
+        except subprocess.TimeoutExpired as exc:
+            raise BackendError(f"`{self.runtime}` timed out after {self.timeout_s}s") from exc
+
+        stdout = (proc.stdout or "").strip()
+        if not stdout:
+            raise BackendError((proc.stderr or "claude produced no output").strip()[:300])
+        try:
+            obj: dict[str, Any] = json.loads(stdout)
+        except (json.JSONDecodeError, ValueError) as exc:
+            raise BackendError(f"claude output was not JSON: {stdout[:200]}") from exc
+        if obj.get("is_error"):
+            raise BackendError(str(obj.get("result") or "claude reported an error")[:300])
+
+        usage = obj.get("usage") or {}
+        return Generation(
+            text=str(obj.get("result") or ""),
+            model=chosen,
+            input_tokens=int(usage.get("input_tokens", 0)),
+            output_tokens=int(usage.get("output_tokens", 0)),
+            cost_usd=_as_float(obj.get("total_cost_usd")),
+            cache_read_tokens=int(usage.get("cache_read_input_tokens", 0)),
+            cache_write_tokens=int(usage.get("cache_creation_input_tokens", 0)),
+        )
+
+
+def _run_cli(argv: list[str], *, timeout_s: int, cwd: str | None) -> subprocess.CompletedProcess[str]:
+    """Run a vendor agent CLI, mapping the two expected failures to a clear ``BackendError`` (fail-closed):
+    a missing binary (the CLI isn't installed where the backend runs) and a timeout."""
+    try:
+        return subprocess.run(
+            argv,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+            env=_clean_claude_env(),
+            cwd=cwd,
+            timeout=timeout_s,
+        )
+    except FileNotFoundError as exc:
+        raise BackendError(f"`{argv[0]}` not found on PATH") from exc
+    except subprocess.TimeoutExpired as exc:
+        raise BackendError(f"`{argv[0]}` timed out after {timeout_s}s") from exc
+
+
+def _int(value: Any) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return 0
+
+
+class CodexCliBackend:
+    """Real backend over the OpenAI ``codex`` CLI (ChatGPT subscription auth; no API key).
+
+    Runs ``codex exec`` read-only (no file edits) and takes the final agent message from stdout — the
+    documented non-interactive contract (progress goes to stderr, the result to stdout). ``codex``'s
+    ``--json`` event schema varies by version, so we read plain stdout and keep usage best-effort (0);
+    the subscription path is flat-billed, so precise token accounting is not needed here. ``runtime`` and
+    ``extra_args`` are overridable so a deployment/runner can match its installed CLI without a code change.
+    """
+
+    name = "codex-cli"
+
+    def __init__(
+        self,
+        *,
+        runtime: str = "codex",
+        model: str | None = None,
+        timeout_s: int = 1200,
+        cwd: str | None = None,
+        extra_args: tuple[str, ...] = (),
+    ) -> None:
+        self.runtime = runtime
+        self.model = model or os.environ.get("ORCHESTRATOR_CODEX_MODEL", "")
+        self.timeout_s = timeout_s
+        self.cwd = cwd
+        self.extra_args = tuple(extra_args)
+
+    def generate(self, *, system: str, prompt: str, model: str | None = None) -> Generation:
+        chosen = model or self.model
+        full_prompt = f"{system}\n\n{prompt}" if system else prompt
+        argv = [self.runtime, "exec", "--skip-git-repo-check"]
+        if chosen:
+            argv += ["--model", chosen]
+        argv += [*self.extra_args, full_prompt]
+        proc = _run_cli(argv, timeout_s=self.timeout_s, cwd=self.cwd)
+        text = (proc.stdout or "").strip()
+        if not text:
+            raise BackendError((proc.stderr or "codex produced no output").strip()[:300])
+        return Generation(text=text, model=chosen or "codex", input_tokens=0, output_tokens=0)
+
+
+class GeminiCliBackend:
+    """Real backend over the Google ``gemini`` CLI (Google-account/subscription auth; no API key).
+
+    Runs headless with ``--output-format json`` and parses the single result object (``response`` +
+    usage stats), falling back to raw stdout when the output is not JSON — the CLI's flags/schema vary by
+    version, so parsing is tolerant and never hard-fails on a schema change. ``runtime`` is overridable so
+    a runner can match its installed CLI.
+    """
+
+    name = "gemini-cli"
+
+    def __init__(
+        self,
+        *,
+        runtime: str = "gemini",
+        model: str | None = None,
+        timeout_s: int = 1200,
+        cwd: str | None = None,
+    ) -> None:
+        self.runtime = runtime
+        self.model = model or os.environ.get("ORCHESTRATOR_GEMINI_MODEL", "")
+        self.timeout_s = timeout_s
+        self.cwd = cwd
+
+    def generate(self, *, system: str, prompt: str, model: str | None = None) -> Generation:
+        chosen = model or self.model
+        full_prompt = f"{system}\n\n{prompt}" if system else prompt
+        argv = [self.runtime, "--output-format", "json"]
+        if chosen:
+            argv += ["--model", chosen]
+        argv += ["-p", full_prompt]
+        proc = _run_cli(argv, timeout_s=self.timeout_s, cwd=self.cwd)
+        stdout = (proc.stdout or "").strip()
+        text = ""
+        in_tok = out_tok = 0
+        if stdout:
+            try:
+                obj: Any = json.loads(stdout)
+            except (json.JSONDecodeError, ValueError):
+                obj = None
+            if isinstance(obj, dict):
+                if obj.get("error"):
+                    raise BackendError(str(obj.get("error"))[:300])
+                text = str(obj.get("response") or obj.get("text") or "")
+                stats = obj.get("stats") or obj.get("usage") or {}
+                if isinstance(stats, dict):
+                    in_tok = _int(stats.get("input_tokens") or stats.get("promptTokenCount"))
+                    out_tok = _int(stats.get("output_tokens") or stats.get("candidatesTokenCount"))
+            else:
+                text = stdout  # not JSON (older/text mode) -> treat raw stdout as the completion
+        if not text:
+            raise BackendError((proc.stderr or "gemini produced no output").strip()[:300])
+        return Generation(text=text, model=chosen or "gemini", input_tokens=in_tok, output_tokens=out_tok)
+
+
+def _as_float(value: Any) -> float | None:
+    return float(value) if isinstance(value, int | float) else None
+
+
+class FakeBackend:
+    """Deterministic backend for unit tests. Records the last call so tests can assert the prompt
+    was built correctly. Not a product path — real runs use a live backend."""
+
+    name = "fake"
+
+    def __init__(self, reply: str = "# Draft\n\nGenerated by the fake backend.\n") -> None:
+        self.reply = reply
+        self.last_system = ""
+        self.last_prompt = ""
+        self.calls = 0
+
+    def generate(self, *, system: str, prompt: str, model: str | None = None) -> Generation:
+        self.last_system = system
+        self.last_prompt = prompt
+        self.calls += 1
+        return Generation(
+            text=self.reply,
+            model=model or "fake/deterministic",
+            input_tokens=len(prompt.split()),
+            output_tokens=len(self.reply.split()),
+            cost_usd=0.0,
+        )

orchestrator_runner/cli.py

@@ -0,0 +1,352 @@
+"""``orchestrator-runner`` — connect a local runner so your own LLM subscription powers your work.
+
+Commands:
+- ``pair --url <site> --code <code>`` — exchange a one-time pairing code (from the UI) for a runner
+  credential, saved locally (0600). Reports which provider CLIs (claude/codex/gemini) are present.
+- ``run`` — poll for tasks and run them on the local seat CLIs: generation (2b) and, when paired with
+  ``--allow-build``, builds (2c — clone, run the coding agent, return a patch the server verifies).
+- ``whoami`` — verify the stored credential against the server.
+
+This runs on the user's machine; the provider seat logins never leave it.
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import json
+import os
+import shutil
+import sys
+import tempfile
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from orchestrator_runner.backends import (
+    ClaudeCliBackend,
+    CodexCliBackend,
+    GeminiCliBackend,
+    ModelBackend,
+)
+from orchestrator_runner.coding import (
+    ImplementationBrief,
+    agent_available,
+    agent_spec,
+    run_coding_agent,
+)
+from orchestrator_runner.command import LocalCommandRunner
+
+CONFIG_PATH = Path.home() / ".orchestrator-runner" / "config.json"
+
+# provider -> the seat CLI that serves it (presence here = a subscription this runner can run)
+_PROVIDER_CLIS = {"anthropic": "claude", "openai": "codex", "google": "gemini"}
+
+
+def detect_capabilities(*, allow_build: bool = False) -> dict[str, Any]:
+    """Which provider seat CLIs are installed on this machine (presence only — login is checked at run time),
+    plus whether this runner may BUILD — an explicit opt-in (``--allow-build``) AND git present, since a
+    build runs agent-written code + tests on this machine."""
+    providers = [name for name, cli in _PROVIDER_CLIS.items() if shutil.which(cli)]
+    return {"providers": providers, "build": bool(allow_build and shutil.which("git"))}
+
+
+def _request(
+    url: str, *, method: str, payload: dict[str, Any] | None = None, token: str = ""
+) -> dict[str, Any]:
+    data = json.dumps(payload).encode("utf-8") if payload is not None else None
+    req = urllib.request.Request(url, data=data, method=method)
+    if payload is not None:
+        req.add_header("Content-Type", "application/json")
+    if token:
+        req.add_header("Authorization", f"Bearer {token}")
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        obj: Any = json.loads(resp.read().decode("utf-8"))
+    if not isinstance(obj, dict):
+        raise ValueError("expected a JSON object from the server")
+    return obj
+
+
+def _save_config(cfg: dict[str, Any]) -> None:
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CONFIG_PATH.write_text(json.dumps(cfg, indent=2), encoding="utf-8")
+    with contextlib.suppress(OSError):
+        CONFIG_PATH.chmod(0o600)
+
+
+def _load_config() -> dict[str, Any]:
+    try:
+        obj: Any = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return obj if isinstance(obj, dict) else {}
+
+
+def cmd_pair(args: argparse.Namespace) -> int:
+    url = str(args.url).rstrip("/")
+    caps = detect_capabilities(allow_build=bool(args.allow_build))
+    try:
+        result = _request(
+            f"{url}/runners/pair",
+            method="POST",
+            payload={"code": str(args.code), "name": str(args.name), "capabilities": caps},
+        )
+    except urllib.error.HTTPError as exc:
+        sys.stderr.write(f"pairing failed: {exc.code} {exc.read().decode('utf-8', 'replace')}\n")
+        return 1
+    except urllib.error.URLError as exc:
+        sys.stderr.write(f"could not reach {url}: {exc}\n")
+        return 1
+    _save_config(
+        {
+            "url": url,
+            "token": result["token"],
+            "runner_id": result["runner_id"],
+            "user_id": result["user_id"],
+        }
+    )
+    print(f"paired: runner {result['runner_id']} for user {result['user_id']}")
+    print(f"capabilities: providers={caps['providers']} build={caps['build']}")
+    if not caps["providers"]:
+        print(
+            "warning: no provider CLI (claude/codex/gemini) found on PATH — this runner can't serve a "
+            "subscription yet. Install and log into at least one."
+        )
+    print(f"credential saved to {CONFIG_PATH}")
+    return 0
+
+
+def cmd_whoami(_args: argparse.Namespace) -> int:
+    cfg = _load_config()
+    if not cfg.get("token"):
+        sys.stderr.write("not paired — run `orchestrator-runner pair --url <site> --code <code>`\n")
+        return 1
+    try:
+        me = _request(f"{str(cfg['url']).rstrip('/')}/runners/me", method="GET", token=str(cfg["token"]))
+    except urllib.error.HTTPError as exc:
+        sys.stderr.write(f"credential rejected: {exc.code} (revoked? re-pair)\n")
+        return 1
+    except urllib.error.URLError as exc:
+        sys.stderr.write(f"could not reach {cfg.get('url')}: {exc}\n")
+        return 1
+    print(f"runner {me['runner_id']} for user {me['user_id']} — capabilities {me.get('capabilities')}")
+    return 0
+
+
+_BACKEND_BUILDERS: dict[str, Callable[[str | None], ModelBackend]] = {
+    "anthropic": lambda model: ClaudeCliBackend(model=model),
+    "openai": lambda model: CodexCliBackend(model=model),
+    "google": lambda model: GeminiCliBackend(model=model),
+}
+
+
+def _local_backends() -> dict[str, ModelBackend]:
+    """The seat-CLI backends installed on this machine, by provider (only CLIs actually on PATH)."""
+    out: dict[str, ModelBackend] = {}
+    for provider, cli in _PROVIDER_CLIS.items():
+        if shutil.which(cli):
+            out[provider] = _BACKEND_BUILDERS[provider](None)
+    return out
+
+
+def _post_fail(url: str, token: str, task_id: str, detail: str) -> None:
+    with contextlib.suppress(urllib.error.HTTPError, urllib.error.URLError):
+        _request(
+            f"{url}/runners/tasks/{task_id}/fail", method="POST", payload={"detail": detail}, token=token
+        )
+
+
+def _run_one(task: dict[str, Any], backends: dict[str, ModelBackend], url: str, token: str) -> None:
+    task_id = str(task.get("task_id", ""))
+    provider = str(task.get("provider", ""))
+    backend = backends.get(provider)
+    if backend is None:
+        _post_fail(url, token, task_id, f"runner has no local backend for provider {provider!r}")
+        return
+    try:
+        gen = backend.generate(
+            system=str(task.get("system", "")),
+            prompt=str(task.get("prompt", "")),
+            model=(str(task["model"]) if task.get("model") else None),
+        )
+    except Exception as exc:  # a failed generation (CLI missing/unauth'd, timeout) -> report, stay alive
+        _post_fail(url, token, task_id, str(exc)[:500])
+        return
+    try:
+        _request(
+            f"{url}/runners/tasks/{task_id}/result",
+            method="POST",
+            payload={
+                "text": gen.text,
+                "input_tokens": gen.input_tokens,
+                "output_tokens": gen.output_tokens,
+                "model": gen.model,
+            },
+            token=token,
+        )
+        print(f"task {task_id}: done ({gen.output_tokens} output tokens)")
+    except (urllib.error.HTTPError, urllib.error.URLError) as exc:
+        sys.stderr.write(f"task {task_id}: could not post result: {exc}\n")
+
+
+def _post_build_result(
+    url: str, token: str, task_id: str, *, ok: bool, patch: str, changed_files: list[str], detail: str
+) -> None:
+    with contextlib.suppress(urllib.error.HTTPError, urllib.error.URLError):
+        _request(
+            f"{url}/runners/tasks/{task_id}/build-result",
+            method="POST",
+            payload={"ok": ok, "patch": patch, "changed_files": changed_files, "detail": detail},
+            token=token,
+        )
+
+
+def _run_build(task: dict[str, Any], url: str, token: str) -> None:
+    """Clone the repo (read-only, this machine's git), run the coding agent on the seat, return a PATCH.
+    The server applies + authoritatively verifies it — this runner never pushes."""
+    task_id = str(task.get("task_id", ""))
+    runtime = str(task.get("runtime") or "claude-code")
+    spec = agent_spec(runtime)
+    if spec is None:
+        _post_build_result(
+            url, token, task_id, ok=False, patch="", changed_files=[], detail=f"unknown runtime {runtime!r}"
+        )
+        return
+    cmd = LocalCommandRunner()
+    repo_url = str(task.get("repo_url", ""))
+    base = str(task.get("base_branch") or "main")
+    with tempfile.TemporaryDirectory(prefix="orch-runner-build-") as tmp:
+        clone_dir = os.path.join(tmp, "repo")
+        cloned = cmd.run(
+            ["git", "clone", "--depth", "1", "--branch", base, repo_url, clone_dir], timeout_s=600
+        )
+        if cloned.returncode != 0:
+            _post_build_result(
+                url,
+                token,
+                task_id,
+                ok=False,
+                patch="",
+                changed_files=[],
+                detail=f"clone failed: {cloned.stderr[:300]}",
+            )
+            return
+        if not agent_available(spec, cmd, cwd=clone_dir):
+            _post_build_result(
+                url,
+                token,
+                task_id,
+                ok=False,
+                patch="",
+                changed_files=[],
+                detail=f"{spec.name} CLI not available/logged in on this runner",
+            )
+            return
+        brief = ImplementationBrief(
+            goal=str(task.get("goal", "")),
+            plan=str(task.get("plan", "")),
+            specs=tuple(str(s) for s in (task.get("specs") or [])),
+        )
+        result = run_coding_agent(spec, prompt=brief.to_prompt(), cwd=clone_dir, runner=cmd, timeout_s=3600)
+        if not result.ok:
+            _post_build_result(
+                url,
+                token,
+                task_id,
+                ok=False,
+                patch="",
+                changed_files=list(result.changed_files),
+                detail=f"{spec.name}: {result.detail}",
+            )
+            return
+        cmd.run(["git", "add", "-A"], cwd=clone_dir, timeout_s=120)
+        diff = cmd.run(["git", "diff", "--cached"], cwd=clone_dir, timeout_s=120)
+        _post_build_result(
+            url,
+            token,
+            task_id,
+            ok=True,
+            patch=diff.stdout,
+            changed_files=list(result.changed_files),
+            detail="",
+        )
+        print(f"build task {task_id}: done ({len(result.changed_files)} files)")
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    cfg = _load_config()
+    if not cfg.get("token"):
+        sys.stderr.write("not paired — run `orchestrator-runner pair --url <site> --code <code>`\n")
+        return 1
+    url = str(cfg["url"]).rstrip("/")
+    token = str(cfg["token"])
+    backends = _local_backends()
+    if not backends:
+        sys.stderr.write("no provider CLI (claude/codex/gemini) on PATH — install and log into one\n")
+        return 1
+    poll = float(args.poll)
+    once = bool(args.once)
+    print(f"runner online for {sorted(backends)} — polling {url} every {poll}s (Ctrl-C to stop)")
+    while True:
+        try:
+            resp = _request(f"{url}/runners/tasks", method="GET", token=token)
+        except urllib.error.HTTPError as exc:
+            if exc.code == 401:
+                sys.stderr.write("credential rejected (revoked?) — re-pair\n")
+                return 1
+            sys.stderr.write(f"poll error: {exc.code}\n")
+            resp = {}
+        except urllib.error.URLError as exc:
+            sys.stderr.write(f"could not reach {url}: {exc}\n")
+            if once:
+                return 1
+            time.sleep(poll)
+            continue
+        task = resp.get("task")
+        if task:
+            if str(task.get("kind")) == "build":
+                _run_build(task, url, token)
+            else:
+                _run_one(task, backends, url, token)
+        if once:
+            return 0
+        if not task:
+            time.sleep(poll)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="orchestrator-runner",
+        description="Connect a local runner so your own LLM subscription powers your orchestrator work.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_pair = sub.add_parser("pair", help="exchange a one-time pairing code for a runner credential")
+    p_pair.add_argument("--url", required=True, help="the orchestrator site, e.g. https://host")
+    p_pair.add_argument("--code", required=True, help="the one-time pairing code shown in the UI")
+    p_pair.add_argument("--name", default="", help="a name for this runner (optional)")
+    p_pair.add_argument(
+        "--allow-build",
+        action="store_true",
+        help="let this runner BUILD (run agent-written code + tests on this machine), not just generate",
+    )
+    p_pair.set_defaults(func=cmd_pair)
+
+    p_run = sub.add_parser("run", help="run queued generation tasks on this machine's seat CLIs")
+    p_run.add_argument("--poll", type=float, default=3.0, help="seconds between polls when idle")
+    p_run.add_argument("--once", action="store_true", help="handle at most one poll cycle, then exit")
+    p_run.set_defaults(func=cmd_run)
+
+    p_who = sub.add_parser("whoami", help="verify the stored runner credential against the server")
+    p_who.set_defaults(func=cmd_whoami)
+
+    args = parser.parse_args(argv)
+    func: Any = args.func
+    return int(func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

orchestrator_runner/coding.py

@@ -0,0 +1,199 @@
+"""Third-party coding agents — run an EXTERNAL agent CLI (Claude Code, Codex, Kiro) as the implementer.
+
+The orchestrator's own builder is a TDD cohort loop over a model backend. Some teams would rather drive the
+implementation with a full coding agent they already use. This module makes that a drop-in: a
+:class:`CodingAgentSpec` describes how to invoke one as a non-interactive CLI, and :func:`run_coding_agent`
+runs it IN THE RUN SANDBOX (through the same ``CommandRunner`` the verification ladder uses), so the agent
+edits the run's worktree and the SAME gates + verification ladder + dual review then judge its output — the
+agent is swappable, the governance around it is not.
+
+Execution needs the chosen CLI present in the run's devbox (like the Docker/K8s sandbox backends, it is
+infra-gated): :func:`agent_available` probes for it and the external path fails CLOSED with a clear message
+when it is missing, so a run never silently falls back to something the operator did not choose.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from orchestrator_runner.command import CommandRunner
+
+# the default: the orchestrator's own TDD cohort loop (no external CLI). Selecting this is "no third party".
+BUILTIN_RUNTIME = "builtin"
+
+
+@dataclass(frozen=True, slots=True)
+class CodingAgentSpec:
+    """How to invoke one external coding agent as a non-interactive CLI. ``prefix`` is the fixed argv; the
+    task prompt is appended as a single final argument. ``version_argv`` is the availability probe."""
+
+    id: str
+    name: str
+    prefix: tuple[str, ...]
+    version_argv: tuple[str, ...]
+    description: str = ""
+
+    def command(self, prompt: str) -> list[str]:
+        """The full argv to run ``prompt`` — the prompt is one argument, never shell-interpolated."""
+        return [*self.prefix, prompt]
+
+
+# The built-in catalog. Each entry is the documented non-interactive invocation of a real agent CLI; the
+# exact flags can be tuned per deployment. These run only where the CLI is installed in the devbox.
+BUILTIN_AGENTS: tuple[CodingAgentSpec, ...] = (
+    CodingAgentSpec(
+        id="claude-code",
+        name="Claude Code",
+        prefix=("claude", "-p"),  # -p = print/non-interactive: run the prompt headless and exit
+        version_argv=("claude", "--version"),
+        description="Anthropic's Claude Code CLI, run headless over the run's worktree.",
+    ),
+    CodingAgentSpec(
+        id="codex",
+        name="OpenAI Codex",
+        prefix=("codex", "exec"),  # exec = non-interactive one-shot
+        version_argv=("codex", "--version"),
+        description="OpenAI's Codex CLI, run non-interactively over the run's worktree.",
+    ),
+    CodingAgentSpec(
+        id="kiro",
+        name="Kiro",
+        prefix=("kiro", "run", "--prompt"),
+        version_argv=("kiro", "--version"),
+        description="AWS Kiro agent CLI, run over the run's worktree.",
+    ),
+)
+
+_BY_ID: dict[str, CodingAgentSpec] = {a.id: a for a in BUILTIN_AGENTS}
+
+
+def agent_spec(runtime_id: str) -> CodingAgentSpec | None:
+    """The spec for an external runtime id, or None (``builtin`` / unknown has no external CLI)."""
+    return _BY_ID.get(runtime_id)
+
+
+def is_external(runtime_id: str) -> bool:
+    return runtime_id in _BY_ID
+
+
+def list_runtimes() -> list[dict[str, str]]:
+    """The selectable implementation runtimes: the built-in loop + every external agent (id + name)."""
+    out = [
+        {
+            "id": BUILTIN_RUNTIME,
+            "name": "Built-in (TDD loop)",
+            "description": "The orchestrator's own builder.",
+        }
+    ]
+    out += [{"id": a.id, "name": a.name, "description": a.description} for a in BUILTIN_AGENTS]
+    return out
+
+
+@dataclass(frozen=True, slots=True)
+class CodingAgentResult:
+    ok: bool
+    runtime: str
+    exit_code: int
+    changed_files: tuple[str, ...] = ()
+    output_tail: str = ""
+    detail: str = ""
+
+
+def agent_available(spec: CodingAgentSpec, runner: CommandRunner, *, cwd: str | Path | None = None) -> bool:
+    """Whether the agent's CLI is runnable in the sandbox (the version probe exits 0). Fail-closed: a missing
+    binary (FileNotFoundError), a timeout, or a non-zero exit all mean 'not available'."""
+    try:
+        res = runner.run(list(spec.version_argv), cwd=cwd, timeout_s=30)
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return False
+    return res.returncode == 0
+
+
+def _changed_files(runner: CommandRunner, cwd: str | Path) -> tuple[str, ...]:
+    """Files the agent created/modified, via ``git status --porcelain`` in the worktree (best-effort)."""
+    try:
+        res = runner.run(["git", "status", "--porcelain"], cwd=cwd, timeout_s=60)
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return ()
+    if res.returncode != 0:
+        return ()
+    files: list[str] = []
+    for line in res.stdout.splitlines():
+        path = line[3:].strip() if len(line) > 3 else line.strip()
+        if path:
+            files.append(path)
+    return tuple(files)
+
+
+def run_coding_agent(
+    spec: CodingAgentSpec,
+    *,
+    prompt: str,
+    cwd: str | Path,
+    runner: CommandRunner,
+    timeout_s: int = 1800,
+    env: Mapping[str, str] | None = None,
+) -> CodingAgentResult:
+    """Run the external agent over the worktree at ``cwd`` with ``prompt``, then report what it changed.
+
+    Fail-closed: a missing CLI (FileNotFoundError) or a timeout returns ``ok=False`` with a clear reason
+    rather than raising, so the executor can surface it as a run failure the operator can act on."""
+    argv = spec.command(prompt)
+    try:
+        res = runner.run(argv, cwd=cwd, timeout_s=timeout_s, env=env)
+    except FileNotFoundError:
+        return CodingAgentResult(
+            ok=False,
+            runtime=spec.id,
+            exit_code=127,
+            detail=f"{spec.name} CLI ({spec.prefix[0]!r}) is not installed in this run's devbox",
+        )
+    except subprocess.TimeoutExpired:
+        return CodingAgentResult(
+            ok=False, runtime=spec.id, exit_code=124, detail=f"{spec.name} timed out after {timeout_s}s"
+        )
+    changed = _changed_files(runner, cwd)
+    output = f"{res.stdout}\n{res.stderr}".strip()
+    tail = "\n".join(output.splitlines()[-20:])
+    ok = res.returncode == 0 and bool(changed)
+    detail = ""
+    if res.returncode != 0:
+        detail = f"{spec.name} exited {res.returncode}"
+    elif not changed:
+        detail = f"{spec.name} made no file changes"
+    return CodingAgentResult(
+        ok=ok,
+        runtime=spec.id,
+        exit_code=res.returncode,
+        changed_files=changed,
+        output_tail=tail,
+        detail=detail,
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class ImplementationBrief:
+    """What an external agent is told to build — assembled from the approved product + engineering tiers."""
+
+    goal: str
+    plan: str = ""
+    specs: tuple[str, ...] = field(default_factory=tuple)
+
+    def to_prompt(self) -> str:
+        parts = [
+            "Implement the following feature in this repository. Make the changes directly in the working "
+            "tree; write real, tested, production-quality code that satisfies the specification and plan.",
+            f"\n## Goal\n{self.goal}",
+        ]
+        if self.plan:
+            parts.append(f"\n## Engineering plan\n{self.plan}")
+        for i, spec in enumerate(self.specs, 1):
+            parts.append(f"\n## Specification {i}\n{spec}")
+        parts.append(
+            "\nWhen done, ensure the code lints, type-checks, and its tests pass. Do not open a pull "
+            "request — the orchestrator handles delivery after its own review."
+        )
+        return "\n".join(parts)

orchestrator_runner/command.py

@@ -0,0 +1,97 @@
+"""The command-execution seam — how a run's build/verify commands actually run.
+
+The verification ladder (and anything else that shells out during a run) executes commands through a
+``CommandRunner`` instead of calling ``subprocess`` directly. The default ``LocalCommandRunner`` runs them
+as subprocesses on the host — exactly today's behavior. A containerized runner is a drop-in behind the same
+port (the per-run sandbox), so a run's lint/typecheck/tests can run inside an isolated devbox without
+touching the ladder or the executor above it — the same agnostic-seam pattern as the model backends and the
+filesystem ``Sandbox``.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+
+@dataclass(frozen=True, slots=True)
+class CommandResult:
+    """The outcome of one command: its exit code and captured output."""
+
+    returncode: int
+    stdout: str
+    stderr: str
+
+
+@runtime_checkable
+class CommandRunner(Protocol):
+    """Runs one command and returns its result.
+
+    Implementations run it wherever isolation requires — on the host (local) or inside a per-run container
+    (sandbox). ``run`` may raise ``FileNotFoundError`` (the executable is not present) or
+    ``subprocess.TimeoutExpired`` (it exceeded ``timeout_s``); callers that must fail closed catch those
+    (the verification ladder does). ``env`` is ADDITIVE — the given vars are added to (not a replacement of)
+    the ambient environment, so a run's per-project secrets layer on top of the toolchain's own PATH/env;
+    ``None`` means no additions.
+    """
+
+    def run(
+        self,
+        argv: Sequence[str],
+        *,
+        cwd: str | Path | None = None,
+        timeout_s: int = 300,
+        env: Mapping[str, str] | None = None,
+    ) -> CommandResult: ...
+
+
+class LocalCommandRunner:
+    """Runs commands as subprocesses on the local host — the default, today's behavior."""
+
+    def run(
+        self,
+        argv: Sequence[str],
+        *,
+        cwd: str | Path | None = None,
+        timeout_s: int = 300,
+        env: Mapping[str, str] | None = None,
+    ) -> CommandResult:
+        proc = subprocess.run(
+            list(argv),
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            cwd=cwd,
+            # additive: merge onto the ambient env so PATH/etc survive; a bare replacement would strip them
+            env={**os.environ, **env} if env is not None else None,
+            timeout=timeout_s,
+            check=False,
+        )
+        return CommandResult(proc.returncode, proc.stdout, proc.stderr)
+
+
+@dataclass(frozen=True, slots=True)
+class ScopedEnvRunner:
+    """Wraps a ``CommandRunner`` to inject a fixed base environment into EVERY command it runs — a run's
+    per-project secrets, applied to each build/verify step. A per-call ``env`` overrides the base key-wise.
+    The base is additive wherever the inner runner is (the local runner merges onto the host env; the
+    container runner adds ``-e`` flags), so the toolchain's own environment is preserved."""
+
+    inner: CommandRunner
+    base_env: Mapping[str, str]
+
+    def run(
+        self,
+        argv: Sequence[str],
+        *,
+        cwd: str | Path | None = None,
+        timeout_s: int = 300,
+        env: Mapping[str, str] | None = None,
+    ) -> CommandResult:
+        merged = {**self.base_env, **(env or {})}
+        return self.inner.run(argv, cwd=cwd, timeout_s=timeout_s, env=merged or None)

orchestrator_runner-0.1.0.dist-info/METADATA

@@ -0,0 +1,69 @@
+Metadata-Version: 2.5
+Name: orchestrator-runner
+Version: 0.1.0
+Summary: Local runner for the SDD Orchestrator — run your own LLM subscription (Claude/Codex/Gemini) from your machine.
+Project-URL: Homepage, https://github.com/Aitrich-AI-Dev-Platform/sdd-orchestrator
+Project-URL: Repository, https://github.com/Aitrich-AI-Dev-Platform/sdd-orchestrator
+Project-URL: Issues, https://github.com/Aitrich-AI-Dev-Platform/sdd-orchestrator/issues
+Author: BizEnrich
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# orchestrator-runner
+
+The **local runner** for the SDD Orchestrator. It lets you run your **own LLM subscription**
+(Claude / Codex / Gemini) from **your own machine** — your subscription login and your code never leave your
+computer. The orchestrator server only ever receives the generated text, or (for builds) a patch it
+independently verifies.
+
+It's a standalone client: pure Python stdlib, **no dependency on the orchestrator server**.
+
+## Install
+
+```bash
+pipx install orchestrator-runner
+```
+
+You also need, on this machine:
+
+- The provider's own CLI, installed **and logged in** — `claude` (Pro/Max), `codex` (Sign-in-with-ChatGPT),
+  or `gemini` (Google). The runner only serves providers whose CLI is present.
+- `git`, if you want this runner to also **build** (`--allow-build`).
+
+## Use
+
+1. In the orchestrator web app: **Integrations → Local runners → Pair a new runner** (gives a one-time code,
+   valid ~10 minutes).
+2. On this machine, in a terminal:
+
+   ```bash
+   orchestrator-runner pair --url https://<your-orchestrator-site> --code <code>   # one-time
+   # add --allow-build to also run builds here (runs agent-written code + tests on this machine)
+   orchestrator-runner run
+   ```
+
+   Keep `run` going while your projects work. Closing it takes your runner offline; subscription-backed
+   stages then pause until you start it again.
+
+3. `orchestrator-runner whoami` verifies the stored credential.
+
+The credential is saved to `~/.orchestrator-runner/config.json` (mode 0600). Revoke a runner any time from
+the web app.
+
+## Security
+
+- Your provider **seat login** stays in your provider CLI on this machine — the server stores only a
+  revocable runner credential (its hash).
+- For builds, the runner clones **read-only** with your own git and returns a **patch**; it never pushes.
+  The server applies the patch and runs the authoritative verification + review + delivery.

orchestrator_runner-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+orchestrator_runner/__init__.py,sha256=MhtNAshigASkEQiKQ_YOKzUZJaNVsfPL_82fS24THeg,693
+orchestrator_runner/backends.py,sha256=89dxBl3B1wd_p4YzVJEq-6PTZdezmraShoy9L9XaIiw,10934
+orchestrator_runner/cli.py,sha256=AkEs-WTiL1JnF6YaiYYrLJ0DTR4qDUKygbnt1y4zwGw,13600
+orchestrator_runner/coding.py,sha256=EhtPuRWt3lJknLt2-XpgVVApuUPkubnWjSoz-i9ivaY,7761
+orchestrator_runner/command.py,sha256=KWPxsmP7C6AAh9K8sJkwWJypHQp6QETmvJqACSc07yM,3623
+orchestrator_runner-0.1.0.dist-info/METADATA,sha256=HX2suJXQhmgvCiNes3L5FYzaLDgULljeweoqhqmLr64,2903
+orchestrator_runner-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+orchestrator_runner-0.1.0.dist-info/entry_points.txt,sha256=AeJSVDc6nRVSMRW--Sy5X_iZ0ybveth0ItxV0zv-2cc,69
+orchestrator_runner-0.1.0.dist-info/licenses/LICENSE,sha256=Qe5w6IDSIaCw-M5xRaU_xWuzBhGuXrVnJgtyTmOLxLg,1066
+orchestrator_runner-0.1.0.dist-info/RECORD,,

orchestrator_runner-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

orchestrator_runner-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+orchestrator-runner = orchestrator_runner.cli:main

orchestrator_runner-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BizEnrich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.