Skip to content
Python

Sandbox refusal: no reconnect loop; image check follows the driver (docker or podman) and stays out of remote gateways

Devika Vermaab4d6dda77c4
diff --git a/coworker/sandbox/providers/openshell.py b/coworker/sandbox/providers/openshell.py
index 4379faaa..a76f9da8 100644
--- a/coworker/sandbox/providers/openshell.py
+++ b/coworker/sandbox/providers/openshell.py
@@ -99,7 +99,7 @@ def preflight() -> dict[str, Any]:
if image_present() is False:
raise OpenShellImageMissing(
f"{IMAGE_MISSING_PREFIX} (about 5 GB, one time). Run `openworker machine sandbox setup`, "
- f"or `docker pull {sandbox_image()}`, then start the session again."
+ f"or `{image_tool() or 'docker'} pull {sandbox_image()}`, then start the session again."
)
return {"version": version}
@@ -117,19 +117,41 @@ def active_driver() -> str:
return ""
-def image_present(image: Optional[str] = None) -> Optional[bool]:
- """Whether the base image is on this machine: True or False when the gateway uses the
- Docker driver and the `docker` command is here to ask, None when it cannot be told
- (another driver, such as the MicroVM one on a Mac, or no `docker` on PATH). The check is
- keyed on the driver, not the operating system: the same image serves Linux, WSL and
- macOS, and only the driver knows where images live."""
- if active_driver() != "docker":
+# The command that holds a driver's images, for the drivers whose store is on this machine.
+_IMAGE_TOOLS = {"docker": "docker", "podman": "podman"}
+
+
+def image_tool() -> Optional[str]:
+ """The `docker`/`podman` command to ask about (and pull) images, or None when the
+ question cannot be answered here: the gateway is remote, its driver keeps images
+ elsewhere (Kubernetes, the MicroVM driver on a Mac), or the command is not on PATH."""
+ if _gateway_is_remote():
return None
- docker = shutil.which("docker")
- if docker is None:
+ name = _IMAGE_TOOLS.get(active_driver())
+ return name if name and shutil.which(name) else None
+
+
+def _gateway_is_remote() -> bool:
+ try:
+ home = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config") / "openshell"
+ name = (home / "active_gateway").read_text(encoding="utf-8").strip()
+ meta = json.loads((home / "gateways" / name / "metadata.json").read_text(encoding="utf-8"))
+ return bool(meta.get("is_remote"))
+ except (OSError, ValueError):
+ return False
+
+
+def image_present(image: Optional[str] = None) -> Optional[bool]:
+ """Whether the base image is on this machine: True or False when the gateway's driver
+ keeps images here and can be asked (`docker`/`podman image inspect`), None when it
+ cannot be told. The check is keyed on the driver, not the operating system: the same
+ image serves Linux, WSL and macOS (amd64 and arm64), and only the driver knows where
+ images live. None never refuses anything: the first create then pulls as before."""
+ tool = image_tool()
+ if tool is None:
return None
done = subprocess.run(
- [docker, "image", "inspect", image or sandbox_image()],
+ [tool, "image", "inspect", image or sandbox_image()],
stdin=subprocess.DEVNULL, capture_output=True, text=True, timeout=30,
)
return done.returncode == 0
diff --git a/coworker/sandbox/setup_cmd.py b/coworker/sandbox/setup_cmd.py
index e11587cb..9e621db0 100644
--- a/coworker/sandbox/setup_cmd.py
+++ b/coworker/sandbox/setup_cmd.py
@@ -68,8 +68,8 @@ def checks() -> list[tuple[str, bool, str]]:
out.append(("the `grpcio` package is installed", grpc_ok, "" if grpc_ok else "pip install 'openworker[openshell]'"))
if gateway_ok and exe:
present = openshell.image_present()
- if present is not None: # only the Docker driver can be asked; other drivers get no row
- out.append((IMAGE_ROW, present, "" if present else f"docker pull {openshell.sandbox_image()}"))
+ if present is not None: # only a local docker/podman driver can be asked; others get no row
+ out.append((IMAGE_ROW, present, "" if present else f"{openshell.image_tool() or 'docker'} pull {openshell.sandbox_image()}"))
configured = app_config.load_config().sandbox_provider
out.append(("this machine is set to use OpenShell", configured == "openshell", f"sandbox_provider = {configured!r} in {app_config.global_config_path()}"))
return out
@@ -109,11 +109,11 @@ def _offer_image_download(rows: dict[str, bool], confirm: Callable[[str], bool],
own progress and no time limit. Returns an exit code to stop with, or None to go on."""
if rows.get(IMAGE_ROW, True):
return None
- image = openshell.sandbox_image()
- print_fn(f"The sandbox base image is not on this machine. It is about 5 GB and is downloaded once;\nuntil then the first session cannot start:\n docker pull {image}")
+ image, tool = openshell.sandbox_image(), openshell.image_tool() or "docker"
+ print_fn(f"The sandbox base image is not on this machine. It is about 5 GB and is downloaded once;\nuntil then the first session cannot start:\n {tool} pull {image}")
if not confirm("Download it now? (10 to 20 minutes on a slow connection)"):
return 1
- if subprocess.run(["docker", "pull", image], stdin=subprocess.DEVNULL).returncode != 0:
+ if subprocess.run([tool, "pull", image], stdin=subprocess.DEVNULL).returncode != 0:
print_fn("the download failed; nothing else was changed")
return 1
return None
diff --git a/coworker/server/app.py b/coworker/server/app.py
index a9061fee..be43336f 100644
--- a/coworker/server/app.py
+++ b/coworker/server/app.py
@@ -48,6 +48,9 @@ def _origin_allowed(origin: str | None) -> bool:
# process can reach it), so bound frames, messages, and per-connection request rate before
# building model content or starting a turn.
_WS_MAX_FRAME_BYTES = 16 * 1024 * 1024
+# Close code for a session socket whose engine could not be built (a refused sandbox, a
+# failed build). Private-use range; the client treats it as final and does not reconnect.
+WS_CLOSE_SESSION_REFUSED = 4403
_WS_RATE_LIMIT_COUNT = 30
_WS_RATE_LIMIT_WINDOW_SECONDS = 10.0
_MAX_MESSAGE_TEXT_CHARS = 200_000
@@ -2840,9 +2843,11 @@ def create_app(manager: SessionManager) -> FastAPI:
except Exception as exc:
# A refused sandbox (OpenShell not usable, its image not downloaded, the
# per-machine cap) or a failed build: the reason goes to the session's own
- # view, and the socket closes cleanly instead of dying in the ASGI stack.
+ # view, and the socket closes cleanly instead of dying in the ASGI stack. The
+ # close code tells the client this is final: reconnecting would only repeat
+ # the refusal every few seconds (the client retries any other close).
await ws.send_json({"type": "error", "data": {"error": str(exc)}})
- await ws.close()
+ await ws.close(code=WS_CLOSE_SESSION_REFUSED, reason="session refused")
return
if sandbox_provider and engine is not None:
info = getattr(getattr(engine, "sandbox_workspace", None), "describe", dict)()
diff --git a/surfaces/gui/src/App.tsx b/surfaces/gui/src/App.tsx
index 394ea738..814bcc88 100644
--- a/surfaces/gui/src/App.tsx
+++ b/surfaces/gui/src/App.tsx
@@ -251,6 +251,9 @@ export function App() {
// OPE-206: the provider name while this session's sandbox is being built (the socket
// is open, `ready` has not come yet); null otherwise. Drives the waiting row.
const [preparingSandbox, setPreparingSandbox] = useState<string | null>(null);
+ // The server refused to build this session (its sandbox cannot be used) and closed the
+ // socket for good: no reconnect strip, the error notice in the transcript says why.
+ const [sessionRefused, setSessionRefused] = useState(false);
const [running, setRunning] = useState(false);
// Transient "Compacting context…" indicator (OPE-27): set by the `compacting` event,
// cleared by whatever the engine emits next — the summarizer call is otherwise a
@@ -880,6 +883,7 @@ export function App() {
break;
case "ready":
setPreparingSandbox(null);
+ setSessionRefused(false);
setConnected(true);
if (d.model) setModel(d.model);
if (d.mode) setMode(d.mode);
@@ -1181,7 +1185,9 @@ export function App() {
setConnected(false);
setPreparingSandbox(null);
},
+ onRefused: () => setSessionRefused(true),
}, machine);
+ setSessionRefused(false); // a fresh socket: the previous refusal, if any, is history
sessionRef.current = session;
return () => session.close();
// NOTE: `workspace` is intentionally NOT a dependency. Every real workspace change
@@ -2348,7 +2354,7 @@ export function App() {
}}
/>
)}
- {!connected && !booting && !currentRowOffline && !(isCloudMode() && !machine) && (
+ {!connected && !booting && !sessionRefused && !currentRowOffline && !(isCloudMode() && !machine) && (
<div className="reconnecting-strip" data-testid="session-reconnecting" role="status">
{machine ? t("misc.app.machine_reconnecting") : t("misc.app.reconnecting")}
<span className="reconnecting-sub">
diff --git a/surfaces/gui/src/api.ts b/surfaces/gui/src/api.ts
index d376352c..7c49c347 100644
--- a/surfaces/gui/src/api.ts
+++ b/surfaces/gui/src/api.ts
@@ -2795,8 +2795,15 @@ export type Handlers = {
* should reload what it may have missed (transcript tail, parked prompts). */
onOpen?: (reconnected: boolean) => void;
onClose?: () => void;
+ /** The server refused to build this session (its sandbox cannot be used) and closed
+ * the socket for good (close code 4403). No reconnect follows: retrying would only
+ * repeat the refusal every few seconds. The reason arrived as an `error` event. */
+ onRefused?: () => void;
};
+/** Close code the server uses for a session it refused to build (see app.py). */
+export const WS_CLOSE_SESSION_REFUSED = 4403;
+
/** Reconnect backoff for a dropped session socket: 1s, 2s, 4s, 8s, then 15s. */
export const SESSION_RECONNECT_MS = [1000, 2000, 4000, 8000, 15000];
@@ -2850,9 +2857,14 @@ export class Session {
this.flush();
this.handlers.onOpen?.(reconnected);
};
- ws.onclose = () => {
+ ws.onclose = (ev) => {
this.handlers.onClose?.();
if (this.closed) return;
+ if (ev.code === WS_CLOSE_SESSION_REFUSED) {
+ this.closed = true; // final: the server said this session cannot be built as configured
+ this.handlers.onRefused?.();
+ return;
+ }
const delay = SESSION_RECONNECT_MS[Math.min(this.attempts, SESSION_RECONNECT_MS.length - 1)];
this.attempts += 1;
this.timer = window.setTimeout(() => this.connect(), delay);
diff --git a/tests/test_sandbox_openshell.py b/tests/test_sandbox_openshell.py
index ff2e5f38..44ab51ea 100644
--- a/tests/test_sandbox_openshell.py
+++ b/tests/test_sandbox_openshell.py
@@ -112,6 +112,7 @@ def test_a_missing_base_image_is_refused_before_a_create_can_hang_on_it(monkeypa
# OPE-205: the first `sandbox create` pulls about 5 GB; on a slow link that outlives the
# create's timeout and the session hangs for ten minutes with no word about why. So the
# image is checked up front, with a message that names the download.
+ monkeypatch.setattr(openshell, "_gateway_is_remote", lambda: False)
monkeypatch.setattr(openshell.shutil, "which", lambda name: f"/usr/bin/{name}")
missing = {"--version": _OK_VERSION, "status": _CONNECTED, "gateway": _DOCKER_GATEWAY, "image": ("Error: No such image", 1)}
monkeypatch.setattr(openshell.subprocess, "run", _fake_cli(missing))
@@ -139,6 +140,26 @@ def test_a_missing_base_image_is_refused_before_a_create_can_hang_on_it(monkeypa
assert openshell.image_present() is True and seen[-1] == "registry.example.com/team/agent:2"
+def test_the_image_check_follows_the_driver_and_stays_out_of_remote_gateways(monkeypatch):
+ # Podman keeps its own image store, so it is asked with its own command; the same
+ # image serves both, and both hang the first session the same way when it is absent.
+ monkeypatch.setattr(openshell, "_gateway_is_remote", lambda: False)
+ monkeypatch.setattr(openshell.shutil, "which", lambda name: f"/usr/bin/{name}")
+ podman = ('{"compute_drivers": [{"name": "podman"}]}', 0)
+ seen: list[list[str]] = []
+ monkeypatch.setattr(openshell.subprocess, "run", lambda argv, **kw: seen.append(argv) or _fake_cli({"gateway": podman, "image": ("", 1)})(argv, **kw))
+ assert openshell.image_tool() == "podman"
+ assert openshell.image_present() is False and seen[-1][:3] == ["podman", "image", "inspect"]
+ monkeypatch.setattr(openshell.subprocess, "run", _fake_cli({"--version": _OK_VERSION, "status": _CONNECTED, "gateway": podman, "image": ("", 1)}))
+ with pytest.raises(openshell.OpenShellImageMissing, match="podman pull"):
+ openshell.preflight()
+ # A remote gateway keeps its images on another machine: a local store says nothing
+ # about it, so the check answers "cannot tell" and never refuses.
+ monkeypatch.setattr(openshell, "_gateway_is_remote", lambda: True)
+ assert openshell.image_tool() is None and openshell.image_present() is None
+ assert openshell.preflight() == {"version": openshell.PINNED_VERSION}
+
+
def test_registry_counts_caps_and_forgets(tmp_path, monkeypatch):
from coworker.sandbox.registry import SandboxLimitReached, SandboxRegistry
diff --git a/tests/test_sandbox_selection.py b/tests/test_sandbox_selection.py
index 9c10fce9..f60dd34e 100644
--- a/tests/test_sandbox_selection.py
+++ b/tests/test_sandbox_selection.py
@@ -162,6 +162,7 @@ def test_setup_offers_the_base_image_download_and_runs_nothing_when_refused(tmp_
monkeypatch.setattr(setup_cmd.sys, "platform", "linux")
monkeypatch.setattr(setup_cmd, "checks", lambda: _all_but_the_image(setup_cmd))
monkeypatch.setattr(setup_cmd.openshell, "sandbox_image", lambda: "ghcr.io/example/base@sha256:abc")
+ monkeypatch.setattr(setup_cmd.openshell, "image_tool", lambda: "docker")
ran: list[list[str]] = []
monkeypatch.setattr(setup_cmd.subprocess, "run", lambda argv, **kw: ran.append(argv) or type("Done", (), {"returncode": 0})())
asked: list[str] = []
@@ -184,6 +185,7 @@ def test_setup_on_a_mac_still_offers_the_download(tmp_path, monkeypatch):
monkeypatch.setenv("COWORKER_STATE_DIR", str(tmp_path))
monkeypatch.setattr(setup_cmd.sys, "platform", "darwin")
monkeypatch.setattr(setup_cmd, "checks", lambda: _all_but_the_image(setup_cmd))
+ monkeypatch.setattr(setup_cmd.openshell, "image_tool", lambda: "docker")
ran: list[list[str]] = []
monkeypatch.setattr(setup_cmd.subprocess, "run", lambda argv, **kw: ran.append(argv) or type("Done", (), {"returncode": 0})())
said: list[str] = []
@@ -202,9 +204,10 @@ def test_status_shows_a_missing_image_as_its_own_row_not_as_a_gateway_problem(tm
monkeypatch.setattr(setup_cmd, "openshell_problem", lambda fresh=False: f"{setup_cmd.openshell.IMAGE_MISSING_PREFIX} (about 5 GB, one time). Run `docker pull x`.")
monkeypatch.setattr(setup_cmd.openshell, "image_present", lambda image=None: False)
monkeypatch.setattr(setup_cmd.openshell, "sandbox_image", lambda: "x")
+ monkeypatch.setattr(setup_cmd.openshell, "image_tool", lambda: "podman") # the hint names the driver's own tool
rows = {what: (ok, detail) for what, ok, detail in setup_cmd.checks()}
assert rows["the gateway is running"] == (True, "") # the gateway is fine; only the image is missing
- assert rows[setup_cmd.IMAGE_ROW] == (False, "docker pull x")
+ assert rows[setup_cmd.IMAGE_ROW] == (False, "podman pull x")
# Another driver: Docker cannot be asked, so no row rather than a wrong one.
monkeypatch.setattr(setup_cmd, "openshell_problem", lambda fresh=False: None)
monkeypatch.setattr(setup_cmd.openshell, "image_present", lambda image=None: None)
diff --git a/tests/test_session_socket_sandbox_build.py b/tests/test_session_socket_sandbox_build.py
index 671baaf8..15334be8 100644
--- a/tests/test_session_socket_sandbox_build.py
+++ b/tests/test_session_socket_sandbox_build.py
@@ -69,11 +69,16 @@ def test_a_refused_sandbox_is_reported_on_the_socket_not_as_a_server_error(tmp_p
monkeypatch.setattr(mgr, "get_engine", refuse)
client = TestClient(create_app(mgr))
+ from starlette.websockets import WebSocketDisconnect
+
+ from coworker.server.app import WS_CLOSE_SESSION_REFUSED
+
with client.websocket_connect("/ws/session/s-refused?agent=cowork") as ws:
assert ws.receive_json()["type"] == "sandbox_preparing"
assert ws.receive_json() == {"type": "error", "data": {"error": refusal}}
- with pytest.raises(Exception): # the server closed the socket cleanly
+ with pytest.raises(WebSocketDisconnect) as closed: # closed cleanly, with the "final" code
ws.receive_json()
+ assert closed.value.code == WS_CLOSE_SESSION_REFUSED # so the client does not retry the refusal
def test_pending_sandbox_build_reads_the_config_and_knows_an_existing_engine(tmp_path, monkeypatch):