chore(merge): sync master into dev/4.11.x

src/langbot/pkg/box/admission.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+import asyncio
+import datetime as dt
+import time
+import weakref
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from langbot_plugin.box.errors import BoxAdmissionError, BoxRuntimeUnavailableError
+from langbot_plugin.box.models import (
+    SandboxAdmissionGrant,
+    SandboxAdmissionPolicy,
+    SandboxAdmissionRevocation,
+)
+
+from ..api.http.context import ExecutionContext
+from ..cloud.entitlements import EntitlementSnapshot, EntitlementUnavailableError
+
+if TYPE_CHECKING:
+    from langbot_plugin.box.client import BoxRuntimeClient
+
+    from ..core.app import Application
+
+
+_UTC = dt.timezone.utc
+_MANAGED_SANDBOX_FEATURE = 'managed_sandbox'
+_MANAGED_SANDBOX_SESSION_LIMIT = 'managed_sandbox_sessions'
+_MAX_GRANT_TTL_SEC = 300
+
+
+class SandboxAdmissionController:
+    """Project Cloud entitlements into short-lived Box Runtime grants.
+
+    Product and plan names intentionally never cross this boundary. The
+    closed Control Plane supplies a versioned generic entitlement, while Core
+    installs only the numeric authority understood by the shared Box Runtime.
+
+    No state is allocated for a Workspace until it attempts to use the
+    managed sandbox. Per-Workspace locks serialize renewal/revocation so a
+    concurrent first use cannot install conflicting grants.
+    """
+
+    def __init__(
+        self,
+        ap: Application,
+        client: BoxRuntimeClient,
+        *,
+        policy: SandboxAdmissionPolicy,
+        wall_time: Callable[[], float] = time.time,
+    ) -> None:
+        self.ap = ap
+        self.client = client
+        self.policy = policy
+        self._wall_time = wall_time
+        self._locks: weakref.WeakValueDictionary[str, asyncio.Lock] = weakref.WeakValueDictionary()
+        self._highest_revisions: dict[str, int] = {}
+
+    def _workspace_lock(self, workspace_uuid: str) -> asyncio.Lock:
+        lock = self._locks.get(workspace_uuid)
+        if lock is None:
+            lock = asyncio.Lock()
+            self._locks[workspace_uuid] = lock
+        return lock
+
+    @staticmethod
+    def _context_revision(context: ExecutionContext) -> int:
+        revision = getattr(context, 'entitlement_revision', 0)
+        if isinstance(revision, bool) or not isinstance(revision, int):
+            return 0
+        return max(revision, 0)
+
+    def _revocation_revision(self, context: ExecutionContext, candidate_revision: int = 0) -> int:
+        return max(
+            1,
+            self._highest_revisions.get(context.workspace_uuid, 0),
+            self._context_revision(context),
+            candidate_revision,
+        )
+
+    async def _revoke_locked(
+        self,
+        context: ExecutionContext,
+        *,
+        candidate_revision: int = 0,
+    ) -> None:
+        revision = self._revocation_revision(context, candidate_revision)
+        revocation = SandboxAdmissionRevocation(
+            instance_uuid=context.instance_uuid,
+            workspace_uuid=context.workspace_uuid,
+            entitlement_revision=revision,
+        )
+        try:
+            result = await self.client.revoke_sandbox_admission_grant(revocation)
+            if (
+                not isinstance(result, dict)
+                or result.get('revoked') is not True
+                or result.get('workspace_uuid') != context.workspace_uuid
+                or result.get('entitlement_revision') != revision
+            ):
+                raise BoxRuntimeUnavailableError('Box Runtime returned an invalid sandbox revocation receipt')
+        except Exception as exc:
+            # The caller still fails closed even if the control connection is
+            # unavailable. A previously installed grant expires independently
+            # in at most five minutes inside the Runtime.
+            self.ap.logger.warning(
+                'Failed to install Box sandbox admission revocation: '
+                f'workspace_uuid={context.workspace_uuid} revision={revision} error={exc}'
+            )
+        self._highest_revisions[context.workspace_uuid] = revision
+
+    @staticmethod
+    def _require_managed_sandbox(snapshot: EntitlementSnapshot) -> None:
+        snapshot.require_feature(_MANAGED_SANDBOX_FEATURE)
+        sessions = snapshot.limit(_MANAGED_SANDBOX_SESSION_LIMIT)
+        if sessions != 1:
+            raise EntitlementUnavailableError('Workspace entitlement must grant exactly one managed sandbox session')
+
+    def _grant_expiry(self, snapshot: EntitlementSnapshot) -> dt.datetime:
+        now_epoch = int(self._wall_time())
+        ttl_sec = min(self.policy.max_grant_ttl_sec, _MAX_GRANT_TTL_SEC)
+        expires_epoch = min(snapshot.expires_at, now_epoch + ttl_sec)
+        if expires_epoch <= now_epoch:
+            raise EntitlementUnavailableError('Workspace entitlement expired before sandbox admission')
+        return dt.datetime.fromtimestamp(expires_epoch, tz=_UTC)
+
+    async def require(self, context: ExecutionContext) -> SandboxAdmissionGrant:
+        """Validate entitlement freshness and install/renew one Runtime grant."""
+
+        resolver = getattr(self.ap, 'entitlement_resolver', None)
+        if resolver is None:
+            raise EntitlementUnavailableError('Workspace entitlement resolver is unavailable')
+        if context.instance_uuid != resolver.instance_uuid:
+            raise EntitlementUnavailableError('Workspace entitlement targets another LangBot instance')
+
+        lock = self._workspace_lock(context.workspace_uuid)
+        async with lock:
+            try:
+                snapshot = await resolver.resolve(
+                    context.workspace_uuid,
+                    minimum_revision=self._context_revision(context),
+                    now=int(self._wall_time()),
+                )
+            except EntitlementUnavailableError as exc:
+                # Only a verified, scoped snapshot can authoritatively revoke
+                # a revision. Provider timeouts, malformed responses, and
+                # rollback/equivocation errors fail this request closed but do
+                # not tombstone a still-valid revision forever.
+                authoritative_revision = exc.entitlement_revision
+                if authoritative_revision is not None:
+                    await self._revoke_locked(
+                        context,
+                        candidate_revision=authoritative_revision,
+                    )
+                raise
+
+            try:
+                self._require_managed_sandbox(snapshot)
+            except EntitlementUnavailableError:
+                await self._revoke_locked(
+                    context,
+                    candidate_revision=snapshot.entitlement_revision,
+                )
+                raise
+
+            grant = SandboxAdmissionGrant(
+                instance_uuid=context.instance_uuid,
+                workspace_uuid=context.workspace_uuid,
+                execution_generation=context.placement_generation,
+                entitlement_revision=snapshot.entitlement_revision,
+                expires_at=self._grant_expiry(snapshot),
+                max_sessions=1,
+                max_managed_processes=0,
+            )
+            result = await self.client.upsert_sandbox_admission_grant(grant)
+            if (
+                not isinstance(result, dict)
+                or result.get('installed') is not True
+                or result.get('workspace_uuid') != context.workspace_uuid
+                or result.get('execution_generation') != context.placement_generation
+                or result.get('entitlement_revision') != snapshot.entitlement_revision
+                or result.get('max_sessions') != 1
+                or result.get('max_managed_processes') != 0
+            ):
+                raise BoxRuntimeUnavailableError('Box Runtime returned an invalid sandbox admission receipt')
+            self._highest_revisions[context.workspace_uuid] = max(
+                self._highest_revisions.get(context.workspace_uuid, 0),
+                snapshot.entitlement_revision,
+            )
+            return grant
+
+    async def revoke(self, context: ExecutionContext, *, entitlement_revision: int = 0) -> None:
+        """Explicitly revoke a Workspace grant using a monotonic tombstone."""
+
+        async with self._workspace_lock(context.workspace_uuid):
+            await self._revoke_locked(context, candidate_revision=entitlement_revision)
+
+
+def require_cloud_admission_policy(raw_policy: object) -> SandboxAdmissionPolicy:
+    """Parse the Cloud Box policy without permitting an OSS downgrade."""
+
+    try:
+        policy = SandboxAdmissionPolicy.model_validate(raw_policy)
+    except Exception as exc:
+        raise BoxAdmissionError('Cloud Box sandbox admission policy is invalid') from exc
+    if not policy.required:
+        raise BoxAdmissionError('Cloud Box sandbox admission must be required')
+    if policy.logical_session_id != 'global':
+        raise BoxAdmissionError('Cloud Box sandbox session ID must be global')
+    if policy.required_backend != 'nsjail':
+        raise BoxAdmissionError('Cloud Box sandbox backend must be nsjail')
+    if policy.max_sessions != 1 or policy.max_managed_processes != 0:
+        raise BoxAdmissionError('Cloud Box sandbox policy must allow one session and zero managed processes')
+    if policy.max_grant_ttl_sec > _MAX_GRANT_TTL_SEC:
+        raise BoxAdmissionError('Cloud Box sandbox admission grant TTL must not exceed 300 seconds')
+    if policy.workspace_quota_mb <= 0:
+        raise BoxAdmissionError('Cloud Box sandbox workspace quota must be a positive integer')
+    return policy

src/langbot/pkg/box/connector.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import json
 import os
+import secrets
 import sys
 import typing
 from typing import TYPE_CHECKING
@@ -15,6 +17,17 @@ from langbot_plugin.runtime.io.connection import Connection
 from langbot_plugin.box.client import ActionRPCBoxClient
 from langbot_plugin.box.errors import BoxRuntimeUnavailableError
 from langbot_plugin.box.actions import LangBotToBoxAction
+from langbot_plugin.box.security import (
+    BOX_CONTROL_TOKEN_ENV,
+    BOX_CONTROL_TOKEN_HEADER,
+    BOX_INSTANCE_HEADER,
+    BOX_PLACEMENT_GENERATION_HEADER,
+    BOX_TRUSTED_INSTANCE_ENV,
+    BOX_WORKSPACE_HEADER,
+    normalize_instance_uuid,
+    validate_control_token,
+)
+from langbot_plugin.entities.io.context import ActionContext
 
 from ..utils import platform
 from ..utils.managed_runtime import ManagedRuntimeConnector
@@ -28,6 +41,7 @@ _DOCKER_BOX_HOST = 'langbot_box'
 _DEFAULT_PORT = 5410
 
 _HEARTBEAT_INTERVAL_SEC = 20
+_HEARTBEAT_FAILURE_THRESHOLD = 3
 
 # Top-level keys under ``box`` that are LangBot-internal and should not be
 # forwarded to the Box runtime.
@@ -113,12 +127,16 @@ class BoxRuntimeConnector(ManagedRuntimeConnector):
         self._handler_task: asyncio.Task | None = None
         self._ctrl_task: asyncio.Task | None = None
         self._heartbeat_task: asyncio.Task | None = None
+        self._ctrl = None
+        self._generation = 0
 
         # Parse the relay URL once for reuse.
         parsed = urlparse(self.ws_relay_base_url)
         self._relay_host = parsed.hostname or '127.0.0.1'
         self._relay_port = parsed.port or _DEFAULT_PORT
         self._filtered_box_config = _filter_config_for_runtime(_get_box_config(ap))
+        self._trusted_instance_uuid = normalize_instance_uuid(self.ap.workspace_service.instance_uuid)
+        self._control_token = str(os.environ.get(BOX_CONTROL_TOKEN_ENV) or '').strip()
 
     def uses_websocket(self) -> bool:
         """Whether the connector should use WebSocket to reach the Box runtime.
@@ -145,34 +163,69 @@ class BoxRuntimeConnector(ManagedRuntimeConnector):
         return self.uses_websocket()
 
     async def initialize(self) -> None:
-        if self._uses_websocket():
-            if platform.get_platform() == 'win32' and not self.configured_runtime_endpoint:
-                await self._start_subprocess_then_ws()
-            else:
-                await self._connect_remote_ws()
-        else:
-            await self._start_local_stdio()
+        async with self._lifecycle_lock:
+            if self._closing:
+                raise BoxRuntimeUnavailableError('box runtime connector is shutting down')
+            self._generation += 1
+            await self._stop_transport()
+            try:
+                if self._uses_websocket():
+                    if platform.get_platform() == 'win32' and not self.configured_runtime_endpoint:
+                        await self._start_subprocess_then_ws()
+                    else:
+                        await self._connect_remote_ws()
+                else:
+                    await self._start_local_stdio()
+            except BaseException:
+                await self._stop_transport()
+                await self._close_managed_subprocess()
+                raise
 
-        # Start heartbeat after successful connection
-        if self._heartbeat_task is None:
-            self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())
+            if self._heartbeat_task is None or self._heartbeat_task.done():
+                self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())
+
+    async def reconnect(self) -> None:
+        async with self._lifecycle_lock:
+            if self._closing:
+                raise BoxRuntimeUnavailableError('box runtime connector is shutting down')
+            self._generation += 1
+            await self._stop_transport()
+            try:
+                if self._uses_websocket():
+                    if platform.get_platform() == 'win32' and not self.configured_runtime_endpoint:
+                        await self._start_subprocess_then_ws()
+                    else:
+                        await self._connect_remote_ws()
+                else:
+                    await self._start_local_stdio()
+            except BaseException:
+                await self._stop_transport()
+                await self._close_managed_subprocess()
+                raise
+
+            if self._heartbeat_task is None or self._heartbeat_task.done():
+                self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())
 
     # -- heartbeat -----------------------------------------------------------
 
     async def _heartbeat_loop(self) -> None:
         """Periodically ping the Box runtime to detect silent disconnections."""
-        while True:
+        failures = 0
+        while not self._closing:
             await asyncio.sleep(_HEARTBEAT_INTERVAL_SEC)
             try:
                 await self.ping()
+                failures = 0
                 self.ap.logger.debug('Heartbeat to Box runtime success.')
             except asyncio.CancelledError:
                 raise
             except Exception as e:
-                self.ap.logger.warning(f'Heartbeat to Box runtime failed; reconnecting: {e}')
-                if self.runtime_disconnect_callback is not None:
-                    await self.runtime_disconnect_callback(self)
-                    return
+                failures += 1
+                self.ap.logger.warning(f'Box runtime heartbeat failed ({failures}/{_HEARTBEAT_FAILURE_THRESHOLD}): {e}')
+                if failures >= _HEARTBEAT_FAILURE_THRESHOLD:
+                    failures = 0
+                    if self.runtime_disconnect_callback is not None:
+                        await self.runtime_disconnect_callback(self)
 
     async def ping(self) -> None:
         if self._handler is None:
@@ -186,8 +239,11 @@ class BoxRuntimeConnector(ManagedRuntimeConnector):
         from langbot_plugin.runtime.io.controllers.stdio.client import StdioClientController
 
         self.ap.logger.info('Use stdio to connect to box runtime')
+        self._ensure_control_token(allow_generate=True)
         python_path = sys.executable
         env = os.environ.copy()
+        env[BOX_CONTROL_TOKEN_ENV] = self._control_token
+        env[BOX_TRUSTED_INSTANCE_ENV] = self._trusted_instance_uuid
         if self._filtered_box_config:
             env['LANGBOT_BOX_CONFIG'] = json.dumps(self._filtered_box_config)
 
@@ -201,9 +257,11 @@ class BoxRuntimeConnector(ManagedRuntimeConnector):
             # mirroring `rt -s`.
             args=['-m', 'langbot_plugin.cli.__init__', 'box', '-s', '--ws-control-port', str(self._relay_port)],
             env=env,
+            capture_stderr=False,
         )
+        self._ctrl = ctrl
         self._ctrl_task = asyncio.create_task(
-            ctrl.run(self._make_connection_callback('stdio', connected, connect_error))
+            ctrl.run(self._make_connection_callback('stdio', connected, connect_error, self._generation))
         )
 
         try:
@@ -220,7 +278,10 @@ class BoxRuntimeConnector(ManagedRuntimeConnector):
         """Launch box server as detached subprocess, then connect via WS (Windows)."""
         self.ap.logger.info('(windows) Use cmd to launch box runtime and communicate via ws')
 
+        self._ensure_control_token(allow_generate=True)
         env = os.environ.copy()
+        env[BOX_CONTROL_TOKEN_ENV] = self._control_token
+        env[BOX_TRUSTED_INSTANCE_ENV] = self._trusted_instance_uuid
         if self._filtered_box_config:
             env['LANGBOT_BOX_CONFIG'] = json.dumps(self._filtered_box_config)
 
@@ -243,6 +304,7 @@ class BoxRuntimeConnector(ManagedRuntimeConnector):
 
     async def _connect_remote_ws(self) -> None:
         """Connect to a remote (or Docker) box server via WebSocket."""
+        self._ensure_control_token(allow_generate=False)
         ws_url = self._resolve_rpc_ws_url()
         self.ap.logger.info(f'Use WebSocket to connect to box runtime ({ws_url})')
         await self._connect_ws(ws_url, 'WebSocket')
@@ -286,9 +348,14 @@ class BoxRuntimeConnector(ManagedRuntimeConnector):
             if self.runtime_disconnect_callback is not None:
                 await self.runtime_disconnect_callback(self)
 
-        ctrl = WebSocketClientController(ws_url=ws_url, make_connection_failed_callback=on_connect_failed)
+        ctrl = WebSocketClientController(
+            ws_url=ws_url,
+            make_connection_failed_callback=on_connect_failed,
+            additional_headers=self.get_control_headers(),
+        )
+        self._ctrl = ctrl
         self._ctrl_task = asyncio.create_task(
-            ctrl.run(self._make_connection_callback(transport_name, connected, connect_error))
+            ctrl.run(self._make_connection_callback(transport_name, connected, connect_error, self._generation))
         )
 
         try:
@@ -299,14 +366,69 @@ class BoxRuntimeConnector(ManagedRuntimeConnector):
         if connect_error:
             raise BoxRuntimeUnavailableError(f'box runtime connection failed: {connect_error[0]}')
 
+    def _ensure_control_token(self, *, allow_generate: bool) -> str:
+        if not self._control_token and allow_generate:
+            self._control_token = secrets.token_urlsafe(48)
+        try:
+            self._control_token = validate_control_token(self._control_token)
+        except ValueError as exc:
+            raise BoxRuntimeUnavailableError(
+                f'{BOX_CONTROL_TOKEN_ENV} must be configured with a strong shared secret for an external Box runtime'
+            ) from exc
+        return self._control_token
+
+    def get_control_headers(self) -> dict[str, str]:
+        """Headers for the instance-authenticated RPC control handshake."""
+
+        self._ensure_control_token(allow_generate=False)
+        return {
+            BOX_CONTROL_TOKEN_HEADER: self._control_token,
+            BOX_INSTANCE_HEADER: self._trusted_instance_uuid,
+        }
+
+    def get_relay_headers(
+        self,
+        action_context: ActionContext,
+    ) -> dict[str, str]:
+        """Return authenticated, placement-scoped relay handshake headers."""
+
+        context = ActionContext.model_validate(action_context).without_installation()
+        if context.instance_uuid != self._trusted_instance_uuid:
+            raise BoxRuntimeUnavailableError('Box relay context belongs to another LangBot instance')
+        return {
+            **self.get_control_headers(),
+            BOX_WORKSPACE_HEADER: context.workspace_uuid,
+            BOX_PLACEMENT_GENERATION_HEADER: str(context.placement_generation),
+        }
+
     def _make_connection_callback(
         self,
         transport_name: str,
         connected: asyncio.Event,
         connect_error: list[Exception],
+        generation: int,
     ):
         async def new_connection_callback(connection: Connection) -> None:
+            if generation != self._generation or self._closing:
+                await connection.close()
+                return
             handler = Handler(connection)
+            connection_ready = False
+            disconnect_notified = False
+
+            async def notify_disconnect() -> None:
+                nonlocal disconnect_notified
+                if (
+                    connection_ready
+                    and not disconnect_notified
+                    and generation == self._generation
+                    and not self._closing
+                    and self.runtime_disconnect_callback is not None
+                ):
+                    disconnect_notified = True
+                    self.ap.logger.error('Disconnected from Box runtime, trying to reconnect...')
+                    await self.runtime_disconnect_callback(self)
+
             self._handler = handler
             self.client.set_handler(handler)
             self._handler_task = asyncio.create_task(handler.run())
@@ -316,27 +438,74 @@ class BoxRuntimeConnector(ManagedRuntimeConnector):
                     await handler.call_action(LangBotToBoxAction.INIT, self._filtered_box_config)
                     self.ap.logger.debug('Sent box configuration to Box runtime via INIT.')
                 self.ap.logger.info(f'Connected to Box runtime via {transport_name}.')
+                connection_ready = True
                 connected.set()
                 await self._handler_task
+            except asyncio.CancelledError:
+                raise
             except Exception as exc:
                 if not connected.is_set():
                     connect_error.append(exc)
                     connected.set()
                     return
-
-            # If we reach here, handler.run() returned normally (connection
-            # closed) or raised after the initial handshake succeeded.
-            # Either way, treat it as a disconnect.
-            if connected.is_set():
-                self.ap.logger.error('Disconnected from Box runtime, trying to reconnect...')
-                if self.runtime_disconnect_callback is not None:
-                    await self.runtime_disconnect_callback(self)
+            finally:
+                if getattr(self, '_handler', None) is handler:
+                    self._handler = None
+                    self.client.set_handler(None)
+                await notify_disconnect()
 
         return new_connection_callback
 
     # -- lifecycle -----------------------------------------------------------
 
+    async def _stop_transport(self) -> None:
+        if self._handler is not None:
+            with contextlib.suppress(Exception):
+                await self._handler.close()
+        self.client.set_handler(None)
+        tasks = [
+            task
+            for task in (self._handler_task, self._ctrl_task)
+            if task is not None and task is not asyncio.current_task()
+        ]
+        for task in tasks:
+            task.cancel()
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+        close_ctrl = getattr(self._ctrl, 'close', None)
+        if close_ctrl is not None:
+            with contextlib.suppress(Exception):
+                await close_ctrl()
+        self._handler = None
+        self._handler_task = None
+        self._ctrl_task = None
+        self._ctrl = None
+
+    async def aclose(self) -> None:
+        self._closing = True
+        self._generation += 1
+        if self._heartbeat_task is not None:
+            self._heartbeat_task.cancel()
+            await asyncio.gather(self._heartbeat_task, return_exceptions=True)
+            self._heartbeat_task = None
+        await self._stop_transport()
+
+        process = getattr(self, '_subprocess', None)
+        if process is not None and process.returncode is None:
+            with contextlib.suppress(ProcessLookupError):
+                process.terminate()
+            try:
+                await asyncio.wait_for(process.wait(), timeout=3)
+            except asyncio.TimeoutError:
+                with contextlib.suppress(ProcessLookupError):
+                    process.kill()
+                await process.wait()
+        self._subprocess = None
+        await self._close_managed_subprocess()
+
     def dispose(self) -> None:
+        """Best-effort synchronous compatibility wrapper; prefer ``aclose``."""
+        self._closing = True
         if self._heartbeat_task is not None:
             self._heartbeat_task.cancel()
             self._heartbeat_task = None

src/langbot/pkg/box/secure_fs.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+import contextlib
+import errno
+import os
+import stat
+from collections.abc import Iterable
+
+
+class UnsafeWorkspacePathError(OSError):
+    """A tenant-controlled path could not be opened without following links."""
+
+
+_DIRECTORY_FLAGS = (
+    os.O_RDONLY | getattr(os, 'O_DIRECTORY', 0) | getattr(os, 'O_NOFOLLOW', 0) | getattr(os, 'O_CLOEXEC', 0)
+)
+_FILE_READ_FLAGS = os.O_RDONLY | getattr(os, 'O_NOFOLLOW', 0) | getattr(os, 'O_CLOEXEC', 0)
+_FILE_WRITE_FLAGS = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, 'O_NOFOLLOW', 0) | getattr(os, 'O_CLOEXEC', 0)
+_MAX_REMOVAL_ENTRIES = 4096
+_MAX_REMOVAL_DEPTH = 16
+
+
+def _component(value: str) -> str:
+    normalized = str(value or '').strip()
+    if (
+        not normalized
+        or normalized in {'.', '..'}
+        or '/' in normalized
+        or '\\' in normalized
+        or '\x00' in normalized
+        or len(os.fsencode(normalized)) > 240
+    ):
+        raise UnsafeWorkspacePathError('Unsafe Workspace path component')
+    return normalized
+
+
+def _unsafe(path: str, exc: BaseException | None = None) -> UnsafeWorkspacePathError:
+    error = UnsafeWorkspacePathError(f'Workspace path is not a link-free directory: {path}')
+    if exc is not None:
+        error.__cause__ = exc
+    return error
+
+
+@contextlib.contextmanager
+def _root_fd(root: str):
+    try:
+        fd = os.open(root, _DIRECTORY_FLAGS)
+    except OSError as exc:
+        raise _unsafe(root, exc)
+    try:
+        if not stat.S_ISDIR(os.fstat(fd).st_mode):
+            raise _unsafe(root)
+        yield fd
+    finally:
+        os.close(fd)
+
+
+def _open_dir_at(parent_fd: int, name: str, *, create: bool) -> int:
+    name = _component(name)
+    if create:
+        try:
+            os.mkdir(name, mode=0o700, dir_fd=parent_fd)
+        except FileExistsError:
+            pass
+    try:
+        fd = os.open(name, _DIRECTORY_FLAGS, dir_fd=parent_fd)
+    except OSError as exc:
+        raise _unsafe(name, exc)
+    if not stat.S_ISDIR(os.fstat(fd).st_mode):
+        os.close(fd)
+        raise _unsafe(name)
+    return fd
+
+
+def _remove_entry(
+    parent_fd: int,
+    name: str,
+    *,
+    budget: list[int] | None = None,
+    depth: int = 0,
+) -> None:
+    """Remove an entry recursively without following a symlink at any depth."""
+
+    name = _component(name)
+    budget = budget if budget is not None else [_MAX_REMOVAL_ENTRIES]
+    if depth > _MAX_REMOVAL_DEPTH or budget[0] <= 0:
+        raise UnsafeWorkspacePathError('Workspace cleanup exceeded its inode budget')
+    budget[0] -= 1
+    for _ in range(4):
+        try:
+            child_fd = os.open(name, _DIRECTORY_FLAGS, dir_fd=parent_fd)
+        except FileNotFoundError:
+            return
+        except OSError as exc:
+            if exc.errno not in {errno.ELOOP, errno.ENOTDIR, errno.EACCES}:
+                raise
+            try:
+                os.unlink(name, dir_fd=parent_fd)
+                return
+            except FileNotFoundError:
+                return
+            except IsADirectoryError:
+                continue
+        else:
+            try:
+                _clear_dir(child_fd, budget=budget, depth=depth + 1)
+            finally:
+                os.close(child_fd)
+            try:
+                os.rmdir(name, dir_fd=parent_fd)
+                return
+            except FileNotFoundError:
+                return
+            except NotADirectoryError:
+                continue
+    raise UnsafeWorkspacePathError('Workspace entry changed while it was being removed')
+
+
+def _clear_dir(directory_fd: int, *, budget: list[int], depth: int) -> None:
+    # ``scandir(fd)`` enumerates the already-open directory. Names are then
+    # resolved relative to the same fd, so a tenant cannot redirect the walk by
+    # swapping an ancestor symlink between validation and use.
+    # Do not materialize the whole directory: an attacker-controlled outbox
+    # may contain an inode bomb even when its byte size is tiny. Removal is
+    # deliberately budgeted and fails closed once the per-operation cap is
+    # reached; hard filesystem/inode quota remains a Cloud readiness gate.
+    with os.scandir(directory_fd) as iterator:
+        for entry in iterator:
+            _remove_entry(directory_fd, entry.name, budget=budget, depth=depth)
+
+
+@contextlib.contextmanager
+def _query_fd(root: str, subdir: str, query_key: str, *, create: bool, reset: bool = False):
+    subdir = _component(subdir)
+    query_key = _component(query_key)
+    with _root_fd(root) as root_fd:
+        subdir_fd = _open_dir_at(root_fd, subdir, create=create)
+        try:
+            if reset:
+                _remove_entry(subdir_fd, query_key)
+            query_fd = _open_dir_at(subdir_fd, query_key, create=create)
+            try:
+                yield query_fd
+            finally:
+                os.close(query_fd)
+        finally:
+            os.close(subdir_fd)
+
+
+def write_files(
+    root: str,
+    subdir: str,
+    query_key: str,
+    files: Iterable[tuple[str, bytes]],
+) -> None:
+    """Atomically recreate one query directory and write regular files only."""
+
+    with _query_fd(root, subdir, query_key, create=True, reset=True) as query_fd:
+        for raw_name, data in files:
+            name = _component(raw_name)
+            try:
+                file_fd = os.open(name, _FILE_WRITE_FLAGS, 0o600, dir_fd=query_fd)
+            except OSError as exc:
+                raise UnsafeWorkspacePathError(f'Could not create a link-free Workspace file: {name}') from exc
+            with os.fdopen(file_fd, 'wb') as file_obj:
+                file_obj.write(data)
+
+
+def _read_directory(
+    directory_fd: int,
+    *,
+    prefix: str,
+    max_file_bytes: int,
+    max_files: int,
+    max_total_bytes: int,
+    output: list[tuple[str, bytes]],
+    total: list[int],
+    remaining_entries: list[int],
+    remaining_directories: list[int],
+    depth: int,
+) -> None:
+    if depth > 8:
+        return
+    with os.scandir(directory_fd) as iterator:
+        for entry in iterator:
+            if len(output) >= max_files or total[0] >= max_total_bytes:
+                return
+            if remaining_entries[0] <= 0:
+                raise UnsafeWorkspacePathError('Sandbox outbox exceeds the directory-entry limit')
+            remaining_entries[0] -= 1
+            name = _component(entry.name)
+            relative = f'{prefix}/{name}' if prefix else name
+            if entry.is_symlink():
+                continue
+            if entry.is_dir(follow_symlinks=False):
+                if remaining_directories[0] <= 0:
+                    raise UnsafeWorkspacePathError('Sandbox outbox exceeds the directory limit')
+                remaining_directories[0] -= 1
+                try:
+                    child_fd = os.open(name, _DIRECTORY_FLAGS, dir_fd=directory_fd)
+                except OSError:
+                    continue
+                try:
+                    _read_directory(
+                        child_fd,
+                        prefix=relative,
+                        max_file_bytes=max_file_bytes,
+                        max_files=max_files,
+                        max_total_bytes=max_total_bytes,
+                        output=output,
+                        total=total,
+                        remaining_entries=remaining_entries,
+                        remaining_directories=remaining_directories,
+                        depth=depth + 1,
+                    )
+                finally:
+                    os.close(child_fd)
+                continue
+            try:
+                file_fd = os.open(name, _FILE_READ_FLAGS, dir_fd=directory_fd)
+            except OSError:
+                continue
+            try:
+                metadata = os.fstat(file_fd)
+                if not stat.S_ISREG(metadata.st_mode) or metadata.st_size > max_file_bytes:
+                    continue
+                remaining = max_total_bytes - total[0]
+                if metadata.st_size > remaining:
+                    continue
+                with os.fdopen(file_fd, 'rb', closefd=False) as file_obj:
+                    data = file_obj.read(max_file_bytes + 1)
+                if len(data) > max_file_bytes or len(data) > remaining:
+                    continue
+                output.append((relative, data))
+                total[0] += len(data)
+            finally:
+                os.close(file_fd)
+
+
+def read_regular_files(
+    root: str,
+    subdir: str,
+    query_key: str,
+    *,
+    max_file_bytes: int,
+    max_files: int,
+    max_total_bytes: int,
+    max_entries: int = 512,
+    max_directories: int = 64,
+) -> list[tuple[str, bytes]]:
+    """Read bounded regular files without following tenant-created links."""
+
+    output: list[tuple[str, bytes]] = []
+    try:
+        with _query_fd(root, subdir, query_key, create=False) as query_fd:
+            _read_directory(
+                query_fd,
+                prefix='',
+                max_file_bytes=max_file_bytes,
+                max_files=max_files,
+                max_total_bytes=max_total_bytes,
+                output=output,
+                total=[0],
+                remaining_entries=[max_entries],
+                remaining_directories=[max_directories],
+                depth=0,
+            )
+    except (FileNotFoundError, UnsafeWorkspacePathError):
+        # A missing directory is an empty outbox. An unsafe existing path is
+        # deliberately surfaced to the caller rather than followed.
+        if os.path.lexists(os.path.join(root, subdir, query_key)):
+            raise
+    return output
+
+
+def reset_directory(root: str, subdir: str, query_key: str) -> None:
+    with _query_fd(root, subdir, query_key, create=True, reset=True):
+        return
+
+
+def purge_subdirectory(root: str, subdir: str) -> None:
+    """Remove one known subtree without following a hostile replacement link."""
+
+    with _root_fd(root) as root_fd:
+        _remove_entry(root_fd, _component(subdir))

src/langbot/pkg/box/workspace.py

@@ -126,24 +126,30 @@ def should_prepare_python_env(host_path: str | None) -> bool:
     return bool(list_python_manifest_files(normalized_root))
 
 
-def wrap_python_command_with_env(command: str, *, mount_path: str = '/workspace') -> str:
+def wrap_python_command_with_env(
+    command: str,
+    *,
+    mount_path: str = '/workspace',
+    state_path: str | None = None,
+) -> str:
     """Wrap a command with a reusable sandbox-local Python env bootstrap.
 
-    This is the generic "workspace is a Python project" path used by mutable
-    workspaces such as skills. Read-only installation strategies stay in the
-    higher-level caller because they are application policy, not workspace
-    semantics.
+    ``mount_path`` is always the source tree used for manifest hashing and
+    installation. ``state_path`` may point at a separate writable directory
+    for read-only source mounts; when omitted, legacy mutable-workspace behavior
+    stores the environment beside the source.
     """
+    writable_state_path = state_path or mount_path
     bootstrap = textwrap.dedent(
         f"""
         set -e
 
-        _LB_VENV_DIR="{mount_path}/.venv"
-        _LB_META_DIR="{mount_path}/.langbot"
+        _LB_VENV_DIR="{writable_state_path}/.venv"
+        _LB_META_DIR="{writable_state_path}/.langbot"
         _LB_META_FILE="$_LB_META_DIR/python-env.json"
         _LB_LOCK_DIR="$_LB_META_DIR/python-env.lock"
-        _LB_TMP_DIR="{mount_path}/.tmp"
-        _LB_PIP_CACHE_DIR="{mount_path}/.cache/pip"
+        _LB_TMP_DIR="{writable_state_path}/.tmp"
+        _LB_PIP_CACHE_DIR="{writable_state_path}/.cache/pip"
 
         mkdir -p "$_LB_META_DIR" "$_LB_TMP_DIR" "$_LB_PIP_CACHE_DIR"
         _LB_SYSTEM_PYTHON="$(command -v python3 || command -v python || true)"
@@ -165,17 +171,23 @@ def wrap_python_command_with_env(command: str, *, mount_path: str = '/workspace'
         import sys
 
         root = "{mount_path}"
+        max_manifest_bytes = 10 * 1024 * 1024
         digest = hashlib.sha256()
         manifest_files = []
         for rel in ("requirements.txt", "pyproject.toml", "setup.py", "setup.cfg"):
             path = os.path.join(root, rel)
             if not os.path.isfile(path):
                 continue
+            if os.path.getsize(path) > max_manifest_bytes:
+                raise RuntimeError(
+                    f"Python project manifest exceeds {{max_manifest_bytes}} bytes: {{rel}}"
+                )
             manifest_files.append(rel)
             with open(path, "rb") as handle:
                 digest.update(rel.encode("utf-8"))
                 digest.update(b"\\0")
-                digest.update(handle.read())
+                while chunk := handle.read(1024 * 1024):
+                    digest.update(chunk)
                 digest.update(b"\\0")
 
         print(
@@ -274,6 +286,7 @@ class BoxWorkspaceSession:
     def __init__(
         self,
         box_service,
+        execution_context,
         session_id: str,
         *,
         host_path: str | None = None,
@@ -290,6 +303,7 @@ class BoxWorkspaceSession:
         persistent: bool = False,
     ):
         self.box_service = box_service
+        self.execution_context = execution_context
         self.session_id = session_id
         self.host_path = host_path
         self.host_path_mode = host_path_mode
@@ -363,7 +377,7 @@ class BoxWorkspaceSession:
         timeout_sec: int | None = None,
     ):
         payload = self.build_exec_payload(cmd, workdir=workdir, env=env, timeout_sec=timeout_sec)
-        return await self.box_service.client.execute(self.box_service.build_spec(payload))
+        return await self.box_service.execute_in_context(self.execution_context, payload)
 
     async def execute_for_query(
         self,
@@ -378,7 +392,7 @@ class BoxWorkspaceSession:
         return await self.box_service.execute_spec_payload(payload, query)
 
     async def create_session(self):
-        return await self.box_service.create_session(self.build_session_payload())
+        return await self.box_service.create_session(self.execution_context, self.build_session_payload())
 
     def build_process_payload(
         self,
@@ -415,16 +429,26 @@ class BoxWorkspaceSession:
     ):
         payload = self.build_process_payload(command, args, env=env, cwd=cwd)
         payload['process_id'] = process_id
-        return await self.box_service.start_managed_process(self.session_id, payload)
+        return await self.box_service.start_managed_process(self.execution_context, self.session_id, payload)
 
     async def get_managed_process(self, process_id: str = 'default'):
-        return await self.box_service.get_managed_process(self.session_id, process_id)
+        return await self.box_service.get_managed_process(self.execution_context, self.session_id, process_id)
 
     async def stop_managed_process(self, process_id: str = 'default') -> None:
-        await self.box_service.stop_managed_process(self.session_id, process_id)
+        await self.box_service.stop_managed_process(self.execution_context, self.session_id, process_id)
 
-    def get_managed_process_websocket_url(self, process_id: str = 'default') -> str:
-        return self.box_service.get_managed_process_websocket_url(self.session_id, process_id)
+    async def get_managed_process_websocket_connection(
+        self,
+        process_id: str = 'default',
+    ) -> tuple[str, dict[str, str]]:
+        return await self.box_service.get_managed_process_websocket_connection(
+            self.execution_context,
+            self.session_id,
+            process_id,
+        )
 
     async def cleanup(self) -> None:
-        await self.box_service.client.delete_session(self.session_id)
+        await self.box_service.client.delete_session(
+            self.session_id,
+            action_context=self.box_service._action_context(self.execution_context),
+        )