sbxloop 0.2.0__py3-none-any.whl

sbxloop/__init__.py

@@ -0,0 +1,26 @@
+"""sbxloop — agentic loop orchestration on Docker Sandboxes (sbx).
+
+Every sbxloop 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.2.0"
+
+from sbxloop.config import Budgets, Config, load_config
+from sbxloop.engine import LoopEngine, RunResult, run_outcome
+from sbxloop.events import Event, EventBus, Hook
+
+__all__ = [
+    "Budgets",
+    "Config",
+    "Event",
+    "EventBus",
+    "Hook",
+    "LoopEngine",
+    "RunResult",
+    "__version__",
+    "load_config",
+    "run_outcome",
+]

sbxloop/cli/__init__.py

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

sbxloop/cli/app.py

@@ -0,0 +1,365 @@
+"""The sbxloop 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 sbxloop
+from sbxloop.cli.doctor import run_doctor
+from sbxloop.cli.tui import Dashboard, format_event, plain_printer
+from sbxloop.config import Config, load_config, load_config_with_sources, load_dotenv_file
+from sbxloop.engine.engine import LoopEngine
+from sbxloop.engine.model import RunResult
+from sbxloop.engine.store import StateStore
+from sbxloop.errors import SdxloopError
+from sbxloop.sbx.cli import SbxCLI
+from sbxloop.sbx.provision import sandbox_name
+
+app = typer.Typer(
+    name="sbxloop",
+    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 sbxloop 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"sbxloop {sbxloop.__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _main_callback(
+    version: Annotated[
+        bool, typer.Option("--version", callback=_version_callback, is_eager=True)
+    ] = False,
+) -> None:
+    """sbxloop — agentic loops on Docker Sandboxes."""
+    # Every command sees ./.env (tokens + SBXLOOP_* settings); real
+    # environment variables always take precedence.
+    load_dotenv_file()
+
+
+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="sbxloop 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 sbxloop-managed sandboxes."""
+    config = load_config()
+    cli = SbxCLI(app_name=config.app_name or None)
+    table = Table(title="sbxloop sandboxes")
+    for column in ("name", "agent", "status", "workspace"):
+        table.add_column(column)
+    for info in cli.ls():
+        if info.name.startswith("sbxloop-"):
+            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 sbxloop sandboxes.")] = False,
+) -> None:
+    """Remove sbxloop 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("sbxloop-")]
+    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="sbxloop 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 sbxloop.toml with the default configuration."""
+    path = Path("sbxloop.toml")
+    if path.exists() and not force:
+        console.print("sbxloop.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 sbxloop."""
+    ok = run_doctor(console)
+    raise typer.Exit(0 if ok else 1)
+
+
+DEFAULT_CONFIG_TOML = """\
+# sbxloop configuration. Every key is optional; these are the defaults.
+# Precedence: SBXLOOP_* env vars > this file > pyproject [tool.sbxloop].
+
+# Copilot model for agent sessions ("auto" lets the SDK choose).
+model = "auto"
+# Optional sbx --app-name isolating sbxloop's sandboxes/policies/secrets.
+# Empty shares your normal sbx state (your login + balanced policy apply).
+# If set, that isolated state needs its own `sbx --app-name <name> login`
+# and `sbx --app-name <name> policy init balanced`.
+app_name = ""
+# Where run state (SQLite) and per-run workspaces live.
+state_dir = ".sbxloop"
+# 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()

sbxloop/cli/doctor.py

@@ -0,0 +1,172 @@
+"""sbxloop doctor: host readiness checks with remediation hints."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from rich.console import Console
+from rich.table import Table
+
+from sbxloop.config import load_config
+from sbxloop.errors import SbxError, SbxNotFoundError
+from sbxloop.sbx.cli import SbxCLI
+from sbxloop.sbx.provision import (
+    AGENT_TOKEN_HOSTS,
+    COPILOT_TOKEN_ENV,
+    GH_TOKEN_ENVS,
+)
+from sbxloop.worker.wheel import resolve_worker_wheel
+
+TESTED_SBX_SERIES = "0.35"
+
+
+@dataclass
+class Check:
+    name: str
+    ok: bool
+    detail: str
+    hard: bool = True
+
+
+ProgressFn = Callable[[str], None]
+
+
+def collect_checks(
+    env: dict[str, str],
+    cli: SbxCLI | None = None,
+    progress: ProgressFn | None = None,
+) -> list[Check]:
+    config = load_config(env=env)
+    cli = cli or SbxCLI(app_name=config.app_name or None)
+    checks: list[Check] = []
+    report = progress or (lambda _message: None)
+
+    # sbx binary + version. The very first sbx invocation may trigger
+    # Docker's interactive browser login if this sbx application state has
+    # never authenticated - say so instead of appearing hung.
+    report("checking sbx binary (Docker may open a browser window for authentication on first use)")
+    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" (sbxloop 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
+        report("checking sbx login")
+        try:
+            cli.ls()
+            checks.append(Check("sbx login", True, "sbx ls succeeded"))
+        except SbxError as exc:
+            login_cmd = (
+                f"sbx --app-name {config.app_name} login" if config.app_name else "sbx login"
+            )
+            checks.append(Check("sbx login", False, f"sbx ls failed ({exc}); run `{login_cmd}`"))
+
+        # network policy reachable for the copilot hosts
+        for host in AGENT_TOKEN_HOSTS:
+            report(f"checking network policy for {host}")
+            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 _clean(detail: str, limit: int = 300) -> str:
+    """Collapse whitespace/newlines so multi-line sbx stderr can't shatter
+    the table layout; long tails are elided."""
+    flat = " ".join(detail.split())
+    return flat if len(flat) <= limit else flat[: limit - 1] + "\u2026"
+
+
+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,
+        progress=lambda message: console.print(f"[dim]\u2026 {message}[/dim]", highlight=False),
+    )
+    table = Table(title="sbxloop doctor")
+    table.add_column("check", no_wrap=True)
+    table.add_column("status", no_wrap=True)
+    table.add_column("detail", overflow="fold")
+    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, _clean(check.detail))
+    console.print(table)
+    return all(check.ok or not check.hard for check in checks)