Skip to content
Python

Session socket: build the engine (and its sandbox) off the event loop, and say so (OPE-206)

Devika Verma5e16e26b1d76
diff --git a/coworker/server/app.py b/coworker/server/app.py
index 504f92ac..a9061fee 100644
--- a/coworker/server/app.py
+++ b/coworker/server/app.py
@@ -2812,20 +2812,46 @@ def create_app(manager: SessionManager) -> FastAPI:
mcp_tools = await manager.prepare_mcp_tools(
session_id, workspace=workspace, agent=agent
)
- engine = manager.get_engine(
- session_id,
- workspace=workspace,
- agent=agent,
- approver=approver,
- extra_tools=mcp_tools,
- directory_requester=directory_requester,
- plan_approver=plan_approver,
- question_asker=question_asker,
- tool_requester=tool_requester,
- team_approver=team_approver,
- items_approver=items_approver,
- connector_requester=connector_requester,
- )
+ # Building the engine can mean building a sandbox: with OpenShell, a container is
+ # created, its runner started and its mounts verified, which takes seconds (and on
+ # first use, minutes). Done on the event loop that wait froze the whole server, so
+ # the GUI saw its health checks fail and showed the app-wide "Starting OpenWorker…"
+ # screen instead of this session (OPE-206). So: say what is happening on THIS
+ # socket, build on a worker thread, and report the outcome here too.
+ sandbox_provider = manager.pending_sandbox_build(session_id)
+ if sandbox_provider:
+ await ws.send_json({"type": "sandbox_preparing", "data": {"provider": sandbox_provider}})
+ try:
+ engine = await asyncio.to_thread(
+ manager.get_engine,
+ session_id,
+ workspace=workspace,
+ agent=agent,
+ approver=approver,
+ extra_tools=mcp_tools,
+ directory_requester=directory_requester,
+ plan_approver=plan_approver,
+ question_asker=question_asker,
+ tool_requester=tool_requester,
+ team_approver=team_approver,
+ items_approver=items_approver,
+ connector_requester=connector_requester,
+ )
+ 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.
+ await ws.send_json({"type": "error", "data": {"error": str(exc)}})
+ await ws.close()
+ return
+ if sandbox_provider and engine is not None:
+ info = getattr(getattr(engine, "sandbox_workspace", None), "describe", dict)()
+ await ws.send_json(
+ {
+ "type": "sandbox_ready",
+ "data": {key: info.get(key) for key in ("provider", "enforcement", "reason", "sandbox") if info.get(key) is not None},
+ }
+ )
if engine is None:
await ws.send_json(
{
diff --git a/coworker/server/manager.py b/coworker/server/manager.py
index 4d311829..a1993419 100644
--- a/coworker/server/manager.py
+++ b/coworker/server/manager.py
@@ -304,6 +304,11 @@ class SessionManager:
if self.default_workspace:
self.session_store.touch_workspace(self.default_workspace)
self._engines: dict[str, TurnEngine] = {}
+ # One build at a time per session. `get_engine` now runs off the event loop for a
+ # socket connect (OPE-206), so two connects to the same session could otherwise
+ # each build an engine, and with OpenShell each build is a container.
+ self._engine_build_locks: dict[str, threading.Lock] = {}
+ self._engine_build_locks_guard = threading.Lock()
# Sandboxes left behind by a server that died: removed once, in the background, at
# start (design doc, OPE-200 "sandbox lifetime"). Cheap when there are none.
threading.Thread(target=self._reap_sandboxes, name="sandbox-reap", daemon=True).start()
@@ -693,7 +698,33 @@ class SessionManager:
return record.workspace or None
return self.resolve_workspace(workspace)
- def get_engine(
+ def pending_sandbox_build(self, session_id: str) -> str:
+ """The sandbox provider a NEW engine for this session would be built with, or ""
+ when the engine exists already or commands would run directly. Reads the config
+ only, no preflight: it is asked on the event loop, before the build (OPE-206)."""
+ if session_id in self._engines:
+ return ""
+ from ..sandbox.selection import is_headless
+ from ..sandbox.workspace import DIRECT, OPENSHELL, PROVIDER_ENV
+
+ chosen = (os.environ.get(PROVIDER_ENV) or load_config().sandbox_provider or "").strip().lower()
+ if chosen:
+ return "" if chosen == DIRECT else chosen
+ return OPENSHELL if is_headless() else ""
+
+ def _engine_build_lock(self, session_id: str) -> threading.Lock:
+ with self._engine_build_locks_guard:
+ return self._engine_build_locks.setdefault(session_id, threading.Lock())
+
+ def get_engine(self, session_id: str, **kwargs: Any) -> Optional[TurnEngine]:
+ """The session's engine, built on first use. A build is serialized per session
+ (see `_engine_build_locks`); an engine that exists is returned without waiting."""
+ if session_id in self._engines:
+ return self._build_or_get_engine(session_id, **kwargs)
+ with self._engine_build_lock(session_id):
+ return self._build_or_get_engine(session_id, **kwargs)
+
+ def _build_or_get_engine(
self,
session_id: str,
*,
diff --git a/surfaces/gui/src/App.tsx b/surfaces/gui/src/App.tsx
index 27507a85..394ea738 100644
--- a/surfaces/gui/src/App.tsx
+++ b/surfaces/gui/src/App.tsx
@@ -248,6 +248,9 @@ export function App() {
const [surfaces, setSurfaces] = useState<SurfaceVisibility>({ cowork: true, chat: false, code: false });
const [mode, setMode] = useState("interactive");
const [connected, setConnected] = useState(false);
+ // 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);
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
@@ -864,7 +867,19 @@ export function App() {
// silent no-op / failure prompt) — the transient must never outlive it.
if (ev.type !== "compacting") setCompacting(false);
switch (ev.type) {
+ case "sandbox_preparing":
+ setPreparingSandbox(d.provider || "sandbox");
+ break;
+ case "sandbox_ready":
+ setPreparingSandbox(null);
+ // One quiet line in the transcript: which wall this session's commands are behind.
+ setItems((p) => [
+ ...p,
+ { kind: "notice", tone: "info", text: t("app.notice.sandbox_ready", { detail: d.reason || d.provider || "" }) },
+ ]);
+ break;
case "ready":
+ setPreparingSandbox(null);
setConnected(true);
if (d.model) setModel(d.model);
if (d.mode) setMode(d.mode);
@@ -1091,6 +1106,7 @@ export function App() {
setItems((p) => [...p, { kind: "notice", tone: "warn", text: t("app.notice.interrupted") }]);
break;
case "error":
+ setPreparingSandbox(null); // a refused or failed sandbox build arrives here
flushPartialStream();
setItems((p) => [
...p,
@@ -1161,7 +1177,10 @@ export function App() {
sessionRef.current?.userMessage(p.text, p.attachments, p.model, p.skill);
}
},
- onClose: () => setConnected(false),
+ onClose: () => {
+ setConnected(false);
+ setPreparingSandbox(null);
+ },
}, machine);
sessionRef.current = session;
return () => session.close();
@@ -2251,6 +2270,11 @@ export function App() {
<ThinkingBlock text={reasoningStream} live />
</div>
)}
+ {/* OPE-206: the sandbox for this session is being built (a container, its
+ runner, its mounts). Not a turn, so `running` is false; the row says so. */}
+ {preparingSandbox && !connected && (
+ <WaitingForAgent label={t("app.preparing_sandbox", { provider: preparingSandbox })} />
+ )}
{/* Compaction runs between provider turns (nothing streams during it), so
the transient takes over the waiting slot with a specific label. */}
{running && compacting && <WaitingForAgent label={t("app.compacting_context")} />}
diff --git a/surfaces/gui/src/locales/en.json b/surfaces/gui/src/locales/en.json
index e4285be1..e1e8fdb8 100644
--- a/surfaces/gui/src/locales/en.json
+++ b/surfaces/gui/src/locales/en.json
@@ -456,6 +456,7 @@
"interrupted": "Interrupted.",
"error": "Error: ",
"context_compacted": "Context compacted",
+ "sandbox_ready": "Sandbox ready: {{detail}}",
"continuation": "Reply cut off at the output-token limit; asking the model to continue.",
"truncated": "Stopped: reply cut off at the output-token limit with no action.",
"input_rejected": "That message was rejected.",
@@ -464,6 +465,7 @@
"jump_to_latest": "Jump to latest",
"waiting_for_agent": "Waiting for agent...",
"compacting_context": "Compacting context…",
+ "preparing_sandbox": "Preparing the {{provider}} sandbox for this session… (a Linux container with only this session's folders)",
"allow_anyway_message": "I reviewed the blocked {{name}} action — go ahead with it exactly as proposed.",
"temp_folder_failed": "Could not create a temporary folder.",
"temp_folder_created": "Temporary folder created",
diff --git a/surfaces/gui/src/locales/zh.json b/surfaces/gui/src/locales/zh.json
index 7d35b7ec..4fe83576 100644
--- a/surfaces/gui/src/locales/zh.json
+++ b/surfaces/gui/src/locales/zh.json
@@ -448,6 +448,7 @@
"interrupted": "已中断。",
"error": "错误:",
"context_compacted": "上下文已压缩",
+ "sandbox_ready": "沙箱已就绪:{{detail}}",
"continuation": "回复在输出上限处被截断,正在让模型继续。",
"truncated": "已停止:回复在输出上限处被截断且未执行任何操作。",
"input_rejected": "该消息已被拒绝。",
@@ -456,6 +457,7 @@
"jump_to_latest": "跳到最新",
"waiting_for_agent": "正在等待 agent…",
"compacting_context": "正在压缩上下文…",
+ "preparing_sandbox": "正在为此会话准备 {{provider}} 沙箱…(一个仅包含此会话文件夹的 Linux 容器)",
"allow_anyway_message": "我已审阅被拦截的 {{name}} 操作 —— 请按原样执行。",
"temp_folder_failed": "无法创建临时文件夹。",
"temp_folder_created": "已创建临时文件夹",
diff --git a/surfaces/gui/src/types.ts b/surfaces/gui/src/types.ts
index d57aa7f4..6cf4346d 100644
--- a/surfaces/gui/src/types.ts
+++ b/surfaces/gui/src/types.ts
@@ -27,7 +27,12 @@ export type EventType =
| "compacting"
| "compacted"
| "continuation"
- | "turn_done";
+ | "turn_done"
+ // OPE-206: a socket connect that has to build a sandbox first says so on the socket
+ // itself, so the session view can show "Preparing sandbox…" instead of the app
+ // falling back to its startup screen while the backend was busy.
+ | "sandbox_preparing"
+ | "sandbox_ready";
export interface WsEvent {
type: EventType;
diff --git a/tests/test_session_socket_sandbox_build.py b/tests/test_session_socket_sandbox_build.py
new file mode 100644
index 00000000..671baaf8
--- /dev/null
+++ b/tests/test_session_socket_sandbox_build.py
@@ -0,0 +1,114 @@
+"""A socket connect that has to build a sandbox (OPE-206).
+
+The engine build used to run on the event loop; with OpenShell that is a container being
+created, so the whole server stopped answering and the GUI fell back to its startup
+screen. Now the socket says `sandbox_preparing`, the build runs on a worker thread, and
+the socket reports `sandbox_ready` (or an `error` with the reason) before `ready`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+
+import pytest
+from fastapi.testclient import TestClient
+
+from coworker.sandbox.providers.openshell import OpenShellUnavailable
+from coworker.server import create_app
+from tests.test_persona_connections import _mgr
+
+
+class _FakeSandbox:
+ def describe(self):
+ return {"provider": "openshell", "enforcement": "full", "reason": "OpenShell 0.0.116: Landlock and seccomp", "sandbox": "ow-abc", "runner": {"os": "Linux"}}
+
+
+def test_a_connect_that_builds_a_sandbox_says_so_and_builds_off_the_loop(tmp_path, monkeypatch):
+ mgr = _mgr(tmp_path, monkeypatch)
+ monkeypatch.setattr(mgr, "pending_sandbox_build", lambda session_id: "openshell")
+ seen: dict = {}
+ real = mgr.get_engine
+
+ def build(session_id, **kwargs):
+ seen["thread"] = threading.current_thread().name
+ try:
+ asyncio.get_running_loop()
+ seen["on_loop"] = True
+ except RuntimeError:
+ seen["on_loop"] = False
+ engine = real(session_id, **kwargs)
+ engine.sandbox_workspace = _FakeSandbox()
+ return engine
+
+ monkeypatch.setattr(mgr, "get_engine", build)
+ client = TestClient(create_app(mgr))
+ with client.websocket_connect("/ws/session/s-box?agent=cowork") as ws:
+ first, second, third = ws.receive_json(), ws.receive_json(), ws.receive_json()
+ assert first == {"type": "sandbox_preparing", "data": {"provider": "openshell"}}
+ assert second["type"] == "sandbox_ready"
+ assert second["data"] == {"provider": "openshell", "enforcement": "full", "reason": "OpenShell 0.0.116: Landlock and seccomp", "sandbox": "ow-abc"}
+ assert third["type"] == "ready"
+ assert seen["on_loop"] is False # the build ran on a worker thread, the loop stayed free
+
+
+def test_a_connect_that_needs_no_sandbox_is_unchanged(tmp_path, monkeypatch):
+ mgr = _mgr(tmp_path, monkeypatch) # no sandbox_provider set: direct mode
+ client = TestClient(create_app(mgr))
+ with client.websocket_connect("/ws/session/s-plain?agent=cowork") as ws:
+ assert ws.receive_json()["type"] == "ready"
+
+
+def test_a_refused_sandbox_is_reported_on_the_socket_not_as_a_server_error(tmp_path, monkeypatch):
+ mgr = _mgr(tmp_path, monkeypatch)
+ monkeypatch.setattr(mgr, "pending_sandbox_build", lambda session_id: "openshell")
+ refusal = "The sandbox base image is not downloaded yet (about 5 GB, one time). Run `openworker machine sandbox setup`."
+
+ def refuse(session_id, **kwargs):
+ raise OpenShellUnavailable(refusal)
+
+ monkeypatch.setattr(mgr, "get_engine", refuse)
+ client = TestClient(create_app(mgr))
+ 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
+ ws.receive_json()
+
+
+def test_pending_sandbox_build_reads_the_config_and_knows_an_existing_engine(tmp_path, monkeypatch):
+ from coworker import config
+
+ mgr = _mgr(tmp_path, monkeypatch)
+ monkeypatch.delenv("OPENWORKER_SANDBOX_PROVIDER", raising=False)
+ monkeypatch.delenv("OPENWORKER_HEADLESS", raising=False)
+ monkeypatch.setattr(config, "global_config_path", lambda: tmp_path / "config.toml")
+ assert mgr.pending_sandbox_build("s-new") == "" # default rule on a desktop: direct
+ monkeypatch.setenv("OPENWORKER_HEADLESS", "1")
+ assert mgr.pending_sandbox_build("s-new") == "openshell" # a headless machine's default
+ monkeypatch.delenv("OPENWORKER_HEADLESS")
+ mgr.get_engine("s-built", agent="cowork") # direct mode here: no OpenShell on a test box
+ config.set_global_value("sandbox_provider", "openshell")
+ assert mgr.pending_sandbox_build("s-new") == "openshell"
+ assert mgr.pending_sandbox_build("s-built") == "" # built already: nothing pending
+ monkeypatch.setenv("OPENWORKER_SANDBOX_PROVIDER", "direct")
+ assert mgr.pending_sandbox_build("s-new") == "" # the environment wins
+
+
+def test_two_connects_to_one_session_build_one_engine(tmp_path, monkeypatch):
+ mgr = _mgr(tmp_path, monkeypatch)
+ builds: list[str] = []
+ real = mgr._build_or_get_engine
+
+ def slow_build(session_id, **kwargs):
+ if session_id not in mgr._engines:
+ builds.append(session_id)
+ return real(session_id, **kwargs)
+
+ monkeypatch.setattr(mgr, "_build_or_get_engine", slow_build)
+ threads = [threading.Thread(target=lambda: mgr.get_engine("s-twice", agent="cowork")) for _ in range(4)]
+ for t in threads:
+ t.start()
+ for t in threads:
+ t.join()
+ assert builds == ["s-twice"] # serialized per session: the others found the engine