sbxloop 0.5.6__tar.gz → 0.5.8__tar.gz

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

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

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

@@ -587,6 +587,56 @@ def config_show() -> None:
     console.print(table)
 
 
+@config_app.command("policy")
+def config_policy() -> None:
+    """Show the effective per-phase network egress policy."""
+    from sbxloop.policy import PROMPT_ADVERTISED_DOMAINS
+    from sbxloop.sbx.provision import AGENT_ALLOW_DOMAINS, GITHUB_ALLOW_DOMAINS
+
+    try:
+        config = load_config()
+    except SdxloopError as exc:
+        console.print(f"[bold red]{exc}[/]")
+        raise typer.Exit(2) from exc
+
+    extra = list(config.sandbox.extra_allow_domains)
+    baseline = ", ".join([*AGENT_ALLOW_DOMAINS, *extra])
+    advertised = ", ".join(PROMPT_ADVERTISED_DOMAINS)
+
+    table = Table(title="agent sandbox: effective egress per phase")
+    table.add_column("phase", no_wrap=True)
+    table.add_column("policy", overflow="fold")
+    table.add_row("decompose / plan", "baseline")
+    table.add_row(
+        "execute",
+        "baseline + plan-declared grants (auto-granted just before execute, "
+        "within the [policy] bounds below; every grant/refusal is event-logged)",
+    )
+    table.add_row(
+        "scrutinize / verify / validate",
+        "baseline + grants already made — sbx has no policy revocation, so "
+        "grants persist for the sandbox's lifetime (sandboxes are removed at "
+        "run end; grants never outlive a run)",
+    )
+    console.print(table)
+    console.print(f"baseline (provisioned per-sandbox): {baseline}")
+    console.print(f"advertised by the user's balanced preset: {advertised}")
+
+    bounds = Table(title="[policy] bounds for plan-declared grants")
+    bounds.add_column("bound", no_wrap=True)
+    bounds.add_column("patterns", overflow="fold")
+    bounds.add_row(
+        "allow", ", ".join(config.policy.allow) or "(empty — plans may only use the baseline)"
+    )
+    bounds.add_row("deny", ", ".join(config.policy.deny) or "(none)")
+    console.print(bounds)
+
+    if config.github.enabled:
+        gh_domains = ", ".join([*GITHUB_ALLOW_DOMAINS, *extra])
+        console.print(f"github sandbox (all phases, no plan grants): {gh_domains}")
+    console.print("audit trail: [cyan]sbxloop logs RUN_ID --type policy.[/]")
+
+
 @app.command()
 def init(
     force: Annotated[bool, typer.Option("--force", help="Overwrite an existing file.")] = False,
@@ -635,6 +685,19 @@ secret_strategy = "proxy"
 # Extra network allow rules applied to both sandboxes.
 extra_allow_domains = []
 
+[policy]
+# Bounds for plan-declared egress. At PLAN time the agent may declare extra
+# domains a task needs during EXECUTE (each with a justification); they are
+# auto-granted to the agent sandbox just before EXECUTE only when they match
+# `allow` and no `deny` pattern, and every grant/refusal is logged as a run
+# event (`sbxloop logs RUN --type policy.`). Patterns: exact domains,
+# "*.example.com" (the domain and all subdomains), or "*" (everything).
+# Empty `allow` (the default) means plans may only use the always-reachable
+# baseline: the Copilot/GitHub hosts, PyPI, and apt mirrors.
+# See `sbxloop config policy` for the effective per-phase policy.
+allow = []
+deny = []
+
 [github]
 # The GitHub integration. Unset (the default) disables GitHub entirely:
 # no github sandbox is provisioned, GH_TOKEN is not required, and
@@ -655,6 +718,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.6 → sbxloop-0.5.8}/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.6 → sbxloop-0.5.8}/src/sbxloop/cli/tui.py

@@ -39,10 +39,12 @@ TASK_STATE_STYLES = {
 }
 
 # Compact one-liner lifecycle events (chat "system" messages).
-_LIFECYCLE_PREFIXES = ("run.", "task.", "phase.", "sandbox.", "gh.")
+_LIFECYCLE_PREFIXES = ("run.", "task.", "phase.", "sandbox.", "gh.", "policy.")
 
 # 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,12 @@ 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
+            or event.type == HostEventTypes.POLICY_DENY
+        ):
             style = "yellow"
         return Text(line, style=style, overflow="fold")
 
@@ -166,13 +176,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 +234,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 +271,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.6 → sbxloop-0.5.8}/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
 
@@ -42,6 +49,35 @@ class SandboxConfig(_ConfigModel):
     extra_allow_domains: list[str] = Field(default_factory=list)
 
 
+class PolicyConfig(_ConfigModel):
+    """Operator bounds for plan-declared egress.
+
+    The PLAN phase may request extra network allows for EXECUTE (each with a
+    justification). Requests are auto-granted just before EXECUTE only when
+    they match ``allow`` and no ``deny`` pattern; everything is event-logged
+    (``sbxloop logs RUN --type policy.``). Patterns are exact domains,
+    ``*.example.com`` wildcards (the domain and all subdomains), or ``*``
+    (everything). Empty ``allow`` — the default — means plans may only use
+    the always-reachable baseline (Copilot/GitHub hosts, PyPI, apt mirrors).
+    """
+
+    allow: list[str] = Field(default_factory=list)
+    deny: list[str] = Field(default_factory=list)
+
+    @field_validator("allow", "deny")
+    @classmethod
+    def _check_patterns(cls, value: list[str]) -> list[str]:
+        from sbxloop.policy import valid_pattern
+
+        value = [p.strip().lower() for p in value]
+        bad = [p for p in value if not valid_pattern(p, operator=True)]
+        if bad:
+            raise ValueError(
+                f"invalid egress pattern(s) {bad}: use a domain, *.domain wildcard, or *"
+            )
+        return value
+
+
 class GithubConfig(_ConfigModel):
     """The GitHub integration. ``repo`` is the gate: unset (the default)
     disables GitHub entirely — no github sandbox is provisioned, no GH_TOKEN
@@ -68,6 +104,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
@@ -98,8 +163,10 @@ class Config(_ConfigModel):
     worker_python: str = "/home/agent/.sbxloop/venv/bin/python"
     install_workers: bool = True
     sandbox: SandboxConfig = Field(default_factory=SandboxConfig)
+    policy: PolicyConfig = Field(default_factory=PolicyConfig)
     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.6 → sbxloop-0.5.8}/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
@@ -40,6 +41,7 @@ from sbxloop.events import EventBus, Hook, HostEventTypes
 from sbxloop.gh.ops import GithubOps
 from sbxloop.gh.reporter import GithubReporterHook
 from sbxloop.ids import new_run_id
+from sbxloop.policy import EgressGranter
 from sbxloop.sbx.cli import SbxCLI
 from sbxloop.sbx.pair import SandboxPair
 from sbxloop.sbx.provision import Provisioner
@@ -75,9 +77,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 +91,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:
@@ -124,6 +138,8 @@ class LoopEngine:
                         self.bus,
                         transport=self.config.worker_transport,
                         python=self.worker_python,
+                        role="agent",
+                        limits=self.config.limits,
                     )
                     github = (
                         WorkerClient(
@@ -131,6 +147,8 @@ class LoopEngine:
                             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
@@ -146,7 +164,10 @@ class LoopEngine:
                         phases = PhaseRunner(
                             agent, self.config, run_id, outcome, workdir=pair.agent_workdir
                         )
-                        state = self._run_phases(run_id, phases, deadline, pair)
+                        granter = EgressGranter(
+                            self.sbx, self.config, self.bus, run_id, pair.agent.name
+                        )
+                        state = self._run_phases(run_id, phases, deadline, pair, granter)
                         # 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.
@@ -249,12 +270,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(
@@ -301,7 +338,12 @@ class LoopEngine:
         self.bus.emit(HostEventTypes.RUN_DELIVER, run_id, repo=repo, pr=pr.number, url=pr.url)
 
     def _run_phases(
-        self, run_id: str, phases: PhaseRunner, deadline: float, pair: SandboxPair
+        self,
+        run_id: str,
+        phases: PhaseRunner,
+        deadline: float,
+        pair: SandboxPair,
+        granter: EgressGranter,
     ) -> RunState:
         tasks = self.store.get_tasks(run_id)
         if not tasks:
@@ -340,7 +382,7 @@ class LoopEngine:
                 self.store.update_task(run_id, task)
                 self._emit_task_end(run_id, task)
                 continue
-            self._run_task(run_id, phases, task, deadline, pair)
+            self._run_task(run_id, phases, task, deadline, pair, granter)
             if task.state == "failed":
                 failed_ids.add(task.spec.id)
 
@@ -356,6 +398,7 @@ class LoopEngine:
         task: TaskRecord,
         deadline: float,
         pair: SandboxPair,
+        granter: EgressGranter,
     ) -> None:
         budgets = self.config.budgets
         if task.state == "pending":
@@ -374,10 +417,18 @@ 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":
-                self._phase_execute_and_scrutinize(run_id, phases, task, budgets)
+                self._phase_execute_and_scrutinize(run_id, phases, task, granter)
             elif task.state == "verifying":
                 self._phase_verify(run_id, phases, task, budgets)
             elif task.state == "validating":
@@ -410,9 +461,14 @@ class LoopEngine:
         run_id: str,
         phases: PhaseRunner,
         task: TaskRecord,
-        budgets: object,
+        granter: EgressGranter,
     ) -> None:
         assert task.plan is not None
+        # Grant-late: plan-declared egress is applied at EXECUTE entry, not
+        # at plan time. Runs here (not in _phase_plan) so resumed tasks whose
+        # persisted state skips planning still get their grants on the
+        # freshly provisioned sandbox.
+        granter.apply(task.spec.id, [(egress.domain, egress.reason) for egress in task.plan.egress])
         started = time.time()
         result = phases.execute(task, task.plan)
         task.session_id = result.session_id
@@ -510,6 +566,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.6 → sbxloop-0.5.8}/src/sbxloop/engine/model.py

@@ -6,7 +6,7 @@ from graphlib import CycleError, TopologicalSorter
 from pathlib import Path
 from typing import Literal
 
-from pydantic import BaseModel, ConfigDict, Field, model_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
 RunState = Literal[
     "created",
@@ -95,12 +95,40 @@ class TaskGraph(_Model):
         return 1 + max(self._depth(by_id[d], by_id) for d in task.depends_on)
 
 
+class EgressSpec(_Model):
+    """One plan-declared network need: a domain EXECUTE must reach, and why.
+
+    Granted to the agent sandbox just before EXECUTE — but only within the
+    operator's ``[policy]`` bounds (checked at plan time, enforced again at
+    grant time). ``domain`` is a bare domain or ``*.domain`` wildcard; no
+    scheme, path, or port, and never the bare ``"*"``.
+    """
+
+    domain: str
+    reason: str = ""
+
+    @field_validator("domain")
+    @classmethod
+    def _check_domain(cls, value: str) -> str:
+        from sbxloop.policy import valid_pattern
+
+        value = value.strip().lower()
+        if not valid_pattern(value):
+            raise ValueError(
+                f"egress domain must be a domain or *.domain wildcard "
+                f"(no scheme/path/port), got {value!r}"
+            )
+        return value
+
+
 class PlanModel(_Model):
     """The agent's plan for one task."""
 
     steps: list[str]
     expected_artifacts: list[str] = Field(default_factory=list)
     verify_commands: list[str] = Field(default_factory=list)
+    # External domains EXECUTE needs beyond the baseline, with justification.
+    egress: list[EgressSpec] = Field(default_factory=list)
 
 
 class Issue(_Model):

{sbxloop-0.5.6 → sbxloop-0.5.8}/src/sbxloop/engine/phases.py

@@ -15,9 +15,10 @@ Session strategy per phase (a deliberate design decision):
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from typing import Literal, TypeVar
 
-from pydantic import BaseModel, ValidationError
+from pydantic import BaseModel
 
 from sbxloop.config import Config
 from sbxloop.engine.model import PlanModel, TaskGraph, TaskRecord, Verdict
@@ -99,16 +100,25 @@ class PhaseRunner:
         context: dict[str, str],
         *,
         permission_mode: Literal["auto", "read_only"] = "auto",
+        check: Callable[[ModelT], None] | None = None,
     ) -> ModelT:
-        """Run a JSON-expecting agent job; one retry with the validation error."""
+        """Run a JSON-expecting agent job; one retry with the validation error.
+
+        ``check`` runs host-side semantic validation on the parsed model and
+        raises ValueError to reject — same retry path as schema failures
+        (pydantic's ValidationError is a ValueError subclass).
+        """
         retry_context = ""
         last_error: Exception | None = None
         for _ in range(2):
             prompt = render(prompt_name, retry_context=retry_context, **context)
             result = self._agent_job(prompt, permission_mode=permission_mode, expect="json")
             try:
-                return model_cls.model_validate(result.output_json)
-            except ValidationError as exc:
+                model = model_cls.model_validate(result.output_json)
+                if check is not None:
+                    check(model)
+                return model
+            except ValueError as exc:  # includes pydantic's ValidationError
                 last_error = exc
                 retry_context = (
                     "\n## Previous attempt was invalid\n\n"
@@ -156,8 +166,33 @@ class PhaseRunner:
                 "acceptance_criteria": bullet_list(task.spec.acceptance_criteria),
                 "feedback": task.last_feedback or "(none — first attempt)",
             },
+            check=self._check_plan_egress,
         )
 
+    def _check_plan_egress(self, plan: PlanModel) -> None:
+        """Reject plans declaring egress outside the operator's bounds.
+
+        Feeds the retry loop, so the planner gets one chance to drop the
+        domain (or find a baseline-reachable alternative) before the run
+        fails — the "grant only within operator-set limits" guardrail.
+        """
+        from sbxloop.policy import effective_egress_bounds, egress_rejection
+
+        allow, deny = effective_egress_bounds(self.config)
+        problems = [
+            f"- {egress.domain}: {rejection}"
+            for egress in plan.egress
+            if (rejection := egress_rejection(egress.domain, allow, deny)) is not None
+        ]
+        if problems:
+            raise ValueError(
+                "plan-declared egress is outside the operator's bounds:\n"
+                + "\n".join(problems)
+                + "\nDrop these domains from `egress` (prefer baseline-reachable hosts: "
+                "PyPI, GitHub, apt mirrors). Only the operator can extend the bounds, "
+                "via [policy] allow in sbxloop.toml."
+            )
+
     def execute(self, task: TaskRecord, plan: PlanModel) -> JobResult:
         prompt = render(
             "execute",

{sbxloop-0.5.6 → sbxloop-0.5.8}/src/sbxloop/engine/prompts/execute.md

@@ -17,11 +17,13 @@ destroyed.
   project commands through `.venv/bin/...`.
 - If a tool or apt package is missing, you have passwordless sudo:
   `sudo apt-get install -y <package>`.
-- Network egress is allowlisted. PyPI, GitHub, and apt mirrors are
-  reachable; other hosts (npm registry, arbitrary APIs) may not be. If a
-  download times out repeatedly, say so in your summary instead of
-  retrying forever — the allowlist is user configuration, not something
-  you can change.
+- Network egress is allowlisted. PyPI, GitHub, apt mirrors, and any
+  domains the plan declared as `egress` are reachable; other hosts (npm
+  registry, arbitrary APIs) may not be. If a download times out
+  repeatedly, treat the host as blocked: name the exact blocked domain in
+  your summary — a re-plan can declare it — instead of retrying forever.
+  The allowlist is operator-bounded configuration, not something you can
+  change from in here.
 
 ## Overall outcome
 

{sbxloop-0.5.6 → sbxloop-0.5.8}/src/sbxloop/engine/prompts/plan.md

@@ -26,17 +26,27 @@ Respond with exactly one fenced JSON block:
 {
   "steps": ["specific action 1", "specific action 2"],
   "expected_artifacts": ["files or outputs this task should produce"],
-  "verify_commands": ["shell commands that exit 0 only when the work is correct"]
+  "verify_commands": ["shell commands that exit 0 only when the work is correct"],
+  "egress": [{"domain": "registry.npmjs.org", "reason": "npm install for the build"}]
 }
 ```
 
 Steps must be specific enough that an executor with no other context can
 follow them. Include the task's own verification ideas in `verify_commands`.
 
+`egress` declares external domains the executor will need to reach beyond
+the baseline. PyPI, GitHub, and apt mirrors are always reachable — never
+declare those. Each entry needs a short justification; use `[]` when the
+baseline suffices (the common case). Domains only — no scheme, path, or
+port; `*.example.com` wildcards are accepted. Declarations are auto-granted
+only within an operator-set allowlist: a request outside it fails this
+plan's validation, so prefer baseline-reachable alternatives.
+
 Environment facts to plan around: Debian/Ubuntu VM; the system Python is
 externally managed (PEP 668), so Python dependencies belong in a project
 virtualenv (`python3 -m venv .venv`) and commands — including your
 `verify_commands` — should use `.venv/bin/...` paths; missing apt packages
 can be installed with passwordless sudo; network egress is allowlisted
-(PyPI, GitHub, and apt mirrors are reachable — other registries may not be).
+(PyPI, GitHub, and apt mirrors are reachable — declare anything else in
+`egress`).
 $retry_context

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

@@ -82,6 +82,8 @@ class HostEventTypes:
     TASK_END = "task.end"
     PHASE_START = "phase.start"
     PHASE_END = "phase.end"
+    POLICY_ALLOW = "policy.allow"
+    POLICY_DENY = "policy.deny"
     SANDBOX_PROVISION_START = "sandbox.provision_start"
     SANDBOX_READY = "sandbox.ready"
     SANDBOX_CLEANUP = "sandbox.cleanup"

sbxloop-0.5.8/src/sbxloop/policy.py

@@ -0,0 +1,167 @@
+"""Plan-declared network egress: bounds checking and grant-late application.
+
+The PLAN phase may declare external domains a task needs during EXECUTE
+(``PlanModel.egress``). Declarations are validated against operator-set
+bounds (``[policy] allow`` / ``[policy] deny`` in sbxloop.toml) at plan time,
+and granted to the agent sandbox — via ``sbx policy allow network <domain>
+--sandbox <agent>`` — only just before EXECUTE runs ("grant late"). Every
+grant and refusal is emitted as a ``policy.*`` run event, so the persisted
+event log doubles as an egress audit trail (``sbxloop logs RUN --type
+policy.``).
+
+sbx 0.35 has no primitive for revoking or narrowing an allow on a live
+sandbox, so grants are additive for the sandbox's lifetime — SCRUTINIZE and
+VERIFY inherit whatever EXECUTE was granted. Grants never outlive a run:
+sandboxes are removed at run end, and resume provisions fresh ones. If a
+future sbx grows revocation, this module is where "revoke early" lands.
+
+Pattern semantics (ours, not sbx's — bounds govern what may be *requested*;
+the requested domain is passed to sbx verbatim): a pattern is an exact
+domain, a wildcard ``*.example.com`` (covers ``example.com`` and every
+subdomain), or the operator-only ``*`` (covers everything).
+"""
+
+from __future__ import annotations
+
+import re
+
+from sbxloop.config import Config
+from sbxloop.errors import SbxError
+from sbxloop.events import EventBus, HostEventTypes
+from sbxloop.sbx.cli import SbxCLI
+
+DOMAIN_PATTERN_RE = re.compile(r"(?:\*\.)?(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}")
+
+# Hosts the plan/execute prompts advertise as reachable (the user's balanced
+# preset covers PyPI and apt mirrors). A plan declaring one of these is
+# in-bounds without operator configuration — granting it per-sandbox cannot
+# expand egress beyond what the prompts already promise, and makes the
+# promise hold even under a preset that lacks the host.
+PROMPT_ADVERTISED_DOMAINS = (
+    "pypi.org",
+    "files.pythonhosted.org",
+    "deb.debian.org",
+    "security.debian.org",
+    "archive.ubuntu.com",
+    "ports.ubuntu.com",
+)
+
+
+def valid_pattern(pattern: str, *, operator: bool = False) -> bool:
+    """Whether ``pattern`` is a well-formed domain pattern.
+
+    ``operator=True`` additionally permits the bare ``"*"`` — meaningful as
+    an operator bound ("grant anything the plan asks for") but rejected in
+    plan declarations, which must name what they need.
+    """
+    if pattern == "*":
+        return operator
+    return DOMAIN_PATTERN_RE.fullmatch(pattern) is not None
+
+
+def pattern_covers(pattern: str, domain: str) -> bool:
+    """Whether a bounds pattern covers a requested domain (or wildcard)."""
+    pattern = pattern.lower()
+    domain = domain.lower()
+    if pattern == "*" or pattern == domain:
+        return True
+    if not pattern.startswith("*."):
+        return False
+    base = pattern[2:]
+    requested = domain[2:] if domain.startswith("*.") else domain
+    return requested == base or requested.endswith(f".{base}")
+
+
+def egress_rejection(domain: str, allow: list[str], deny: list[str]) -> str | None:
+    """Why ``domain`` may not be granted, or None when it is in bounds."""
+    for pattern in deny:
+        if pattern_covers(pattern, domain):
+            return f"matches [policy] deny pattern {pattern!r}"
+    if not any(pattern_covers(pattern, domain) for pattern in allow):
+        return "not covered by [policy] allow in sbxloop.toml"
+    return None
+
+
+def effective_egress_bounds(config: Config) -> tuple[list[str], list[str]]:
+    """The (allow, deny) bounds plan-declared egress is checked against.
+
+    The allow side is the operator's ``[policy] allow`` plus everything the
+    agent sandbox can already reach (its provision-time baseline and the
+    prompt-advertised hosts) — declaring an already-reachable domain must
+    never fail a plan. ``[policy] deny`` still wins over all of it.
+    """
+    from sbxloop.sbx.provision import AGENT_ALLOW_DOMAINS
+
+    allow = [
+        *AGENT_ALLOW_DOMAINS,
+        *config.sandbox.extra_allow_domains,
+        *PROMPT_ADVERTISED_DOMAINS,
+        *config.policy.allow,
+    ]
+    return allow, list(config.policy.deny)
+
+
+class EgressGranter:
+    """Applies one run's plan-declared egress grants to the agent sandbox.
+
+    Grants are applied at EXECUTE entry, not at plan time — the tightest
+    point sbx's grant-only policy model permits. Idempotent per domain: the
+    provision-time baseline is pre-seeded, and revision loops re-entering
+    EXECUTE do not re-grant. Out-of-bounds declarations are refused with a
+    ``policy.deny`` event; plan validation normally rejects them, so a deny
+    here means the operator tightened bounds after the plan was persisted
+    (e.g. across a resume).
+    """
+
+    def __init__(self, cli: SbxCLI, config: Config, bus: EventBus, run_id: str, sandbox: str):
+        from sbxloop.sbx.provision import AGENT_ALLOW_DOMAINS
+
+        self.cli = cli
+        self.bus = bus
+        self.run_id = run_id
+        self.sandbox = sandbox
+        self.allow, self.deny = effective_egress_bounds(config)
+        self._granted = {
+            d.lower() for d in (*AGENT_ALLOW_DOMAINS, *config.sandbox.extra_allow_domains)
+        }
+
+    def apply(self, task_id: str, egress: list[tuple[str, str]]) -> None:
+        """Grant each declared (domain, justification), event-logging both
+        grants and refusals. sbx failures propagate (infrastructure error)."""
+        for domain, reason in egress:
+            domain = domain.lower()
+            rejection = egress_rejection(domain, self.allow, self.deny)
+            if rejection is not None:
+                self.bus.emit(
+                    HostEventTypes.POLICY_DENY,
+                    self.run_id,
+                    task_id=task_id,
+                    domain=domain,
+                    sandbox=self.sandbox,
+                    message=f"egress refused: {domain} — {rejection}",
+                )
+                continue
+            if domain in self._granted:
+                continue
+            try:
+                self.cli.policy_allow(domain, sandbox=self.sandbox)
+            except SbxError:
+                self.bus.emit(
+                    HostEventTypes.POLICY_DENY,
+                    self.run_id,
+                    task_id=task_id,
+                    domain=domain,
+                    sandbox=self.sandbox,
+                    message=f"egress grant failed: {domain} — sbx policy allow errored",
+                )
+                raise
+            self._granted.add(domain)
+            self.bus.emit(
+                HostEventTypes.POLICY_ALLOW,
+                self.run_id,
+                task_id=task_id,
+                domain=domain,
+                reason=reason,
+                sandbox=self.sandbox,
+                message=f"egress granted: {domain} — {reason or 'no justification given'}",
+            )

{sbxloop-0.5.6 → sbxloop-0.5.8}/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 ----------------------------------------------------