sbxloop 0.5.5__tar.gz → 0.5.7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sbxloop
-Version: 0.5.5
+Version: 0.5.7
 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.7}/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.7'
+__version_tuple__ = version_tuple = (0, 5, 7)
 
 __commit_id__ = commit_id = None

{sbxloop-0.5.5 → sbxloop-0.5.7}/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".
@@ -587,6 +655,15 @@ max_replans_per_task = 1
 max_tasks = 20
 max_wall_clock_s = 7200.0
 per_job_timeout_s = 900.0
+
+[limits]
+# Sandbox resource guardrails (percent used; 0 disables). Sampled in-VM on
+# the worker heartbeat and shown as a gauge in the TUI status panel.
+# Crossing disk_abort fails the current task with an explicit
+# "sandbox disk exhausted" error.
+disk_warn = 85.0
+disk_abort = 95.0
+mem_warn = 90.0
 """
 
 

{sbxloop-0.5.5 → sbxloop-0.5.7}/src/sbxloop/cli/doctor.py

@@ -122,6 +122,29 @@ def collect_checks(
                 )
             )
 
+        # Host-side resource stats: sbx 0.35.x has no stats command, so
+        # resource telemetry samples in-VM on the worker heartbeat. This is
+        # the field-check for the day sbx grows one (issue #54) — purely
+        # informational either way.
+        report("checking for host-side sandbox stats")
+        stats_available = False
+        try:
+            stats_available = cli.run("stats", "--help", check=False).returncode == 0
+        except SbxError:
+            stats_available = False
+        checks.append(
+            Check(
+                "sandbox stats",
+                True,
+                "host-side `sbx stats` available — sbxloop still samples in-VM; "
+                "consider filing an issue to prefer host-side stats"
+                if stats_available
+                else "no host-side `sbx stats`; resource telemetry samples in-VM "
+                f"on the worker heartbeat (expected on {TESTED_SBX_SERIES}.x)",
+                hard=False,
+            )
+        )
+
     # tokens
     checks.append(
         Check(

{sbxloop-0.5.5 → sbxloop-0.5.7}/src/sbxloop/cli/tui.py

@@ -42,7 +42,9 @@ TASK_STATE_STYLES = {
 _LIFECYCLE_PREFIXES = ("run.", "task.", "phase.", "sandbox.", "gh.")
 
 # High-volume noise excluded from the transcript (still queryable via
-# `sbxloop logs`): streaming deltas, raw stdout passthrough, heartbeats.
+# `sbxloop logs`): streaming deltas, raw stdout passthrough, heartbeats,
+# per-beat resource samples (they live in the pinned gauge instead —
+# threshold *crossings* arrive as sandbox.resources_warning and do print).
 _TRANSCRIPT_SKIP = {
     EventTypes.AGENT_MESSAGE_DELTA,
     EventTypes.WORKER_STDOUT,
@@ -51,8 +53,11 @@ _TRANSCRIPT_SKIP = {
     EventTypes.WORKER_RESULT,
     EventTypes.WORKER_END,
     EventTypes.AGENT_USAGE,
+    EventTypes.SANDBOX_RESOURCES,
 }
 
+RESOURCE_LEVEL_STYLES = {"ok": "dim", "warn": "yellow", "abort": "bold red"}
+
 AGENT_MESSAGE_CLIP = 4000
 # One-line clip for tool arguments; output tail lines shown on tool failure.
 TOOL_ARGS_LINE_CLIP = 160
@@ -148,7 +153,7 @@ def render_event(event: Event) -> RenderableType | None:
         style = "dim"
         if event.type == HostEventTypes.TASK_STATE:
             style = TASK_STATE_STYLES.get(str(data.get("state", "")), "dim")
-        elif "fallback" in event.type or "missing" in event.type:
+        elif "fallback" in event.type or "missing" in event.type or "warning" in event.type:
             style = "yellow"
         return Text(line, style=style, overflow="fold")
 
@@ -166,13 +171,18 @@ class Dashboard:
         self.run_state: str = "starting"
         self.outcome: str = ""
         self.tasks: dict[str, dict[str, Any]] = {}
+        # Latest resource sample per sandbox role, rendered as one compact
+        # gauge line each; only escalates visually past warn/abort levels.
+        self.resources: dict[str, dict[str, Any]] = {}
 
     # -- 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:
+        if event.type == EventTypes.SANDBOX_RESOURCES:
+            self.resources[str(data.get("role") or "sandbox")] = dict(data)
+        elif event.type == HostEventTypes.RUN_START:
             self.outcome = str(data.get("outcome", ""))
         elif event.type in (HostEventTypes.RUN_STATE, HostEventTypes.RUN_END):
             self.run_state = str(data.get("state", self.run_state))
@@ -219,12 +229,29 @@ class Dashboard:
         if not self.tasks:
             table.add_row("…", "decomposing outcome", Text("pending", style="dim"), "")
 
+        gauges = [self._gauge_line(role) for role in sorted(self.resources)]
         return Panel(
-            Group(header, outcome, table),
+            Group(header, outcome, table, *gauges),
             border_style="cyan",
             padding=(0, 1),
         )
 
+    def _gauge_line(self, role: str) -> Text:
+        sample = self.resources[role]
+        level = str(sample.get("level", "ok"))
+        parts = []
+        if sample.get("disk_used_pct") is not None:
+            parts.append(f"disk {sample['disk_used_pct']:.0f}%")
+        if sample.get("mem_used_pct") is not None:
+            parts.append(f"mem {sample['mem_used_pct']:.0f}%")
+        if sample.get("load1") is not None:
+            parts.append(f"load {sample['load1']}")
+        suffix = "  ⚠ " + level if level != "ok" else ""
+        return Text(
+            f"{role}: " + " · ".join(parts) + suffix,
+            style=RESOURCE_LEVEL_STYLES.get(level, "dim"),
+        )
+
 
 def format_event(event: Event) -> str:
     """Dense single-line form (used by `sbxloop logs` and lifecycle lines)."""
@@ -239,6 +266,17 @@ def format_event(event: Event) -> str:
             value = str(event.data[key]).replace("\n", " ")
             parts.append(value[:160])
             break
+    if event.data.get("disk_used_pct") is not None:
+        # Resource samples: make `sbxloop logs --type-prefix sandbox.resources`
+        # answer "what did disk look like before the failure" at a glance.
+        summary = [f"disk={event.data['disk_used_pct']}%"]
+        if event.data.get("mem_used_pct") is not None:
+            summary.append(f"mem={event.data['mem_used_pct']}%")
+        if event.data.get("load1") is not None:
+            summary.append(f"load={event.data['load1']}")
+        if event.data.get("level"):
+            summary.append(str(event.data["level"]))
+        parts.append(" ".join(summary))
     if event.data.get("args"):
         parts.append(_one_line(str(event.data["args"]), 120))
     if picked != "error" and event.data.get("error"):

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

@@ -18,7 +18,14 @@ from collections.abc import Mapping
 from pathlib import Path
 from typing import Any, Literal
 
-from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    ValidationError,
+    field_validator,
+    model_validator,
+)
 
 from sbxloop.errors import ConfigError
 
@@ -68,6 +75,35 @@ class GithubConfig(_ConfigModel):
         return self.repo is not None
 
 
+class Limits(_ConfigModel):
+    """Sandbox resource guardrails, sampled in-VM on the worker heartbeat.
+
+    Thresholds are percent-used of the workspace filesystem / memory; 0
+    disables a guardrail. Crossing a warn threshold emits a prominent
+    ``sandbox.resources_warning`` event and escalates the TUI gauge;
+    crossing ``disk_abort`` fails the current task with an explicit
+    "sandbox disk exhausted" error instead of letting in-VM tooling fail
+    confusingly on a full disk.
+    """
+
+    disk_warn: float = 85.0
+    disk_abort: float = 95.0
+    mem_warn: float = 90.0
+
+    @model_validator(mode="after")
+    def _check_thresholds(self) -> Limits:
+        for name in ("disk_warn", "disk_abort", "mem_warn"):
+            value = getattr(self, name)
+            if value < 0 or value > 100:
+                raise ValueError(f"limits.{name} must be a percentage in 0..100, got {value}")
+        if 0 < self.disk_abort <= self.disk_warn:
+            raise ValueError(
+                f"limits.disk_abort ({self.disk_abort}) must be greater than "
+                f"limits.disk_warn ({self.disk_warn})"
+            )
+        return self
+
+
 class Budgets(_ConfigModel):
     max_revisions_per_task: int = 2
     max_replans_per_task: int = 1
@@ -85,6 +121,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
@@ -95,6 +136,7 @@ class Config(_ConfigModel):
     sandbox: SandboxConfig = Field(default_factory=SandboxConfig)
     github: GithubConfig = Field(default_factory=GithubConfig)
     budgets: Budgets = Field(default_factory=Budgets)
+    limits: Limits = Field(default_factory=Limits)
 
 
 def _read_toml(path: Path) -> dict[str, Any]:

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

@@ -18,6 +18,7 @@ import json
 import logging
 import time
 from collections.abc import Callable, Sequence
+from typing import Any
 
 from sbxloop.config import Config, load_config, load_dotenv_file
 from sbxloop.deliver import deliver_workspace
@@ -75,9 +76,13 @@ class LoopEngine:
             install_workers if install_workers is not None else self.config.install_workers
         )
         self.clock = clock
+        # Latest sandbox.resources sample per sandbox role, fed by the bus;
+        # consulted for the disk guardrail and the harvest-truncation note.
+        self._last_resources: dict[str, dict[str, object]] = {}
         for hook in hooks:
             self.bus.attach_hook(hook)
         self.bus.subscribe(self._persist_event)
+        self.bus.subscribe(self._track_resources)
 
     def _persist_event(self, event: object) -> None:
         from sbxloop_worker.protocol import Event
@@ -85,6 +90,14 @@ class LoopEngine:
         assert isinstance(event, Event)
         self.store.append_event(event)
 
+    def _track_resources(self, event: object) -> None:
+        from sbxloop_worker.protocol import Event, EventTypes
+
+        assert isinstance(event, Event)
+        if event.type == EventTypes.SANDBOX_RESOURCES:
+            role = str(event.data.get("role") or "agent")
+            self._last_resources[role] = dict(event.data)
+
     # -- public API --------------------------------------------------------
 
     def start(self, outcome: str, *, run_id: str | None = None) -> RunResult:
@@ -113,49 +126,64 @@ 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,
+                        role="agent",
+                        limits=self.config.limits,
                     )
-                    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,
+                            role="github",
+                            limits=self.config.limits,
+                        )
+                        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 +196,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(
@@ -214,12 +266,28 @@ class LoopEngine:
         if target is None or not target.is_dir():
             return
         count = sum(1 for p in target.rglob("*") if p.is_file())
+        extra: dict[str, Any] = {}
+        sample = self._last_resources.get("agent")
+        if sample and sample.get("level") in ("warn", "abort"):
+            # Disk was under pressure at the last sample — harvested
+            # artifacts may be truncated or missing.
+            extra = {
+                "disk_used_pct": sample.get("disk_used_pct"),
+                "resources_level": sample.get("level"),
+            }
+            logger.warning(
+                "run %s: sandbox disk was at %s%% at the last sample — "
+                "harvested artifacts may be incomplete",
+                run_id,
+                sample.get("disk_used_pct"),
+            )
         self.bus.emit(
             HostEventTypes.RUN_ARTIFACTS,
             run_id,
             path=str(target),
             files=count,
             mounted=pair.mounted,
+            **extra,
         )
 
     def _deliver(
@@ -339,6 +407,14 @@ class LoopEngine:
 
         while not task.terminal:
             self._check_cancelled_and_clock(run_id, deadline)
+            abort_reason = self._resource_abort_reason()
+            if abort_reason:
+                # Fail the task with a diagnosis instead of letting the next
+                # phase produce garbage in a full sandbox. Dependents are
+                # skipped by the normal failed-task machinery.
+                task.last_feedback = abort_reason
+                self._set_task_state(run_id, task, "failed")
+                break
             if task.state == "planning":
                 self._phase_plan(run_id, phases, task)
             elif task.state == "executing":
@@ -475,6 +551,18 @@ class LoopEngine:
 
     # -- bookkeeping -------------------------------------------------------
 
+    def _resource_abort_reason(self) -> str | None:
+        """Non-None when the agent sandbox's last resource sample crossed
+        the disk_abort threshold (the worker classifies; the level rides on
+        the event)."""
+        sample = self._last_resources.get("agent")
+        if sample and sample.get("level") == "abort":
+            return (
+                f"sandbox disk exhausted: {sample.get('disk_used_pct')}% of the workspace "
+                f"filesystem is used (limits.disk_abort={self.config.limits.disk_abort}%)"
+            )
+        return None
+
     def _check_cancelled_and_clock(self, run_id: str, deadline: float) -> None:
         if self.store.get_run(run_id).state == "cancelled":
             raise StateError(f"run {run_id} was cancelled")

{sbxloop-0.5.5 → sbxloop-0.5.7}/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.7}/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.7}/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)
 

{sbxloop-0.5.5 → sbxloop-0.5.7}/src/sbxloop/worker/client.py

@@ -27,7 +27,7 @@ from collections import deque
 from pathlib import Path
 
 import sbxloop
-from sbxloop.config import WorkerTransport
+from sbxloop.config import Limits, WorkerTransport
 from sbxloop.errors import SbxError, WorkerError, WorkerTimeoutError
 from sbxloop.events import EventBus
 from sbxloop.sbx.models import ExecResult
@@ -61,6 +61,8 @@ class WorkerClient:
         python: str = DEFAULT_PYTHON,
         poll_interval: float = 2.0,
         grace_s: float = 60.0,
+        role: str | None = None,
+        limits: Limits | None = None,
     ) -> None:
         self.sandbox = sandbox
         self.bus = bus or EventBus()
@@ -68,6 +70,11 @@ class WorkerClient:
         self.python = python
         self.poll_interval = poll_interval
         self.grace_s = grace_s
+        # Sandbox role for enriching resource telemetry (the worker doesn't
+        # know which sandbox it lives in), and guardrail thresholds to pass
+        # through to the worker's heartbeat sampler.
+        self.role = role
+        self.limits = limits
 
     # -- install -----------------------------------------------------------
 
@@ -266,6 +273,15 @@ class WorkerClient:
         # process itself chdirs there — agent SDK sessions inherit it.
         if job.cwd:
             argv += ["--cwd", job.cwd]
+        if self.limits is not None:
+            argv += [
+                "--disk-warn",
+                str(self.limits.disk_warn),
+                "--disk-abort",
+                str(self.limits.disk_abort),
+                "--mem-warn",
+                str(self.limits.mem_warn),
+            ]
         # sbx injects secrets through the sandbox session/profile machinery;
         # a bare exec'd process may not see them. Run the worker under a
         # login shell so the sandbox environment is fully loaded.
@@ -338,6 +354,11 @@ class WorkerClient:
                 Event.now(EventTypes.WORKER_STDOUT, job.run_id, job_id=job.job_id, line=line)
             )
             return
+        if self.role is not None and event.type in (
+            EventTypes.SANDBOX_RESOURCES,
+            EventTypes.SANDBOX_RESOURCES_WARNING,
+        ):
+            event.data.setdefault("role", self.role)
         self.bus.publish(event)
 
     # -- poll transport ----------------------------------------------------