sdxloop 0.1.0__py3-none-any.whl

sdxloop/__init__.py

@@ -0,0 +1,26 @@
+"""sdxloop — agentic loop orchestration on Docker Sandboxes (sbx).
+
+Every sdxloop operation runs as a pair of isolated microVM sandboxes: an agent
+sandbox holding only ``COPILOT_GITHUB_TOKEN`` for the GitHub Copilot SDK
+agentic layer, and a GitHub-ops sandbox holding only ``GH_TOKEN`` for
+user-facing GitHub interactions. The balanced network policy is the default.
+"""
+
+__version__ = "0.1.0"
+
+from sdxloop.config import Budgets, Config, load_config
+from sdxloop.engine import LoopEngine, RunResult, run_outcome
+from sdxloop.events import Event, EventBus, Hook
+
+__all__ = [
+    "Budgets",
+    "Config",
+    "Event",
+    "EventBus",
+    "Hook",
+    "LoopEngine",
+    "RunResult",
+    "__version__",
+    "load_config",
+    "run_outcome",
+]

sdxloop/cli/__init__.py

@@ -0,0 +1 @@
+"""The sdxloop command-line interface."""

sdxloop/cli/app.py

@@ -0,0 +1,359 @@
+"""The sdxloop CLI: run agentic loops on Docker Sandboxes."""
+
+from __future__ import annotations
+
+import threading
+import time
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+from rich.live import Live
+from rich.table import Table
+
+import sdxloop
+from sdxloop.cli.doctor import run_doctor
+from sdxloop.cli.tui import Dashboard, format_event, plain_printer
+from sdxloop.config import Config, load_config, load_config_with_sources
+from sdxloop.engine.engine import LoopEngine
+from sdxloop.engine.model import RunResult
+from sdxloop.engine.store import StateStore
+from sdxloop.errors import SdxloopError
+from sdxloop.sbx.cli import SbxCLI
+from sdxloop.sbx.provision import sandbox_name
+
+app = typer.Typer(
+    name="sdxloop",
+    help="Agentic loop orchestration on Docker Sandboxes with isolated credentials.",
+    no_args_is_help=True,
+    pretty_exceptions_show_locals=False,
+)
+sandbox_app = typer.Typer(help="Manage sdxloop sandboxes.", no_args_is_help=True)
+config_app = typer.Typer(help="Inspect configuration.", no_args_is_help=True)
+app.add_typer(sandbox_app, name="sandbox")
+app.add_typer(config_app, name="config")
+
+console = Console()
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"sdxloop {sdxloop.__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _main_callback(
+    version: Annotated[
+        bool, typer.Option("--version", callback=_version_callback, is_eager=True)
+    ] = False,
+) -> None:
+    """sdxloop — agentic loops on Docker Sandboxes."""
+
+
+def _config_with_overrides(**overrides: Any) -> Config:
+    config = load_config()
+    updates = {k: v for k, v in overrides.items() if v is not None}
+    return config.model_copy(update=updates) if updates else config
+
+
+def _store(config: Config) -> StateStore:
+    return StateStore(config.state_dir / "state.db")
+
+
+def _drive_with_ui(engine: LoopEngine, *, tui: bool, action: Any) -> RunResult:
+    """Run start/resume with either the live dashboard or plain event logs."""
+    if not tui:
+        engine.bus.subscribe(plain_printer(console))
+        return action()  # type: ignore[no-any-return]
+
+    dashboard = Dashboard()
+    engine.bus.subscribe(dashboard.on_event)
+    outcome: dict[str, Any] = {}
+
+    def target() -> None:
+        try:
+            outcome["result"] = action()
+        except BaseException as exc:
+            outcome["error"] = exc
+
+    thread = threading.Thread(target=target, daemon=True)
+    with Live(dashboard.renderable(), console=console, refresh_per_second=8) as live:
+        thread.start()
+        while thread.is_alive():
+            live.update(dashboard.renderable())
+            time.sleep(0.15)
+        live.update(dashboard.renderable())
+    if "error" in outcome:
+        raise outcome["error"]
+    return outcome["result"]  # type: ignore[no-any-return]
+
+
+def _finish(result: RunResult) -> None:
+    style = "green" if result.succeeded else "red"
+    console.print(f"\nrun [bold cyan]{result.run_id}[/] finished: [bold {style}]{result.state}[/]")
+    for task in result.tasks:
+        console.print(f"  {task.spec.id}: {task.state}  ({task.spec.title})")
+    raise typer.Exit(0 if result.succeeded else 1)
+
+
+@app.command()
+def run(
+    outcome: Annotated[str, typer.Argument(help="The outcome to achieve.")],
+    repo: Annotated[
+        str | None, typer.Option("--repo", help="owner/repo for GitHub progress reporting.")
+    ] = None,
+    model: Annotated[str | None, typer.Option("--model", help="Copilot model id.")] = None,
+    keep_sandboxes: Annotated[
+        bool, typer.Option("--keep-sandboxes", help="Do not remove sandboxes at the end.")
+    ] = False,
+    tui: Annotated[bool, typer.Option("--tui/--no-tui", help="Live dashboard.")] = True,
+) -> None:
+    """Run an agentic loop for OUTCOME in a fresh sandbox pair."""
+    config = _config_with_overrides(model=model, keep_sandboxes=keep_sandboxes or None)
+    if repo:
+        config = config.model_copy(
+            update={"github": config.github.model_copy(update={"report_repo": repo})}
+        )
+    engine = LoopEngine(config)
+    try:
+        result = _drive_with_ui(engine, tui=tui, action=lambda: engine.start(outcome))
+    except SdxloopError as exc:
+        console.print(f"[bold red]run failed:[/] {exc}")
+        raise typer.Exit(2) from exc
+    _finish(result)
+
+
+@app.command()
+def resume(
+    run_id: Annotated[str, typer.Argument(help="Run id to resume.")],
+    tui: Annotated[bool, typer.Option("--tui/--no-tui")] = True,
+) -> None:
+    """Resume an unfinished run (fresh sandboxes, persisted state)."""
+    engine = LoopEngine(load_config())
+    try:
+        result = _drive_with_ui(engine, tui=tui, action=lambda: engine.resume(run_id))
+    except SdxloopError as exc:
+        console.print(f"[bold red]resume failed:[/] {exc}")
+        raise typer.Exit(2) from exc
+    _finish(result)
+
+
+@app.command()
+def cancel(run_id: Annotated[str, typer.Argument()]) -> None:
+    """Mark a run cancelled (takes effect at the next phase boundary)."""
+    config = load_config()
+    engine = LoopEngine(config)
+    try:
+        engine.cancel(run_id)
+    except SdxloopError as exc:
+        console.print(f"[bold red]{exc}[/]")
+        raise typer.Exit(2) from exc
+    console.print(f"run {run_id} cancelled")
+
+
+@app.command()
+def status(
+    run_id: Annotated[str | None, typer.Argument(help="Run id for details.")] = None,
+) -> None:
+    """List runs, or show one run's tasks and phase history."""
+    config = load_config()
+    store = _store(config)
+    if run_id is None:
+        table = Table(title="sdxloop runs")
+        table.add_column("run")
+        table.add_column("state")
+        table.add_column("outcome", max_width=60)
+        table.add_column("updated")
+        for record in store.list_runs():
+            table.add_row(
+                record.run_id,
+                record.state,
+                record.outcome[:60],
+                time.strftime("%Y-%m-%d %H:%M", time.localtime(record.updated_at)),
+            )
+        console.print(table)
+        return
+
+    try:
+        record = store.get_run(run_id)
+    except SdxloopError as exc:
+        console.print(f"[bold red]{exc}[/]")
+        raise typer.Exit(2) from exc
+    console.print(f"run [bold cyan]{record.run_id}[/]  state: [bold]{record.state}[/]")
+    console.print(f"outcome: {record.outcome}")
+    table = Table(title="tasks")
+    for column in ("task", "title", "state", "revisions", "replans"):
+        table.add_column(column)
+    for task in store.get_tasks(run_id):
+        table.add_row(
+            task.spec.id,
+            task.spec.title,
+            task.state,
+            str(task.revisions),
+            str(task.replans),
+        )
+    console.print(table)
+    attempts = store.phase_attempts(run_id)
+    console.print(f"{len(attempts)} phase attempts recorded")
+
+
+@app.command()
+def logs(
+    run_id: Annotated[str, typer.Argument()],
+    follow: Annotated[bool, typer.Option("--follow", "-f")] = False,
+    type_prefix: Annotated[
+        str | None, typer.Option("--type", help="Filter by event type prefix.")
+    ] = None,
+    task: Annotated[str | None, typer.Option("--task", help="Filter by task id.")] = None,
+) -> None:
+    """Replay (or tail) a run's event stream from the state store."""
+    config = load_config()
+    store = _store(config)
+    store.get_run(run_id)  # validates existence
+    last_seq = 0
+    while True:
+        for seq, event in store.events(run_id, after_seq=last_seq, type_prefix=type_prefix):
+            last_seq = seq
+            if task and event.data.get("task_id") != task:
+                continue
+            console.print(format_event(event), highlight=False)
+        if not follow:
+            break
+        if store.get_run(run_id).state in ("completed", "failed", "cancelled"):
+            break
+        time.sleep(0.5)
+
+
+@sandbox_app.command("ls")
+def sandbox_ls() -> None:
+    """List sdxloop-managed sandboxes."""
+    config = load_config()
+    cli = SbxCLI(app_name=config.app_name or None)
+    table = Table(title="sdxloop sandboxes")
+    for column in ("name", "agent", "status", "workspace"):
+        table.add_column(column)
+    for info in cli.ls():
+        if info.name.startswith("sdxloop-"):
+            table.add_row(info.name, info.agent or "", info.status or "", info.workspace or "")
+    console.print(table)
+
+
+@sandbox_app.command("rm")
+def sandbox_rm(
+    name: Annotated[str | None, typer.Argument(help="Sandbox name.")] = None,
+    run_id: Annotated[str | None, typer.Option("--run", help="Remove a run's pair.")] = None,
+    all_: Annotated[bool, typer.Option("--all", help="Remove all sdxloop sandboxes.")] = False,
+) -> None:
+    """Remove sdxloop sandboxes by name, by run, or all of them."""
+    config = load_config()
+    cli = SbxCLI(app_name=config.app_name or None)
+    targets: list[str] = []
+    if name:
+        targets.append(name)
+    if run_id:
+        targets += [sandbox_name(run_id, "agent"), sandbox_name(run_id, "github")]
+    if all_:
+        targets += [i.name for i in cli.ls() if i.name.startswith("sdxloop-")]
+    if not targets:
+        console.print("nothing to remove: pass a NAME, --run, or --all")
+        raise typer.Exit(2)
+    for target in dict.fromkeys(targets):
+        try:
+            cli.rm(target)
+            console.print(f"removed {target}")
+        except SdxloopError as exc:
+            console.print(f"[yellow]skip {target}:[/] {exc}")
+
+
+@config_app.command("show")
+def config_show() -> None:
+    """Show the resolved configuration and where each value came from."""
+    try:
+        config, sources = load_config_with_sources()
+    except SdxloopError as exc:
+        console.print(f"[bold red]{exc}[/]")
+        raise typer.Exit(2) from exc
+    table = Table(title="sdxloop configuration")
+    table.add_column("key")
+    table.add_column("value")
+    table.add_column("source")
+    flat: dict[str, Any] = {}
+
+    def flatten(prefix: str, data: dict[str, Any]) -> None:
+        for key, value in data.items():
+            dotted = f"{prefix}{key}"
+            if isinstance(value, dict):
+                flatten(f"{dotted}.", value)
+            else:
+                flat[dotted] = value
+
+    flatten("", config.model_dump(mode="json"))
+    for dotted in sorted(flat):
+        table.add_row(dotted, repr(flat[dotted]), sources.get(dotted, "default"))
+    console.print(table)
+
+
+@app.command()
+def init(
+    force: Annotated[bool, typer.Option("--force", help="Overwrite an existing file.")] = False,
+) -> None:
+    """Write a commented sdxloop.toml with the default configuration."""
+    path = Path("sdxloop.toml")
+    if path.exists() and not force:
+        console.print("sdxloop.toml already exists (use --force to overwrite)")
+        raise typer.Exit(2)
+    path.write_text(DEFAULT_CONFIG_TOML)
+    console.print(f"wrote {path}")
+
+
+@app.command()
+def doctor() -> None:
+    """Check that this host is ready to run sdxloop."""
+    ok = run_doctor(console)
+    raise typer.Exit(0 if ok else 1)
+
+
+DEFAULT_CONFIG_TOML = """\
+# sdxloop configuration. Every key is optional; these are the defaults.
+# Precedence: SDXLOOP_* env vars > this file > pyproject [tool.sdxloop].
+
+# Copilot model for agent sessions ("auto" lets the SDK choose).
+model = "auto"
+# sbx --app-name isolating sdxloop's sandboxes/policies/secrets.
+app_name = "sdxloop"
+# Where run state (SQLite) and per-run workspaces live.
+state_dir = ".sdxloop"
+# Keep sandboxes around after a run (for debugging).
+keep_sandboxes = false
+# Worker transport: "stream" (default) or "poll".
+worker_transport = "stream"
+# Secret injection: "proxy" (sbx keychain proxy; recommended) or "plain-env".
+secret_strategy = "proxy"
+
+[sandbox]
+# Custom sandbox template reference (defaults to the sbx shell template).
+# template = "docker.io/you/your-template:v1"
+# Extra network allow rules applied to both sandboxes.
+extra_allow_domains = []
+
+[github]
+# Report run progress to a GitHub repo ("owner/repo"); empty disables.
+# report_repo = "you/your-repo"
+
+[budgets]
+max_revisions_per_task = 2
+max_replans_per_task = 1
+max_tasks = 20
+max_wall_clock_s = 7200.0
+per_job_timeout_s = 900.0
+"""
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

sdxloop/cli/doctor.py

@@ -0,0 +1,145 @@
+"""sdxloop doctor: host readiness checks with remediation hints."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from rich.console import Console
+from rich.table import Table
+
+from sdxloop.config import load_config
+from sdxloop.errors import SbxError, SbxNotFoundError
+from sdxloop.sbx.cli import SbxCLI
+from sdxloop.sbx.provision import (
+    AGENT_TOKEN_HOSTS,
+    COPILOT_TOKEN_ENV,
+    GH_TOKEN_ENVS,
+)
+from sdxloop.worker.wheel import resolve_worker_wheel
+
+TESTED_SBX_SERIES = "0.35"
+
+
+@dataclass
+class Check:
+    name: str
+    ok: bool
+    detail: str
+    hard: bool = True
+
+
+def collect_checks(env: dict[str, str], cli: SbxCLI | None = None) -> list[Check]:
+    config = load_config(env=env)
+    cli = cli or SbxCLI(app_name=config.app_name or None)
+    checks: list[Check] = []
+
+    # sbx binary + version
+    try:
+        version = cli.version()
+    except SbxNotFoundError:
+        checks.append(
+            Check(
+                "sbx binary",
+                False,
+                "sbx not found on PATH — install Docker Sandboxes: "
+                "https://docs.docker.com/ai/sandboxes/",
+            )
+        )
+        version = None
+    else:
+        detail = f"found sbx {version or '(unknown version)'}"
+        if version and not version.startswith(TESTED_SBX_SERIES):
+            detail += f" (sdxloop is tested against {TESTED_SBX_SERIES}.x; parsing may drift)"
+        checks.append(Check("sbx binary", True, detail))
+
+    if version is not None:
+        # login / daemon reachable
+        try:
+            cli.ls()
+            checks.append(Check("sbx login", True, "sbx ls succeeded"))
+        except SbxError as exc:
+            checks.append(Check("sbx login", False, f"sbx ls failed ({exc}); run `sbx login`"))
+
+        # network policy reachable for the copilot hosts
+        for host in AGENT_TOKEN_HOSTS:
+            allowed = False
+            try:
+                allowed = cli.policy_check(host)
+            except SbxError:
+                allowed = False
+            checks.append(
+                Check(
+                    f"policy: {host}",
+                    allowed,
+                    "reachable"
+                    if allowed
+                    else (
+                        "blocked — run `sbx policy init balanced` and/or "
+                        f"`sbx policy allow network {host}`"
+                    ),
+                    hard=False,  # per-sandbox allows are applied at provision time
+                )
+            )
+
+    # tokens
+    checks.append(
+        Check(
+            COPILOT_TOKEN_ENV,
+            bool(env.get(COPILOT_TOKEN_ENV)),
+            "set"
+            if env.get(COPILOT_TOKEN_ENV)
+            else 'not set — create a fine-grained PAT with the "Copilot Requests" '
+            f"permission and export {COPILOT_TOKEN_ENV}",
+        )
+    )
+    gh_set = any(env.get(name) for name in GH_TOKEN_ENVS)
+    checks.append(
+        Check(
+            "/".join(GH_TOKEN_ENVS),
+            gh_set,
+            "set"
+            if gh_set
+            else "not set — create a fine-grained PAT (issues:write, contents:read, ...) "
+            "and export GH_TOKEN",
+        )
+    )
+
+    # worker wheel
+    wheel = resolve_worker_wheel()
+    checks.append(
+        Check(
+            "worker wheel",
+            True,
+            f"resolved: {wheel.name}" if wheel else "no local wheel; will install from PyPI",
+            hard=False,
+        )
+    )
+
+    # state dir writable
+    try:
+        config.state_dir.mkdir(parents=True, exist_ok=True)
+        probe = config.state_dir / ".doctor-probe"
+        probe.write_text("ok")
+        probe.unlink()
+        checks.append(Check("state dir", True, str(config.state_dir.resolve())))
+    except OSError as exc:
+        checks.append(Check("state dir", False, f"not writable: {exc}"))
+
+    return checks
+
+
+def run_doctor(console: Console, env: dict[str, str] | None = None) -> bool:
+    import os
+
+    checks = collect_checks(dict(os.environ) if env is None else env)
+    table = Table(title="sdxloop doctor")
+    table.add_column("check")
+    table.add_column("status")
+    table.add_column("detail", max_width=80)
+    for check in checks:
+        status = (
+            "[green]ok[/]" if check.ok else ("[red]FAIL[/]" if check.hard else "[yellow]warn[/]")
+        )
+        table.add_row(check.name, status, check.detail)
+    console.print(table)
+    return all(check.ok or not check.hard for check in checks)

sdxloop/cli/tui.py

@@ -0,0 +1,129 @@
+"""Rich rendering for runs: live dashboard and plain event logging."""
+
+from __future__ import annotations
+
+import datetime
+from collections import deque
+from typing import Any
+
+from rich.console import Console, Group, RenderableType
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from sdxloop.events import Event, HostEventTypes
+
+TASK_STATE_STYLES = {
+    "pending": "dim",
+    "planning": "yellow",
+    "executing": "cyan",
+    "scrutinizing": "magenta",
+    "verifying": "blue",
+    "validating": "magenta",
+    "done": "green",
+    "failed": "red",
+    "skipped": "dim red",
+}
+
+INTERESTING_EVENTS = (
+    "run.",
+    "task.",
+    "sandbox.",
+    "agent.message",
+    "agent.tool",
+    "gh.",
+    "worker.error",
+)
+
+
+class Dashboard:
+    """Accumulates run state from the event stream and renders it."""
+
+    def __init__(self, max_events: int = 12) -> None:
+        self.run_id: str | None = None
+        self.run_state: str = "starting"
+        self.outcome: str = ""
+        self.tasks: dict[str, dict[str, Any]] = {}
+        self.recent: deque[str] = deque(maxlen=max_events)
+
+    # -- event intake ------------------------------------------------------
+
+    def on_event(self, event: Event) -> None:
+        self.run_id = self.run_id or event.run_id
+        data = event.data
+        if event.type == HostEventTypes.RUN_START:
+            self.outcome = str(data.get("outcome", ""))
+        elif event.type == HostEventTypes.RUN_STATE or event.type == HostEventTypes.RUN_END:
+            self.run_state = str(data.get("state", self.run_state))
+        elif event.type in (HostEventTypes.TASK_START, HostEventTypes.TASK_STATE):
+            task_id = str(data.get("task_id"))
+            entry = self.tasks.setdefault(task_id, {"title": "", "state": "pending"})
+            if data.get("title"):
+                entry["title"] = str(data["title"])
+            if data.get("state"):
+                entry["state"] = str(data["state"])
+            entry["revisions"] = data.get("revisions", entry.get("revisions", 0))
+            entry["replans"] = data.get("replans", entry.get("replans", 0))
+        elif event.type == HostEventTypes.TASK_END:
+            task_id = str(data.get("task_id"))
+            entry = self.tasks.setdefault(task_id, {"title": "", "state": "pending"})
+            if data.get("title"):
+                entry["title"] = str(data["title"])
+            entry["state"] = str(data.get("state", entry["state"]))
+        if event.type.startswith(INTERESTING_EVENTS):
+            self.recent.append(format_event(event))
+
+    # -- rendering ---------------------------------------------------------
+
+    def renderable(self) -> RenderableType:
+        header = Text.assemble(
+            ("run ", "bold"),
+            (self.run_id or "…", "bold cyan"),
+            ("  state: ", ""),
+            (self.run_state, "bold yellow"),
+        )
+        outcome = Text(self.outcome[:200], style="italic dim")
+
+        table = Table(expand=True, box=None, pad_edge=False)
+        table.add_column("task", style="bold", no_wrap=True)
+        table.add_column("title", ratio=2)
+        table.add_column("state", no_wrap=True)
+        table.add_column("rev/replan", no_wrap=True, justify="right")
+        for task_id, entry in self.tasks.items():
+            state = str(entry.get("state", "?"))
+            table.add_row(
+                task_id,
+                str(entry.get("title", "")),
+                Text(state, style=TASK_STATE_STYLES.get(state, "")),
+                f"{entry.get('revisions', 0)}/{entry.get('replans', 0)}",
+            )
+        if not self.tasks:
+            table.add_row("…", "decomposing outcome", Text("pending", style="dim"), "")
+
+        events_panel = Panel(
+            Text("\n".join(self.recent) or "waiting for events…", overflow="ellipsis"),
+            title="events",
+            border_style="dim",
+        )
+        return Group(Panel(Group(header, outcome), border_style="cyan"), table, events_panel)
+
+
+def format_event(event: Event) -> str:
+    stamp = datetime.datetime.fromtimestamp(event.ts).strftime("%H:%M:%S")
+    parts = [stamp, event.type]
+    if event.data.get("task_id"):
+        parts.append(f"[{event.data['task_id']}]")
+    for key in ("state", "content", "tool", "op", "line", "message", "outcome"):
+        if event.data.get(key):
+            value = str(event.data[key]).replace("\n", " ")
+            parts.append(value[:120])
+            break
+    return " ".join(parts)
+
+
+def plain_printer(console: Console) -> Any:
+    def print_event(event: Event) -> None:
+        if event.type.startswith(INTERESTING_EVENTS):
+            console.print(format_event(event), highlight=False)
+
+    return print_event