sbxloop 0.5.5__tar.gz → 0.5.6__tar.gz

{sbxloop-0.5.5 → sbxloop-0.5.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sbxloop
-Version: 0.5.5
+Version: 0.5.6
 Summary: Agentic loop orchestration on Docker Sandboxes (sbx) with isolated credential domains
 Project-URL: Homepage, https://github.com/brettbergin/sbxloop
 Project-URL: Repository, https://github.com/brettbergin/sbxloop

{sbxloop-0.5.5 → sbxloop-0.5.6}/src/sbxloop/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.5.5'
-__version_tuple__ = version_tuple = (0, 5, 5)
+__version__ = version = '0.5.6'
+__version_tuple__ = version_tuple = (0, 5, 6)
 
 __commit_id__ = commit_id = None

{sbxloop-0.5.5 → sbxloop-0.5.6}/src/sbxloop/cli/app.py

@@ -169,6 +169,10 @@ def _finish(result: RunResult, config: Config) -> None:
     for task in result.tasks:
         console.print(f"  {task.spec.id}: {task.state}  ({task.spec.title})")
     _print_artifacts_summary(result, config)
+    if result.kept_sandboxes:
+        console.print(f"\n[bold yellow]sandboxes kept:[/] {', '.join(result.kept_sandboxes)}")
+        console.print(f"  inspect: [cyan]sbxloop shell {result.run_id}[/] (--role github)")
+        console.print(f"  remove:  [cyan]sbxloop sandbox rm --run {result.run_id}[/]")
     raise typer.Exit(0 if result.succeeded else 1)
 
 
@@ -193,10 +197,21 @@ def run(
     keep_sandboxes: Annotated[
         bool, typer.Option("--keep-sandboxes", help="Do not remove sandboxes at the end.")
     ] = False,
+    keep_on_failure: Annotated[
+        bool | None,
+        typer.Option(
+            "--keep-on-failure/--no-keep-on-failure",
+            help="Keep the sandbox pair alive when the run fails (inspect with `sbxloop shell`).",
+        ),
+    ] = None,
     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)
+    config = _config_with_overrides(
+        model=model,
+        keep_sandboxes=keep_sandboxes or None,
+        keep_on_failure=keep_on_failure,
+    )
     if report is not None:
         config = config.model_copy(
             update={"github": config.github.model_copy(update={"report": report})}
@@ -331,6 +346,57 @@ def logs(
         time.sleep(0.5)
 
 
+# Prefer bash when the template has it, fall back to POSIX sh. `sbx exec`
+# has no documented -it flags; terminal attachment is inherited stdio.
+_INTERACTIVE_SHELL = ("sh", "-c", "command -v bash >/dev/null && exec bash -l; exec sh -l")
+
+
+@app.command()
+def shell(
+    run_id: Annotated[str, typer.Argument(help="Run id.")],
+    role: Annotated[
+        str, typer.Option("--role", help="Which sandbox of the pair: agent or github.")
+    ] = "agent",
+    command: Annotated[
+        str | None,
+        typer.Option(
+            "--command", "-c", help="Run one shell command instead of an interactive shell."
+        ),
+    ] = None,
+) -> None:
+    """Open a shell inside a run's sandbox (kept, in-flight, or leaked).
+
+    Attaching to an in-flight run is meant as observation: the worker owns
+    its env files and workspace, so avoid mutating them mid-phase.
+    """
+    if role not in ("agent", "github"):
+        console.print(f"[bold red]invalid --role {role!r}:[/] must be agent or github")
+        raise typer.Exit(2)
+    config = load_config()
+    store = _store(config)
+    try:
+        store.get_run(run_id)
+    except SdxloopError as exc:
+        console.print(f"[bold red]{exc}[/]")
+        raise typer.Exit(2) from exc
+    cli = SbxCLI(app_name=config.app_name or None)
+    name = sandbox_name(run_id, "agent" if role == "agent" else "github")
+    try:
+        live = any(info.name == name for info in cli.ls())
+    except SdxloopError as exc:
+        console.print(f"[bold red]{exc}[/]")
+        raise typer.Exit(2) from exc
+    if not live:
+        console.print(
+            f"[bold red]sandbox {name} is not running.[/] Sandboxes are removed at run end "
+            "unless kept (keep_on_failure, --keep-sandboxes), and kept ones may have been "
+            "pruned since."
+        )
+        raise typer.Exit(2)
+    argv = ("sh", "-lc", command) if command else _INTERACTIVE_SHELL
+    raise typer.Exit(cli.exec_interactive(name, argv))
+
+
 @app.command()
 def artifacts(
     run_id: Annotated[str, typer.Argument(help="Run id.")],
@@ -556,6 +622,8 @@ app_name = ""
 state_dir = ".sbxloop"
 # Keep sandboxes around after a run (for debugging).
 keep_sandboxes = false
+# Keep the pair alive only when a run fails; inspect with `sbxloop shell <run>`.
+keep_on_failure = false
 # Worker transport: "stream" (default) or "poll".
 worker_transport = "stream"
 # Secret injection: "proxy" (sbx keychain proxy; recommended) or "plain-env".

{sbxloop-0.5.5 → sbxloop-0.5.6}/src/sbxloop/config.py

@@ -85,6 +85,11 @@ class Config(_ConfigModel):
     app_name: str = ""
     state_dir: Path = Path(".sbxloop")
     keep_sandboxes: bool = False
+    # Keep the pair alive only when a run fails, so the evidence (worker
+    # stderr, install leftovers, workspace state) survives for
+    # `sbxloop shell <run>`. Kept runs are marked in the state DB and
+    # eventually collectable via `sbxloop sandbox prune --include-kept`.
+    keep_on_failure: bool = False
     worker_transport: WorkerTransport = "stream"
     secret_strategy: SecretStrategy = "proxy"
     # Advanced: in-sandbox interpreter for the worker, and whether to run the

{sbxloop-0.5.5 → sbxloop-0.5.6}/src/sbxloop/engine/engine.py

@@ -113,49 +113,60 @@ class LoopEngine:
         pair = provisioner.ensure_pair(run_id)
         assert pair.workspace is not None
         self.store.set_run_workspace(run_id, pair.workspace, pair.mounted)
+        if pair.keep:
+            # keep_sandboxes: mark up front so `sandbox prune` respects it.
+            self.store.set_run_kept(run_id, "manual")
         try:
             with pair:
-                agent = WorkerClient(
-                    pair.agent,
-                    self.bus,
-                    transport=self.config.worker_transport,
-                    python=self.worker_python,
-                )
-                github = (
-                    WorkerClient(
-                        pair.github,
+                try:
+                    agent = WorkerClient(
+                        pair.agent,
                         self.bus,
                         transport=self.config.worker_transport,
                         python=self.worker_python,
                     )
-                    if pair.github is not None
-                    else None
-                )
-                if self.install_workers:
-                    # ensure_dev_tools: the agent builds projects in this VM
-                    # (venvs, pip) — the github sandbox only runs API ops.
-                    agent.install(extras="copilot", ensure_dev_tools=True)
-                    if github is not None:
-                        github.install(extras="")
-                reporter, detach = self._attach_reporter(github, run_id, outcome)
-                try:
-                    phases = PhaseRunner(
-                        agent, self.config, run_id, outcome, workdir=pair.agent_workdir
+                    github = (
+                        WorkerClient(
+                            pair.github,
+                            self.bus,
+                            transport=self.config.worker_transport,
+                            python=self.worker_python,
+                        )
+                        if pair.github is not None
+                        else None
                     )
-                    state = self._run_phases(run_id, phases, deadline, pair)
-                    # Summary must post while the github sandbox is alive;
-                    # on an infra exception the run is resumable and the
-                    # resumed run reopens the same tracking issue.
-                    if reporter is not None:
-                        reporter.close_run(run_id, state)
-                finally:
-                    detach()
-                    # Harvest even when a phase raised: the sandbox is still
-                    # alive here, and partial artifacts beat none.
-                    self._harvest(run_id, pair)
-                    self._report_artifacts(run_id, pair)
+                    if self.install_workers:
+                        # ensure_dev_tools: the agent builds projects in this VM
+                        # (venvs, pip) — the github sandbox only runs API ops.
+                        agent.install(extras="copilot", ensure_dev_tools=True)
+                        if github is not None:
+                            github.install(extras="")
+                    reporter, detach = self._attach_reporter(github, run_id, outcome)
+                    try:
+                        phases = PhaseRunner(
+                            agent, self.config, run_id, outcome, workdir=pair.agent_workdir
+                        )
+                        state = self._run_phases(run_id, phases, deadline, pair)
+                        # Summary must post while the github sandbox is alive;
+                        # on an infra exception the run is resumable and the
+                        # resumed run reopens the same tracking issue.
+                        if reporter is not None:
+                            reporter.close_run(run_id, state)
+                    finally:
+                        detach()
+                        # Harvest even when a phase raised: the sandbox is still
+                        # alive here, and partial artifacts beat none.
+                        self._harvest(run_id, pair)
+                        self._report_artifacts(run_id, pair)
+                except SdxloopError:
+                    # Infra failures (install, worker, sbx) are exactly what
+                    # gets diagnosed in-sandbox; decide keep before pair exit.
+                    self._keep_on_failure(run_id, pair)
+                    raise
                 if state == "completed":
                     self._deliver(run_id, outcome, pair, github)
+                else:
+                    self._keep_on_failure(run_id, pair)
         except SdxloopError:
             # State is already persisted; the exception is the kill signal.
             raise
@@ -168,6 +179,30 @@ class LoopEngine:
             tasks=tasks,
             workspace=pair.workspace,
             mounted=pair.mounted,
+            kept_sandboxes=self._pair_names(pair) if pair.keep else [],
+        )
+
+    @staticmethod
+    def _pair_names(pair: SandboxPair) -> list[str]:
+        return [s.name for s in (pair.agent, pair.github) if s is not None]
+
+    def _keep_on_failure(self, run_id: str, pair: SandboxPair) -> None:
+        """Flip the pair to kept when configured, so a failed run's evidence
+        survives for `sbxloop shell`. Marked in the DB for `sandbox prune`."""
+        if not self.config.keep_on_failure or pair.keep:
+            return
+        pair.keep = True
+        self.store.set_run_kept(run_id, "debug")
+        names = self._pair_names(pair)
+        self.bus.emit(
+            HostEventTypes.RUN_KEEP,
+            run_id,
+            sandboxes=names,
+            reason="debug",
+            message=(
+                f"sandboxes kept for debugging: {', '.join(names)} — "
+                f"inspect with `sbxloop shell {run_id}`"
+            ),
         )
 
     def _attach_reporter(

{sbxloop-0.5.5 → sbxloop-0.5.6}/src/sbxloop/engine/model.py

@@ -156,6 +156,9 @@ class RunResult(_Model):
     tasks: list[TaskRecord] = Field(default_factory=list)
     workspace: Path | None = None
     mounted: bool = False
+    # Sandbox names deliberately left alive (keep_sandboxes/keep_on_failure),
+    # so callers can point the user at `sbxloop shell`.
+    kept_sandboxes: list[str] = Field(default_factory=list)
 
     @property
     def succeeded(self) -> bool:

{sbxloop-0.5.5 → sbxloop-0.5.6}/src/sbxloop/events.py

@@ -75,6 +75,7 @@ class HostEventTypes:
     RUN_STATE = "run.state"
     RUN_ARTIFACTS = "run.artifacts"
     RUN_DELIVER = "run.deliver"
+    RUN_KEEP = "run.keep"
     RUN_END = "run.end"
     TASK_START = "task.start"
     TASK_STATE = "task.state"

{sbxloop-0.5.5 → sbxloop-0.5.6}/src/sbxloop/sbx/cli.py

@@ -155,6 +155,22 @@ class SbxCLI:
                 raise self._error_for(result)
         return result
 
+    def exec_interactive(self, name: str, cmd: Sequence[str]) -> int:
+        """Run a command in a sandbox with the caller's terminal attached
+        (stdin/stdout/stderr inherited); returns the command's exit code.
+
+        `sbx exec` documents no -it-style flags; terminal attachment is
+        simply inheriting the caller's stdio.
+        """
+        argv = self.argv("exec", name, *cmd)
+        try:
+            return subprocess.run(argv, check=False).returncode
+        except FileNotFoundError as exc:
+            raise SbxNotFoundError(
+                f"sbx binary {self.binary!r} not found on PATH",
+                argv=argv,
+            ) from exc
+
     def cp(self, src: str, dst: str, *, timeout: float | None = None) -> None:
         self.run("cp", src, dst, timeout=timeout)