From e90be32aa9002b5d05b407707852aaa73eed04bb Mon Sep 17 00:00:00 2001 From: HsingTang <32690368+HsingTang@users.noreply.github.com> Date: Wed, 4 Nov 2026 20:31:50 +0000 Subject: [PATCH 1/9] feat: add Databricks sandbox executor example for codex Add examples/codex/databricks: an application-owned gateway and a lifetime-managing Environment context manager that back the native executor with a Databricks sandbox, following the remote-execution pattern in docs/sdk/execution.md (the Databricks counterpart of offline_docker.py). The gateway relays the SDK's WSS executor connection to the sandbox exec-server over the databricks-sdk streaming command API; databricks_sandbox_environment starts the gateway and yields a configured Environment. Ship as an example (not a src/agents module or dependency extra) to match how the branch ships executor gateways. Include a runnable runner, a README, example requirements, and tests for the relay, bearer auth, teardown paths, the context manager, and the SSL_CERT_FILE trust helper. The gateway drops the non-JSON startup banner the sandbox's codex prints on stdout before the exec-server protocol, so it cannot corrupt the stream; a live turn confirmed the banner is dropped and the tool still executes. The runner and the context manager confirm the sandbox is running (starting it if stopped) before launching the exec-server, since execute_command needs a running sandbox. Validated end-to-end against a live sandbox: the exec-server stdio mode, bidirectional streaming over execute_command, and newline framing, plus exec_command / write_stdin / apply_patch, multi-turn with session resume and a real sandbox stop-start, large and single-line output, and the Environment approval / transform_arguments / transform_result hooks with an enforced NetworkPolicy. tests/codex pass (14) and mypy --strict is clean against the preview wheel on a glibc-2.39 host. This also fixes the runner's sandbox-image spec, which set a non-existent SandboxSpec.image instead of SandboxSpec.environment.image_uri, and caps inbound WebSocket frames at 4 MiB so a large apply_patch/write_stdin payload is not dropped. The runner defaults the model provider to the sandbox workspace's Databricks AI Gateway, with a token minted from the Databricks profile (PAT or OAuth), so no OpenAI key is needed; set OPENAI_BASE_URL / OPENAI_API_KEY to override. It accepts the sandbox id or the sandboxes/ resource name and creates the workspace directory before the turn. Both model-provider paths - the AI Gateway default and the OpenAI-direct override - are validated end to end. Co-authored-by: Isaac --- examples/codex/databricks/README.md | 175 +++++++++++++ examples/codex/databricks/environment.py | 208 ++++++++++++++++ examples/codex/databricks/gateway.py | 272 +++++++++++++++++++++ examples/codex/databricks/requirements.txt | 4 + examples/codex/databricks/runner.py | 157 ++++++++++++ tests/codex/test_databricks_environment.py | 237 ++++++++++++++++++ tests/codex/test_databricks_gateway.py | 262 ++++++++++++++++++++ 7 files changed, 1315 insertions(+) create mode 100644 examples/codex/databricks/README.md create mode 100644 examples/codex/databricks/environment.py create mode 100644 examples/codex/databricks/gateway.py create mode 100644 examples/codex/databricks/requirements.txt create mode 100644 examples/codex/databricks/runner.py create mode 100644 tests/codex/test_databricks_environment.py create mode 100644 tests/codex/test_databricks_gateway.py diff --git a/examples/codex/databricks/README.md b/examples/codex/databricks/README.md new file mode 100644 index 0000000000..a2d5fb9ffd --- /dev/null +++ b/examples/codex/databricks/README.md @@ -0,0 +1,175 @@ +# Databricks sandbox executor + +Back a native `Environment` with a Databricks sandbox, so an agent driven by +this SDK runs `exec_command` / `write_stdin` / `apply_patch` inside the sandbox. +This is the "remote execution" pattern from `docs/sdk/execution.md` - an +application-owned gateway plus a lifetime-managing `Environment` context manager - +the Databricks counterpart of `examples/codex/offline_docker.py`. + +> **Validated end-to-end against a live Databricks sandbox (2026-11-11).** +> The native `Environment` connected to the gateway's `wss://` endpoint and drove +> a real `codex exec-server --listen stdio`. `NativeProvider` +> ran against the sandbox's Databricks AI Gateway codex endpoint (PAT from +> `~/.databrickscfg`; no OpenAI key). `openai-agents` 0.24.0-alpha.7 (the preview +> wheel) on Ubuntu 24.04 / glibc 2.39. +> +> Validated two ways: with the controller co-located in the sandbox (a local +> exec-server subprocess), and with an **external controller** (a glibc-2.39 +> container) driving a separate sandbox over the real `databricks-sdk` +> `execute_command` streaming transport - the actual product topology, tool +> side-effects confirmed back in the executor sandbox. +> +> Exercised through this gateway over that transport (tool calls scripted +> deterministically with the SDK's Responses fixture): +> +> - **Multi-turn, resume, and sandbox stop-start.** Two turns in one session +> (turn 2 read turn 1's file); a fresh session relaunched the exec-server; a +> real `stop_sandbox` + `start_sandbox` cycle returned to service with the +> workspace preserved. +> - **All three tools.** `exec_command`, interactive-TTY `write_stdin`, and +> `apply_patch` (which added a file in the sandbox). +> - **Large output.** A 200k-line stream and a single ~4 MB line both relayed +> through the newline framing without truncation. +> - **Environment policy hooks.** `approval` returning `False` blocked a +> command's side-effect; `transform_arguments` rewrote the command; +> `transform_result` changed what the model saw; a `NetworkPolicy` was +> **enforced** by the executor's managed proxy (an allowed domain returned 200, +> a non-allowed domain was blocked). +> - **Model.** `model="gpt-5.5"` is served by `system.ai.gpt-5-5` on the AI +> Gateway. +> - **Startup-banner handling.** The sandbox's `codex` prints a startup banner to +> stdout before the protocol; a live turn confirmed the gateway drops that +> non-JSON preamble and the tool still executes (`proof_pw.txt` created). +> - **Static checks.** `pytest tests/codex` (14 passed) and `mypy --strict` run +> against the preview wheel on a glibc-2.39 host. + +## How it works + +The native `Environment` dials an authenticated `wss://` executor and relays the +exec-server protocol over it. A Databricks sandbox runs that exec-server in +stdio mode, reached through the `databricks-sdk` streaming command API +(`WorkspaceClient.sandbox.execute_command`). Nothing in the SDK speaks stdio and +nothing in the sandbox speaks WebSocket, so `SandboxExecServerGateway` +(`gateway.py`) bridges them: it terminates the WebSocket, authenticates the +bearer token at the HTTP handshake, opens the exec-server's stdio, and relays +bytes both ways. It does not parse the protocol; it only drops a startup banner +the sandbox's `codex` prints on stdout before the protocol begins (non-JSON +lines) so it never reaches the SDK as a bogus message. + +`databricks_sandbox_environment` (`environment.py`) confirms the sandbox is +running, starts that gateway, and yields a configured `Environment`, so the whole +lifecycle fits one `async with` (the "manage the executor lifetime" pattern). + +Because `execute_command` reaches the sandbox outbound through the Databricks +control plane, the gateway runs on loopback next to the application and the +sandbox needs no inbound ingress. The agent loop runs in your process (via +`NativeProvider`), which is what makes the `Environment` approval / transform +callbacks and `NetworkPolicy` available. + +## Files + +- `gateway.py` - `SandboxExecServerGateway` plus a self-signed loopback TLS helper. +- `environment.py` - `databricks_sandbox_environment`, the lifetime context manager. +- `runner.py` - a runnable end-to-end example. + +## Install and run + +The v1.0 SDK is a GitHub preview wheel (off PyPI); this example is validated +against `openai-agents` 0.24.0-alpha.7. The wheel ships a compiled native +runtime, so it needs a supported host: **Linux x86_64 with glibc 2.39 or +newer**, macOS arm64, or Windows x64. Get the wheel URL from +`docs/sdk/installation.md`, then install it and this example's requirements: + +```sh +pip install "" # URL in docs/sdk/installation.md +pip install -r examples/codex/databricks/requirements.txt +``` + +Provide Databricks auth (a CLI profile) and run from the repo root. The model +runs through the workspace's Databricks AI Gateway by default, using the +profile's own token, so no OpenAI key is needed: + +```sh +SANDBOX_NAME=openai-agent-sandbox DATABRICKS_CONFIG_PROFILE=my-workspace \ + PYTHONPATH=. python -m examples.codex.databricks.runner "Inspect the workspace" +``` + +`SANDBOX_NAME` accepts the bare id or the `sandboxes/` resource name. Set +`SANDBOX_CREATE=1` (with `SANDBOX_IMAGE=...`) to provision the sandbox first; +`exec-server` is killed when the sandbox stops, so a new connection after a stop +relaunches it. + +To run the model through OpenAI directly instead of the Databricks AI Gateway, +set `OPENAI_BASE_URL`, `OPENAI_API_KEY`, and an OpenAI model id your account can +use: + +```sh +SANDBOX_NAME=openai-agent-sandbox DATABRICKS_CONFIG_PROFILE=my-workspace \ + OPENAI_BASE_URL=https://api.openai.com/v1 OPENAI_API_KEY=sk-... \ + OPENAI_MODEL=gpt-5.3-codex \ + PYTHONPATH=. python -m examples.codex.databricks.runner "Inspect the workspace" +``` + +Only the model provider changes; the sandbox, gateway, and tools are identical. + +## TLS + +`Environment` requires `wss`, so the gateway needs TLS even on loopback. By +default `databricks_sandbox_environment` generates an ephemeral self-signed +certificate and, for the session, points `SSL_CERT_FILE` at a bundle of the +public CAs (`certifi`) plus that certificate, then restores it on exit - so the +native runtime trusts the gateway without breaking model-provider TLS. This +mirrors the `remote_executor.py` guidance ("Set `SSL_CERT_FILE` to your executor +CA if it uses a private certificate"). Pass your own `ssl_context` and set +`trust_gateway_ca=False` to manage trust yourself. + +`SSL_CERT_FILE` is process-global, so auto-managed trust supports only one +environment per process; a concurrent second use raises rather than silently +corrupting trust. Open design question for OAI: a per-connection trust lever on +`Environment` (a client CA / SSL context) would let a self-hosted gateway avoid +mutating a process-global variable. + +## Prerequisites (validated 2026-11-11 against a Databricks sandbox) + +1. **A running sandbox.** The application creates the sandbox (or reuses one), + starts it if stopped, and polls its status until running before opening the + environment - the exec-server is reached through `execute_command`, which + needs a running sandbox. `runner.py` shows this, and + `databricks_sandbox_environment` confirms it before starting the gateway. +2. **exec-server stdio mode in the image - SUPPORTED.** The sandbox's `codex` + runs the standalone exec-server over stdio with `codex exec-server --listen + stdio`, which the gateway relays. +3. **Streaming bidirectional relay over `execute_command` - CONFIRMED.** An + external-controller turn drove tool calls through the gateway to the + exec-server and back over the real `databricks-sdk` `execute_command` + streaming `CommandProcess` (`stdin`, `stdout.readline`, `text=False`), + creating a file in the executor sandbox's workspace. +4. **WebSocket newline framing - CONFIRMED by the live turn.** The gateway frames + on newlines (one message per `stdout.readline`, newline appended inbound). The + live turn's tool calls parsed and executed, so the framing matches the + exec-server's stdio protocol. + +## Tests + +`tests/codex/test_databricks_gateway.py` and `test_databricks_environment.py` +cover the relay, startup-banner filtering, bearer auth, the large-frame cap, +teardown paths, the context manager, the running-sandbox precondition, and the +`SSL_CERT_FILE` trust-bundle helper with a fake `CommandProcess`. Install the +preview wheel, this example's requirements, and `pytest` + `pytest-asyncio`, +then run them explicitly from the repo root (the default `testpaths` does not +include `tests/codex`): + +```sh +pytest tests/codex +``` + +(validated: 14 passed, and `mypy --strict` clean, against 0.24.0-alpha.7 on a +glibc-2.39 host.) + +These use a fake `CommandProcess`, so they do not exercise the real exec-server +framing themselves - that framing is instead covered end-to-end against a live +sandbox (see the validation note above). A hermetic variant that needs no +Databricks sandbox would point the gateway at a local `codex exec-server +--listen stdio` and drive one `agent.session(environment=...)` turn with the +repo's native model fixtures (see `packages/codex/tests/native_executor_fixtures.py` +and `packages/codex/tests/test_documented_executor_examples.py`). diff --git a/examples/codex/databricks/environment.py b/examples/codex/databricks/environment.py new file mode 100644 index 0000000000..5c2bce785e --- /dev/null +++ b/examples/codex/databricks/environment.py @@ -0,0 +1,208 @@ +"""Provision a native ``Environment`` backed by a Databricks sandbox. + +This async context manager starts a :class:`SandboxExecServerGateway` for an +existing sandbox and yields an ``Environment`` wired to it. It is the +"manage the executor lifetime" pattern from the remote-execution guide: the SDK +enters the context when opening the Session and exits after releasing native +resources, so the whole start-gateway / tear-down lifecycle fits one +``async with``: + + async with databricks_sandbox_environment( + workspace_client=WorkspaceClient(profile="my-workspace"), + sandbox_name="openai-agent-sandbox", + cwd="/home/sandbox-agent/work", + ) as environment: + async with agent.session(environment=environment) as session: + ... + +Provisioning the sandbox (``WorkspaceClient.sandbox.create_sandbox``), confirming +it is running, and ensuring the ``codex`` exec-server is present are the caller's +responsibility. This context manager confirms the sandbox is running before it +starts the gateway. See ``runner.py`` and the example README for the +create / wait-until-running pattern. +""" + +from __future__ import annotations + +import os +import secrets +import ssl +import tempfile +import threading +from collections.abc import AsyncIterator, Callable, Mapping, Sequence +from contextlib import asynccontextmanager, suppress +from typing import TYPE_CHECKING + +from agents import Environment +from agents.executor import ExecutorToolName +from examples.codex.databricks.gateway import ( + SandboxExecServerGateway, + self_signed_server_context, +) + +if TYPE_CHECKING: + from databricks.sdk import WorkspaceClient + +_DEFAULT_TOOLS: tuple[ExecutorToolName, ...] = ("exec_command", "write_stdin", "apply_patch") + +# Auto-managed trust rewrites the process-global ``SSL_CERT_FILE``, so only one +# auto-managed environment can be active per process. This guard turns a +# concurrent second use into a loud error instead of silent trust corruption. +_trust_lock = threading.Lock() +_trust_active = False + + +@asynccontextmanager +async def databricks_sandbox_environment( + *, + workspace_client: WorkspaceClient, + sandbox_name: str, + cwd: str, + tools: Sequence[ExecutorToolName] = _DEFAULT_TOOLS, + exec_server_command: Sequence[str] = ("codex", "exec-server", "--listen", "stdio"), + exec_server_env: Mapping[str, str] | None = None, + token: str | None = None, + ssl_context: ssl.SSLContext | None = None, + trust_gateway_ca: bool = True, +) -> AsyncIterator[Environment]: + """Yield an ``Environment`` connected to ``sandbox_name`` through a gateway. + + Args: + workspace_client: An authenticated ``databricks.sdk.WorkspaceClient``. + sandbox_name: An existing sandbox with the exec-server available, as either + the bare id or the ``sandboxes/`` resource name. It must be + running; this is confirmed before the gateway starts. + cwd: Absolute remote workspace path the executor operates in. + tools: Native executor tools to expose. ``write_stdin`` requires + ``exec_command``. + exec_server_command: Argv that starts the standalone exec-server over + stdio in the sandbox. Defaults to + ``("codex", "exec-server", "--listen", "stdio")``. + exec_server_env: Extra environment variables for the exec-server command. + Defaults to none. + token: Bearer secret shared between the gateway and the SDK. A random + value is generated when omitted. + ssl_context: Server TLS context for the gateway. A self-signed loopback + certificate is generated when omitted. + trust_gateway_ca: When a self-signed context is generated, add its CA to + a combined bundle and point ``SSL_CERT_FILE`` at it for the session, + so the native runtime trusts the gateway while keeping public CAs + (via ``certifi``) for the model provider. Restored on exit. Because + ``SSL_CERT_FILE`` is process-global, only one auto-managed + environment may be active per process; a concurrent second use + raises. To run several at once, pass your own ``ssl_context`` and set + ``trust_gateway_ca=False``, managing trust yourself. + """ + if not sandbox_name.startswith("sandboxes/"): + sandbox_name = f"sandboxes/{sandbox_name}" + _confirm_running(workspace_client, sandbox_name) + secret = token or secrets.token_urlsafe(32) + generated_ca: str | None = None + if ssl_context is None: + ssl_context, generated_ca = self_signed_server_context() + + gateway = SandboxExecServerGateway( + workspace_client=workspace_client, + sandbox_name=sandbox_name, + token=secret, + ssl_context=ssl_context, + exec_server_command=exec_server_command, + exec_server_env=exec_server_env, + ca_cert_path=generated_ca, + ) + handle = await gateway.start() + + restore: Callable[[], None] | None = None + try: + if trust_gateway_ca and handle.ca_cert_path is not None: + restore = _install_trust_bundle(handle.ca_cert_path) + yield Environment( + url=handle.url, + cwd=cwd, + tools=tuple(tools), + headers={"Authorization": f"Bearer {secret}"}, + ) + finally: + if restore is not None: + restore() + await gateway.aclose() + if generated_ca is not None: + with suppress(OSError): + os.unlink(generated_ca) + + +def _confirm_running(workspace_client: WorkspaceClient, sandbox_name: str) -> None: + """Confirm the sandbox is running before the gateway launches the exec-server. + + The gateway reaches the exec-server with ``execute_command``, which needs a + running sandbox. Lifecycle (create / start / poll until running) is the + caller's responsibility; see ``runner.py``. This is a fast precondition + check, not a wait. + """ + from databricks.sdk.service.sandbox import SandboxState + + sandbox = workspace_client.sandbox.get_sandbox(sandbox_name) + state = sandbox.status.state if sandbox.status is not None else None + if state != SandboxState.SANDBOX_STATE_RUNNING: + raise RuntimeError( + f"Sandbox {sandbox_name!r} is not running (state={state}). Create or start " + "it and poll until running before opening the environment (see runner.py)." + ) + + +def _install_trust_bundle(ca_cert_path: str) -> Callable[[], None]: + """Point ``SSL_CERT_FILE`` at ``certifi`` plus the gateway CA; return a restorer. + + The native runtime shares one trust store for the model provider and the + executor connection, so the gateway CA is appended to the public bundle + rather than replacing it. + + ``SSL_CERT_FILE`` is process-global, so this refuses to run while another + auto-managed environment is active rather than silently overwriting its + trust. The returned restorer rewinds the variable and removes the bundle. + """ + import certifi + + global _trust_active + with _trust_lock: + if _trust_active: + raise RuntimeError( + "databricks_sandbox_environment is already auto-managing SSL_CERT_FILE " + "for another active environment in this process. Auto-managed trust is " + "process-global and supports one environment at a time. To run several, " + "pass your own ssl_context and set trust_gateway_ca=False." + ) + _trust_active = True + + try: + with open(certifi.where(), "rb") as public_bundle: + public = public_bundle.read() + with open(ca_cert_path, "rb") as gateway_ca: + extra = gateway_ca.read() + + combined = tempfile.NamedTemporaryFile(prefix="dbx-trust-", suffix=".pem", delete=False) + with combined: + combined.write(public) + if not public.endswith(b"\n"): + combined.write(b"\n") + combined.write(extra) + + previous = os.environ.get("SSL_CERT_FILE") + os.environ["SSL_CERT_FILE"] = combined.name + except BaseException: + with _trust_lock: + _trust_active = False + raise + + def restore() -> None: + global _trust_active + if previous is None: + os.environ.pop("SSL_CERT_FILE", None) + else: + os.environ["SSL_CERT_FILE"] = previous + with suppress(OSError): + os.unlink(combined.name) + with _trust_lock: + _trust_active = False + + return restore diff --git a/examples/codex/databricks/gateway.py b/examples/codex/databricks/gateway.py new file mode 100644 index 0000000000..27de3189b1 --- /dev/null +++ b/examples/codex/databricks/gateway.py @@ -0,0 +1,272 @@ +"""A localhost WSS gateway that bridges the SDK executor to a sandbox exec-server. + +The native ``Environment`` dials an authenticated ``wss://`` endpoint and relays +the exec-server wire protocol over it. A Databricks sandbox runs that +exec-server in stdio mode, reached through the ``databricks-sdk`` streaming +command API (``WorkspaceClient.sandbox.execute_command``). Nothing in the SDK +speaks stdio and nothing in the sandbox speaks WebSocket, so this gateway sits +between them: it terminates the WebSocket, authenticates the bearer token, +opens the exec-server's stdio stream, and relays bytes in both directions. It is +the application-owned gateway described in the "remote execution" guide, like +``offline_docker.py`` but backed by a Databricks sandbox instead of Docker. + +The gateway frames on newlines: it sends one WebSocket message per line read +from exec-server stdout, and ensures each inbound message ends with a newline +before writing it to stdin. This matches the newline-delimited stdio framing +indicated by ``offline_docker.py``, which opens the exec-server stdio stream +with a 4 MiB line-reader limit; confirm the framing against the executor if the +protocol changes (see the example README). Because ``execute_command`` reaches +the sandbox outbound through the Databricks control plane, the gateway can run +on ``localhost`` next to the application; the sandbox needs no inbound ingress. +""" + +from __future__ import annotations + +import asyncio +import hmac +import http +import logging +import os +import ssl +from collections.abc import Mapping, Sequence +from contextlib import suppress +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any + +if TYPE_CHECKING: + from databricks.sdk import WorkspaceClient + from websockets.asyncio.server import ServerConnection + from websockets.http11 import Request, Response + +logger = logging.getLogger("examples.codex.databricks") + +# The sandbox runs the standalone exec-server over stdio; the gateway relays it. +_DEFAULT_EXEC_SERVER_COMMAND: tuple[str, ...] = ("codex", "exec-server", "--listen", "stdio") + +# Cap for inbound SDK->gateway WebSocket frames. The websockets default is 1 MiB, +# which would close the connection (1009) on a large apply_patch or write_stdin +# payload and kill the relay. Match offline_docker.py's 4 MiB exec-server line limit. +_MAX_WS_MESSAGE_BYTES = 4 * 1024 * 1024 + + +@dataclass(frozen=True, kw_only=True) +class GatewayHandle: + """A running gateway. + + Attributes: + url: The ``wss://`` endpoint to pass as ``Environment.url``. + ca_cert_path: Path to the CA that signed the gateway certificate, or + None when the caller supplied its own already-trusted context. Add + it to the trust store the native runtime uses (see + ``environment.databricks_sandbox_environment``). + """ + + url: str + ca_cert_path: str | None + + +class SandboxExecServerGateway: + """Serve one sandbox's exec-server over an authenticated localhost WebSocket. + + Args: + workspace_client: An authenticated ``databricks.sdk.WorkspaceClient``. + sandbox_name: The target sandbox name/id. + token: Shared secret the SDK must present as ``Authorization: Bearer``. + The provisioner puts the same value in ``Environment.headers``. + ssl_context: Server-side TLS context. ``Environment`` requires ``wss``, + so TLS is mandatory even on loopback. Use + ``self_signed_server_context`` for local runs or pass your own. + exec_server_command: Argv that starts the standalone exec-server over + stdio inside the sandbox. Defaults to + ``("codex", "exec-server", "--listen", "stdio")``, validated against + the sandbox image (``codex-cli`` 0.167.0). Override if a future image + changes the binary path or flags. + exec_server_env: Extra environment variables for the exec-server + command. Defaults to none. + host: Loopback interface to bind. + ca_cert_path: Path to the CA for ``ssl_context`` when self-signed, echoed + back on the handle so callers can trust it. + """ + + def __init__( + self, + *, + workspace_client: WorkspaceClient, + sandbox_name: str, + token: str, + ssl_context: ssl.SSLContext, + exec_server_command: Sequence[str] = _DEFAULT_EXEC_SERVER_COMMAND, + exec_server_env: Mapping[str, str] | None = None, + host: str = "127.0.0.1", + ca_cert_path: str | None = None, + ) -> None: + if not token: + raise ValueError("Gateway token must be a non-empty secret") + command = tuple(exec_server_command) + if not command: + raise ValueError("exec_server_command must name the exec-server program") + self._w = workspace_client + self._sandbox_name = sandbox_name + self._token = token + self._ssl_context = ssl_context + self._command = command + self._env = dict(exec_server_env) if exec_server_env is not None else {} + self._host = host + self._ca_cert_path = ca_cert_path + self._server: Any = None + + async def start(self) -> GatewayHandle: + """Bind the WebSocket server on an ephemeral port and start serving.""" + from websockets.asyncio.server import serve + + self._server = await serve( + self._handle, + self._host, + 0, + ssl=self._ssl_context, + process_request=self._process_request, + max_size=_MAX_WS_MESSAGE_BYTES, + ) + port = self._server.sockets[0].getsockname()[1] + return GatewayHandle(url=f"wss://{self._host}:{port}", ca_cert_path=self._ca_cert_path) + + async def aclose(self) -> None: + """Stop accepting connections and wait for the server to close.""" + if self._server is not None: + self._server.close() + await self._server.wait_closed() + self._server = None + + def _process_request(self, connection: ServerConnection, request: Request) -> Response | None: + """Reject an unauthenticated client at the HTTP handshake with 401.""" + presented = request.headers.get("Authorization", "") + if hmac.compare_digest(presented, f"Bearer {self._token}"): + return None + return connection.respond(http.HTTPStatus.UNAUTHORIZED, "unauthorized\n") + + async def _handle(self, connection: ServerConnection) -> None: + proc = await asyncio.to_thread(self._open_exec_server) + inbound = asyncio.create_task(self._ws_to_stdin(connection, proc)) + outbound = asyncio.create_task(self._stdout_to_ws(proc, connection)) + try: + await asyncio.wait({inbound, outbound}, return_when=asyncio.FIRST_COMPLETED) + finally: + # Closing the process unblocks the stdout read thread so both tasks finish. + await asyncio.to_thread(self._close_quietly, proc) + inbound.cancel() + outbound.cancel() + await asyncio.gather(inbound, outbound, return_exceptions=True) + + def _open_exec_server(self) -> Any: + return self._w.sandbox.execute_command( + self._sandbox_name, + self._command[0], + args=list(self._command[1:]), + envs=self._env or None, + text=False, + ) + + @staticmethod + def _close_quietly(proc: Any) -> None: + try: + proc.close() + except Exception: # teardown must not mask the real error + logger.debug("exec-server process close raised during teardown", exc_info=True) + + async def _ws_to_stdin(self, connection: ServerConnection, proc: Any) -> None: + async for message in connection: + data = message if isinstance(message, bytes) else message.encode() + if not data.endswith(b"\n"): + data += b"\n" # preserve newline message framing on stdin + await asyncio.to_thread(proc.stdin.write, data) + flush = getattr(proc.stdin, "flush", None) + if flush is not None: + await asyncio.to_thread(flush) + await asyncio.to_thread(self._close_stdin_quietly, proc) + + @staticmethod + def _close_stdin_quietly(proc: Any) -> None: + try: + proc.stdin.close() + except Exception: # half-closed stream during teardown + logger.debug("exec-server stdin close raised", exc_info=True) + + async def _stdout_to_ws(self, proc: Any, connection: ServerConnection) -> None: + # The exec-server protocol is newline-delimited JSON-RPC: every message is + # an object whose first non-space byte is '{'. The sandbox's codex prints a + # human-readable startup banner to stdout before the exec-server takes + # over; those non-JSON lines would corrupt the stream as bogus protocol + # frames. Drop the leading non-JSON preamble, then forward every line once + # the protocol starts (a no-op when stdout is JSON from the first line). + protocol_started = False + while True: + line = await asyncio.to_thread(proc.stdout.readline) + if not line: + break + if not protocol_started: + if not line.lstrip().startswith(b"{"): + logger.debug("dropping non-protocol stdout preamble: %r", line[:120]) + continue + protocol_started = True + await connection.send(line) # one WebSocket message per exec-server line + + +def self_signed_server_context(host: str = "127.0.0.1") -> tuple[ssl.SSLContext, str]: + """Build a TLS server context with an ephemeral self-signed certificate. + + Returns the server context and the path to the generated CA certificate so + the client side can trust it. Intended for local runs; supply your own + context and CA in production. Requires the ``cryptography`` dependency from + the example requirements. + + Args: + host: The loopback host the gateway binds, embedded as a SAN. + """ + import datetime + import ipaddress + import tempfile + + from cryptography import x509 + from cryptography.hazmat.primitives import hashes, serialization + from cryptography.hazmat.primitives.asymmetric import rsa + from cryptography.x509.oid import NameOID + + key = rsa.generate_private_key(public_exponent=65537, key_size=2048) + name = x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, host)]) + try: + san: x509.GeneralName = x509.IPAddress(ipaddress.ip_address(host)) + except ValueError: + san = x509.DNSName(host) + now = datetime.datetime.now(datetime.timezone.utc) + certificate = ( + x509.CertificateBuilder() + .subject_name(name) + .issuer_name(name) + .public_key(key.public_key()) + .serial_number(x509.random_serial_number()) + .not_valid_before(now - datetime.timedelta(minutes=5)) + .not_valid_after(now + datetime.timedelta(days=1)) + .add_extension(x509.SubjectAlternativeName([san]), critical=False) + .sign(key, hashes.SHA256()) + ) + + cert_pem = certificate.public_bytes(serialization.Encoding.PEM) + key_pem = key.private_bytes( + serialization.Encoding.PEM, + serialization.PrivateFormat.TraditionalOpenSSL, + serialization.NoEncryption(), + ) + cert_file = tempfile.NamedTemporaryFile(prefix="dbx-gw-", suffix=".crt", delete=False) + key_file = tempfile.NamedTemporaryFile(prefix="dbx-gw-", suffix=".key", delete=False) + with cert_file: + cert_file.write(cert_pem) + with key_file: + key_file.write(key_pem) + + context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER) + context.load_cert_chain(cert_file.name, key_file.name) + # load_cert_chain reads the key synchronously; drop the private key immediately. + with suppress(OSError): + os.unlink(key_file.name) + # The caller owns the returned cert path and must unlink it when done. + return context, cert_file.name diff --git a/examples/codex/databricks/requirements.txt b/examples/codex/databricks/requirements.txt new file mode 100644 index 0000000000..b437d0df42 --- /dev/null +++ b/examples/codex/databricks/requirements.txt @@ -0,0 +1,4 @@ +databricks-sdk[sandbox]>=0.153.0 +websockets>=13 +cryptography>=42 +certifi diff --git a/examples/codex/databricks/runner.py b/examples/codex/databricks/runner.py new file mode 100644 index 0000000000..1747599905 --- /dev/null +++ b/examples/codex/databricks/runner.py @@ -0,0 +1,157 @@ +"""Run an agent against a Databricks sandbox through the native executor. + +Prerequisites (see README.md): + - the SDK preview wheel plus this example's requirements.txt + - a Databricks sandbox whose image carries the ``codex`` exec-server + - Databricks auth (a CLI profile) + +Environment variables: + DATABRICKS_CONFIG_PROFILE Databricks CLI profile (default: DEFAULT) + SANDBOX_NAME sandbox id or ``sandboxes/`` resource name (required) + SANDBOX_CWD remote workspace path (default: /home/sandbox-agent/work) + SANDBOX_CREATE "1" to provision the sandbox if absent (default: off) + SANDBOX_IMAGE image with the codex exec-server (used when creating) + SANDBOX_INACTIVITY_TIMEOUT_S auto-stop timeout in seconds (default: 900) + OPENAI_MODEL model name (default: gpt-5.5) + OPENAI_BASE_URL model-provider base URL (default: the workspace's + Databricks AI Gateway codex endpoint) + OPENAI_API_KEY model-provider key (default: a token minted from the + Databricks profile, so no OpenAI key is needed) + +With SANDBOX_CREATE=1 the runner provisions the sandbox. In all cases it then +confirms the sandbox is running (starting it if stopped and polling until ready) +and ensures the workspace directory exists before opening +``databricks_sandbox_environment`` - the gateway reaches the exec-server through +``execute_command``, which needs a running sandbox. The gateway launches +``exec-server stdio`` on each connection, so no separate exec-server start is +needed here; a sandbox that auto-stops is started again before the next session. + +By default the model runs through the sandbox workspace's Databricks AI Gateway +codex endpoint, authenticated with the profile's own token (PAT or OAuth), so no +OpenAI key is required. Set OPENAI_BASE_URL / OPENAI_API_KEY to use a different +provider (for example OpenAI directly). + +Run: + SANDBOX_NAME=openai-agent-sandbox DATABRICKS_CONFIG_PROFILE=my-workspace \ + PYTHONPATH=. python -m examples.codex.databricks.runner "Inspect the project" +""" + +import asyncio +import os +import sys +import time + +from databricks.sdk import WorkspaceClient + +from agents import Agent, NativeProvider +from examples.codex.databricks.environment import databricks_sandbox_environment + + +def _resource_name(name: str) -> str: + """Return the ``sandboxes/`` resource name the sandbox SDK APIs expect.""" + return name if name.startswith("sandboxes/") else f"sandboxes/{name}" + + +def _ensure_sandbox(workspace_client: WorkspaceClient, sandbox_id: str) -> str: + """Provision the sandbox and return its ``sandboxes/`` resource name. + + Mirrors the Databricks sandbox cookbook. Confirm the spec types and their + import path against your installed ``databricks-sdk`` - the sandbox service + module layout may differ by SDK version. + """ + # databricks-sdk re-exports Duration without __all__, so strict mypy flags it. + from databricks.sdk.service.sandbox import ( # type: ignore[attr-defined] + ComputeSpec, + Duration, + EnvironmentSpec, + Sandbox, + SandboxSpec, + ) + + timeout_s = int(os.getenv("SANDBOX_INACTIVITY_TIMEOUT_S", "900")) + spec = SandboxSpec(compute=ComputeSpec(inactivity_timeout=Duration(seconds=timeout_s))) + image = os.getenv("SANDBOX_IMAGE") + if image is not None: + spec.environment = EnvironmentSpec(image_uri=image) + created = workspace_client.sandbox.create_sandbox(Sandbox(spec=spec), sandbox_id=sandbox_id) + return created.name or _resource_name(sandbox_id) + + +def _wait_until_running( + workspace_client: WorkspaceClient, sandbox_name: str, timeout_s: int = 300 +) -> None: + """Confirm the sandbox is running before the exec-server is launched. + + Starts a stopped sandbox, then polls until it reports running. Mirrors the + managed-API pattern of polling status before launching the exec-server. + """ + from databricks.sdk.service.sandbox import SandboxState + + deadline = time.monotonic() + timeout_s + started = False + while True: + sandbox = workspace_client.sandbox.get_sandbox(sandbox_name) + state = sandbox.status.state if sandbox.status is not None else None + if state == SandboxState.SANDBOX_STATE_RUNNING: + return + if state == SandboxState.SANDBOX_STATE_STOPPED and not started: + workspace_client.sandbox.start_sandbox(sandbox_name) + started = True + if time.monotonic() > deadline: + raise TimeoutError(f"sandbox {sandbox_name!r} not running (state={state})") + time.sleep(2) + + +def _model_credentials(workspace_client: WorkspaceClient) -> tuple[str, str]: + """Return ``(base_url, api_key)`` for ``NativeProvider``. + + Defaults to the workspace's Databricks AI Gateway codex endpoint, with a + token minted from the Databricks profile (PAT or OAuth) - no OpenAI key + needed. Override with OPENAI_BASE_URL / OPENAI_API_KEY for another provider. + """ + host = (workspace_client.config.host or "").rstrip("/") + base_url = os.getenv("OPENAI_BASE_URL") or f"{host}/ai-gateway/codex/v1" + api_key = os.getenv("OPENAI_API_KEY") + if not api_key: + authorization = workspace_client.config.authenticate().get("Authorization", "") + api_key = authorization.removeprefix("Bearer ").strip() + return base_url, api_key + + +async def main(task: str) -> None: + workspace_client = WorkspaceClient(profile=os.getenv("DATABRICKS_CONFIG_PROFILE", "DEFAULT")) + requested = os.environ["SANDBOX_NAME"] + if os.getenv("SANDBOX_CREATE") == "1": + sandbox_name = _ensure_sandbox(workspace_client, requested.removeprefix("sandboxes/")) + else: + sandbox_name = _resource_name(requested) + _wait_until_running(workspace_client, sandbox_name) + + cwd = os.getenv("SANDBOX_CWD", "/home/sandbox-agent/work") + workspace_client.sandbox.execute_command_sync( + sandbox_name, "/bin/bash", args=["-lc", f"mkdir -p {cwd}"] + ) + + base_url, api_key = _model_credentials(workspace_client) + async with databricks_sandbox_environment( + workspace_client=workspace_client, + sandbox_name=sandbox_name, + cwd=cwd, + ) as environment: + async with NativeProvider( + base_url=base_url, + api_key=api_key, + supports_websockets=False, + ) as provider: + agent = Agent( + instructions="Inspect the assigned workspace and report findings.", + model=os.getenv("OPENAI_MODEL", "gpt-5.5"), + provider=provider, + ) + async with agent.session(environment=environment) as session: + result = await (await session.submit(task)).get_result() + print(result.final_output) + + +if __name__ == "__main__": + asyncio.run(main(" ".join(sys.argv[1:]) or "Inspect the assigned workspace")) diff --git a/tests/codex/test_databricks_environment.py b/tests/codex/test_databricks_environment.py new file mode 100644 index 0000000000..a3d8afa7a5 --- /dev/null +++ b/tests/codex/test_databricks_environment.py @@ -0,0 +1,237 @@ +"""Tests for the Databricks sandbox environment example context manager. + +Cover the public entry point (Environment wiring, teardown, trust handling) and +the ``SSL_CERT_FILE`` bundle helper. Run from the repo root with the preview +wheel and ``examples/codex/databricks/requirements.txt`` installed. +""" + +from __future__ import annotations + +import os +import queue +import ssl +from pathlib import Path +from types import SimpleNamespace +from typing import TYPE_CHECKING, Any, cast + +import pytest + +pytest.importorskip("websockets") +pytest.importorskip("cryptography") +pytest.importorskip("certifi") + +from databricks.sdk.service.sandbox import SandboxState # noqa: E402 +from websockets.asyncio.client import connect # noqa: E402 + +from examples.codex.databricks.environment import ( # noqa: E402 + _install_trust_bundle, + databricks_sandbox_environment, +) + +if TYPE_CHECKING: + from databricks.sdk import WorkspaceClient + +_FAKE_CA = b"-----BEGIN CERTIFICATE-----\nFAKE\n-----END CERTIFICATE-----\n" + + +class _FakeStdin: + def __init__(self) -> None: + self.written = bytearray() + + def write(self, data: bytes) -> None: + self.written.extend(data) + + def flush(self) -> None: + pass + + def close(self) -> None: + pass + + +class _FakeStdout: + def __init__(self) -> None: + self._lines: queue.Queue[bytes | None] = queue.Queue() + + def eof(self) -> None: + self._lines.put(None) + + def readline(self) -> bytes: + item = self._lines.get() + return b"" if item is None else item + + +class _FakeProcess: + def __init__(self) -> None: + self.stdin = _FakeStdin() + self.stdout = _FakeStdout() + + def close(self) -> None: + self.stdout.eof() + + +class _FakeSandbox: + def __init__(self, proc: _FakeProcess, state: Any = None) -> None: + self._proc = proc + self._state = state if state is not None else SandboxState.SANDBOX_STATE_RUNNING + + def get_sandbox(self, name: str) -> SimpleNamespace: + return SimpleNamespace(status=SimpleNamespace(state=self._state)) + + def execute_command( + self, + name: str, + program: str, + args: list[str], + text: bool, + envs: dict[str, str] | None = None, + ) -> _FakeProcess: + return self._proc + + +class _FakeWorkspaceClient: + def __init__(self, proc: _FakeProcess, state: Any = None) -> None: + self.sandbox = _FakeSandbox(proc, state) + + +async def test_rejects_non_running_sandbox(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.delenv("SSL_CERT_FILE", raising=False) + client = _FakeWorkspaceClient(_FakeProcess(), SandboxState.SANDBOX_STATE_STOPPED) + with pytest.raises(RuntimeError, match="not running"): + async with databricks_sandbox_environment( + workspace_client=cast("WorkspaceClient", client), + sandbox_name="sbx", + cwd="/w", + token="t", + ): + pass + assert "SSL_CERT_FILE" not in os.environ + + +async def test_environment_wiring(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.delenv("SSL_CERT_FILE", raising=False) + client = _FakeWorkspaceClient(_FakeProcess()) + async with databricks_sandbox_environment( + workspace_client=cast("WorkspaceClient", client), + sandbox_name="sbx", + cwd="/home/sandbox-agent/work", + token="tok-123", + ) as environment: + assert environment.url.startswith("wss://127.0.0.1:") + assert environment.cwd == "/home/sandbox-agent/work" + # Environment lowercases header names. + assert environment.headers["authorization"] == "Bearer tok-123" + assert tuple(environment.tools) == ("exec_command", "write_stdin", "apply_patch") + assert "SSL_CERT_FILE" in os.environ + assert "SSL_CERT_FILE" not in os.environ + + +async def test_trust_gateway_ca_false_leaves_env(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.delenv("SSL_CERT_FILE", raising=False) + client = _FakeWorkspaceClient(_FakeProcess()) + async with databricks_sandbox_environment( + workspace_client=cast("WorkspaceClient", client), + sandbox_name="sbx", + cwd="/w", + token="t", + trust_gateway_ca=False, + ): + assert "SSL_CERT_FILE" not in os.environ + assert "SSL_CERT_FILE" not in os.environ + + +async def test_restores_and_closes_on_exception(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("SSL_CERT_FILE", "/orig") + client = _FakeWorkspaceClient(_FakeProcess()) + captured: dict[str, str] = {} + with pytest.raises(RuntimeError, match="boom"): + async with databricks_sandbox_environment( + workspace_client=cast("WorkspaceClient", client), + sandbox_name="sbx", + cwd="/w", + token="t", + ) as environment: + captured["url"] = environment.url + raise RuntimeError("boom") + + assert os.environ["SSL_CERT_FILE"] == "/orig" + + context = ssl.create_default_context() + context.check_hostname = False + context.verify_mode = ssl.CERT_NONE + with pytest.raises(OSError): + async with connect(captured["url"], ssl=context): + pass + + +def test_install_trust_bundle_sets_and_restores( + monkeypatch: pytest.MonkeyPatch, tmp_path: Path +) -> None: + import certifi + + ca = tmp_path / "ca.pem" + ca.write_bytes(_FAKE_CA) + monkeypatch.delenv("SSL_CERT_FILE", raising=False) + + restore = _install_trust_bundle(str(ca)) + bundle = Path(os.environ["SSL_CERT_FILE"]).read_bytes() + assert Path(certifi.where()).read_bytes() in bundle + assert _FAKE_CA in bundle + + restore() + assert "SSL_CERT_FILE" not in os.environ + + +def test_install_trust_bundle_restores_previous( + monkeypatch: pytest.MonkeyPatch, tmp_path: Path +) -> None: + ca = tmp_path / "ca.pem" + ca.write_bytes(_FAKE_CA) + monkeypatch.setenv("SSL_CERT_FILE", "/x") + + restore = _install_trust_bundle(str(ca)) + assert os.environ["SSL_CERT_FILE"] != "/x" + + restore() + assert os.environ["SSL_CERT_FILE"] == "/x" + + +def test_install_trust_bundle_rejects_concurrent( + monkeypatch: pytest.MonkeyPatch, tmp_path: Path +) -> None: + import examples.codex.databricks.environment as env_mod + + ca = tmp_path / "ca.pem" + ca.write_bytes(_FAKE_CA) + monkeypatch.delenv("SSL_CERT_FILE", raising=False) + + first = _install_trust_bundle(str(ca)) + bundle_path = os.environ["SSL_CERT_FILE"] + try: + with pytest.raises(RuntimeError, match="one environment at a time"): + _install_trust_bundle(str(ca)) + finally: + first() + + # The guard is released, the bundle is gone, and a fresh install works. + assert env_mod._trust_active is False + assert not os.path.exists(bundle_path) + second = _install_trust_bundle(str(ca)) + second() + + +def test_install_trust_bundle_rolls_back_on_failure( + monkeypatch: pytest.MonkeyPatch, tmp_path: Path +) -> None: + import examples.codex.databricks.environment as env_mod + + monkeypatch.delenv("SSL_CERT_FILE", raising=False) + with pytest.raises(OSError): + _install_trust_bundle(str(tmp_path / "does-not-exist.pem")) + + # The guard is rolled back and no env var leaked, so later calls still work. + assert env_mod._trust_active is False + assert "SSL_CERT_FILE" not in os.environ + ca = tmp_path / "ca.pem" + ca.write_bytes(_FAKE_CA) + restore = _install_trust_bundle(str(ca)) + restore() diff --git a/tests/codex/test_databricks_gateway.py b/tests/codex/test_databricks_gateway.py new file mode 100644 index 0000000000..19e4776bb4 --- /dev/null +++ b/tests/codex/test_databricks_gateway.py @@ -0,0 +1,262 @@ +"""Relay and auth tests for the Databricks sandbox gateway example. + +These exercise the certain core - byte relay and bearer auth - with a fake +``CommandProcess`` and a real TLS WebSocket client. Run from the repo root with +the preview wheel and ``examples/codex/databricks/requirements.txt`` installed. +""" + +from __future__ import annotations + +import queue +import ssl +from typing import TYPE_CHECKING, Any, cast + +import pytest + +pytest.importorskip("websockets") +pytest.importorskip("cryptography") + +from websockets.asyncio.client import connect # noqa: E402 +from websockets.exceptions import ConnectionClosed, InvalidStatus # noqa: E402 + +from examples.codex.databricks.gateway import ( # noqa: E402 + SandboxExecServerGateway, + self_signed_server_context, +) + +if TYPE_CHECKING: + from databricks.sdk import WorkspaceClient + + +class _FakeStdin: + def __init__(self) -> None: + self.written = bytearray() + self.closed = False + + def write(self, data: bytes) -> None: + self.written.extend(data) + + def flush(self) -> None: + pass + + def close(self) -> None: + self.closed = True + + +class _FakeStdout: + """Blocking stdout fed from the test; ``readline`` returns b'' after EOF.""" + + def __init__(self) -> None: + self._lines: queue.Queue[bytes | None] = queue.Queue() + + def feed(self, data: bytes) -> None: + self._lines.put(data) + + def eof(self) -> None: + self._lines.put(None) + + def readline(self) -> bytes: + item = self._lines.get() + return b"" if item is None else item + + +class _FakeProcess: + def __init__(self) -> None: + self.stdin = _FakeStdin() + self.stdout = _FakeStdout() + self.closed = False + + def close(self) -> None: + self.closed = True + self.stdout.eof() + + +class _FakeSandbox: + def __init__(self, proc: _FakeProcess) -> None: + self._proc = proc + self.calls: list[tuple[str, str, list[str]]] = [] + self.envs: list[dict[str, str] | None] = [] + + def execute_command( + self, + name: str, + program: str, + args: list[str], + text: bool, + envs: dict[str, str] | None = None, + ) -> _FakeProcess: + assert text is False + self.calls.append((name, program, args)) + self.envs.append(envs) + return self._proc + + +class _FakeWorkspaceClient: + def __init__(self, proc: _FakeProcess) -> None: + self.sandbox = _FakeSandbox(proc) + + +def _client_ssl(ca_path: str) -> ssl.SSLContext: + context = ssl.create_default_context(cafile=ca_path) + return context + + +async def _start(proc: _FakeProcess, token: str = "s3cret") -> tuple[SandboxExecServerGateway, Any]: + server_ctx, ca_path = self_signed_server_context("127.0.0.1") + gateway = SandboxExecServerGateway( + workspace_client=cast("WorkspaceClient", _FakeWorkspaceClient(proc)), + sandbox_name="sbx", + token=token, + ssl_context=server_ctx, + ca_cert_path=ca_path, + ) + handle = await gateway.start() + return gateway, handle + + +async def test_relay_both_directions() -> None: + proc = _FakeProcess() + client = _FakeWorkspaceClient(proc) + server_ctx, ca_path = self_signed_server_context("127.0.0.1") + gateway = SandboxExecServerGateway( + workspace_client=cast("WorkspaceClient", client), + sandbox_name="sbx", + token="s3cret", + ssl_context=server_ctx, + ca_cert_path=ca_path, + ) + handle = await gateway.start() + try: + async with connect( + handle.url, + ssl=_client_ssl(ca_path), + additional_headers={"Authorization": "Bearer s3cret"}, + ) as ws: + await ws.send(b"hello-stdin") + proc.stdout.feed(b'{"jsonrpc":"2.0","id":1,"result":{}}\n') + received = await ws.recv() + # One WebSocket message per exec-server line; JSON-RPC protocol frame. + assert received == b'{"jsonrpc":"2.0","id":1,"result":{}}\n' + finally: + await gateway.aclose() + + # The gateway appends the newline framing when the client omits it. + assert proc.stdin.written == b"hello-stdin\n" + assert proc.closed is True + assert proc.stdin.closed is True + assert client.sandbox.calls[0] == ("sbx", "codex", ["exec-server", "--listen", "stdio"]) + assert client.sandbox.envs[0] is None + + +async def test_drops_startup_banner_preamble() -> None: + proc = _FakeProcess() + gateway, handle = await _start(proc) + try: + async with connect( + handle.url, + ssl=_client_ssl(handle.ca_cert_path or ""), + additional_headers={"Authorization": "Bearer s3cret"}, + ) as ws: + # The sandbox's codex prints a startup banner to stdout before the real + # exec-server protocol. Those non-JSON lines must not reach the client. + proc.stdout.feed("✔ Databricks auth available\n".encode()) + proc.stdout.feed("╭- Launching Codex with Unity Gateway -╮\n".encode()) + proc.stdout.feed(b"\n") + proc.stdout.feed(b'{"jsonrpc":"2.0","id":1,"result":{}}\n') + proc.stdout.feed(b'{"method":"process/output","params":{"seq":1}}\n') + first = await ws.recv() + second = await ws.recv() + assert first == b'{"jsonrpc":"2.0","id":1,"result":{}}\n' + assert second == b'{"method":"process/output","params":{"seq":1}}\n' + finally: + await gateway.aclose() + + +async def test_relays_large_inbound_frame() -> None: + # A payload above the websockets 1 MiB default (e.g. a big apply_patch) must + # still reach stdin rather than closing the connection with 1009. + proc = _FakeProcess() + gateway, handle = await _start(proc) + payload = b"x" * (2 * 1024 * 1024) + try: + async with connect( + handle.url, + ssl=_client_ssl(handle.ca_cert_path or ""), + additional_headers={"Authorization": "Bearer s3cret"}, + max_size=4 * 1024 * 1024, + ) as ws: + await ws.send(payload) + proc.stdout.feed(b'{"jsonrpc":"2.0","id":1,"result":{}}\n') + assert await ws.recv() == b'{"jsonrpc":"2.0","id":1,"result":{}}\n' + finally: + await gateway.aclose() + + assert proc.stdin.written == payload + b"\n" + + +async def test_rejects_wrong_token() -> None: + proc = _FakeProcess() + gateway, handle = await _start(proc) + try: + with pytest.raises(InvalidStatus): + async with connect( + handle.url, + ssl=_client_ssl(handle.ca_cert_path or ""), + additional_headers={"Authorization": "Bearer wrong"}, + ): + pass + finally: + await gateway.aclose() + + assert proc.stdin.written == b"" + + +class _RaisingSandbox: + def execute_command(self, name: str, program: str, args: list[str], text: bool) -> Any: + raise RuntimeError("exec-server unavailable") + + +class _RaisingWorkspaceClient: + def __init__(self) -> None: + self.sandbox = _RaisingSandbox() + + +async def test_closes_websocket_when_exec_server_exits() -> None: + proc = _FakeProcess() + gateway, handle = await _start(proc) + try: + async with connect( + handle.url, + ssl=_client_ssl(handle.ca_cert_path or ""), + additional_headers={"Authorization": "Bearer s3cret"}, + ) as ws: + proc.stdout.eof() # exec-server exits first + with pytest.raises(ConnectionClosed): + await ws.recv() + finally: + await gateway.aclose() + + assert proc.closed is True + + +async def test_connection_fails_when_exec_server_cannot_start() -> None: + server_ctx, ca_path = self_signed_server_context("127.0.0.1") + gateway = SandboxExecServerGateway( + workspace_client=cast("WorkspaceClient", _RaisingWorkspaceClient()), + sandbox_name="sbx", + token="s3cret", + ssl_context=server_ctx, + ca_cert_path=ca_path, + ) + handle = await gateway.start() + try: + for _ in range(2): # the gateway keeps serving after a failed connection + async with connect( + handle.url, + ssl=_client_ssl(ca_path), + additional_headers={"Authorization": "Bearer s3cret"}, + ) as ws: + with pytest.raises(ConnectionClosed): + await ws.recv() + finally: + await gateway.aclose() From d38f036d174224a841577d86d95c7fbbba19cf72 Mon Sep 17 00:00:00 2001 From: Hsing Tang Date: Mon, 16 Nov 2026 21:34:42 +0000 Subject: [PATCH 2/9] feat: back Databricks sandbox executor with native stdio_command Replace the wss gateway example with a DatabricksStdioEnvironment that subclasses the native Environment and declares a host-owned stdio_command, mirroring the SDK's Docker stdio executor. The native runtime spawns a local launcher (launch.py) and speaks the exec-server protocol over its stdio; the launcher relays that to `codex exec-server --listen stdio` in the sandbox over the databricks-sdk streaming command API. This drops the loopback WebSocket server, self-signed TLS, CA-trust juggling, and bearer-token handshake. Relax the native stdio admission guard to accept a sanctioned stdio:// host-owned source alongside docker://, so non-Docker backends can supply a trusted host-owned stdio executor; the headers-empty invariant is unchanged. Add Rust unit tests for stdio:// acceptance and unknown-scheme rejection. Rewrite the example tests to cover stdio_command emission, stdio:///header validation, the factory precondition and credential/launcher wiring, and the launcher's startup-banner filter. Co-authored-by: Isaac --- examples/codex/databricks/README.md | 189 ++++++-------- examples/codex/databricks/environment.py | 267 +++++++------------ examples/codex/databricks/gateway.py | 272 ------------------- examples/codex/databricks/launch.py | 84 ++++++ examples/codex/databricks/requirements.txt | 3 - examples/codex/databricks/runner.py | 42 +-- packages/codex/rust/environment.rs | 56 +++- tests/codex/test_databricks_environment.py | 287 +++++++-------------- tests/codex/test_databricks_gateway.py | 262 ------------------- tests/codex/test_databricks_launcher.py | 52 ++++ 10 files changed, 472 insertions(+), 1042 deletions(-) delete mode 100644 examples/codex/databricks/gateway.py create mode 100644 examples/codex/databricks/launch.py delete mode 100644 tests/codex/test_databricks_gateway.py create mode 100644 tests/codex/test_databricks_launcher.py diff --git a/examples/codex/databricks/README.md b/examples/codex/databricks/README.md index a2d5fb9ffd..ffa4979cbe 100644 --- a/examples/codex/databricks/README.md +++ b/examples/codex/databricks/README.md @@ -2,86 +2,72 @@ Back a native `Environment` with a Databricks sandbox, so an agent driven by this SDK runs `exec_command` / `write_stdin` / `apply_patch` inside the sandbox. -This is the "remote execution" pattern from `docs/sdk/execution.md` - an -application-owned gateway plus a lifetime-managing `Environment` context manager - -the Databricks counterpart of `examples/codex/offline_docker.py`. - -> **Validated end-to-end against a live Databricks sandbox (2026-11-11).** -> The native `Environment` connected to the gateway's `wss://` endpoint and drove -> a real `codex exec-server --listen stdio`. `NativeProvider` -> ran against the sandbox's Databricks AI Gateway codex endpoint (PAT from -> `~/.databrickscfg`; no OpenAI key). `openai-agents` 0.24.0-alpha.7 (the preview -> wheel) on Ubuntu 24.04 / glibc 2.39. -> -> Validated two ways: with the controller co-located in the sandbox (a local -> exec-server subprocess), and with an **external controller** (a glibc-2.39 -> container) driving a separate sandbox over the real `databricks-sdk` -> `execute_command` streaming transport - the actual product topology, tool -> side-effects confirmed back in the executor sandbox. -> -> Exercised through this gateway over that transport (tool calls scripted -> deterministically with the SDK's Responses fixture): -> -> - **Multi-turn, resume, and sandbox stop-start.** Two turns in one session -> (turn 2 read turn 1's file); a fresh session relaunched the exec-server; a -> real `stop_sandbox` + `start_sandbox` cycle returned to service with the -> workspace preserved. -> - **All three tools.** `exec_command`, interactive-TTY `write_stdin`, and -> `apply_patch` (which added a file in the sandbox). -> - **Large output.** A 200k-line stream and a single ~4 MB line both relayed -> through the newline framing without truncation. -> - **Environment policy hooks.** `approval` returning `False` blocked a -> command's side-effect; `transform_arguments` rewrote the command; -> `transform_result` changed what the model saw; a `NetworkPolicy` was -> **enforced** by the executor's managed proxy (an allowed domain returned 200, -> a non-allowed domain was blocked). -> - **Model.** `model="gpt-5.5"` is served by `system.ai.gpt-5-5` on the AI -> Gateway. -> - **Startup-banner handling.** The sandbox's `codex` prints a startup banner to -> stdout before the protocol; a live turn confirmed the gateway drops that -> non-JSON preamble and the tool still executes (`proof_pw.txt` created). -> - **Static checks.** `pytest tests/codex` (14 passed) and `mypy --strict` run -> against the preview wheel on a glibc-2.39 host. +This is the "remote execution" pattern from `docs/sdk/execution.md`, built the +same way the SDK's own Docker support is: an `Environment` subclass declares a +host-owned `stdio_command` that the native runtime spawns, and the runtime +speaks the exec-server protocol over that process's stdin/stdout. It is the +Databricks counterpart of `agents.sandbox.DockerGateway` / +`examples/codex/offline_docker.py`. + +> **Status.** The stdio transport and the full turn are validated end-to-end +> against a live Databricks sandbox on the `0.24.0-alpha.8` preview wheel: a real +> `codex exec-server` ran the agent's tool call in the sandbox with no gateway +> server and no TLS, driven over the `databricks-sdk` streaming command API, for +> both model providers (Databricks AI Gateway and OpenAI direct). The `stdio://` +> executor source this example uses requires an Agents SDK build that includes +> the host-owned stdio admission change in this PR's native runtime +> (`packages/codex/rust/environment.rs`); it is not yet in a released preview +> wheel. Until it ships, build the SDK from this branch (see +> `packages/codex/MAINTAINING.md`). The Python pieces are covered by +> `tests/codex/` against the released wheel. ## How it works -The native `Environment` dials an authenticated `wss://` executor and relays the -exec-server protocol over it. A Databricks sandbox runs that exec-server in -stdio mode, reached through the `databricks-sdk` streaming command API -(`WorkspaceClient.sandbox.execute_command`). Nothing in the SDK speaks stdio and -nothing in the sandbox speaks WebSocket, so `SandboxExecServerGateway` -(`gateway.py`) bridges them: it terminates the WebSocket, authenticates the -bearer token at the HTTP handshake, opens the exec-server's stdio, and relays -bytes both ways. It does not parse the protocol; it only drops a startup banner -the sandbox's `codex` prints on stdout before the protocol begins (non-JSON -lines) so it never reaches the SDK as a bogus message. +`DatabricksStdioEnvironment` (`environment.py`) subclasses the native +`Environment` and emits a `stdio_command`: the argv of a local launcher process. +When the session opens, the native runtime spawns that launcher and speaks the +exec-server wire protocol over its stdin/stdout. The launcher (`launch.py`) +relays that protocol to `codex exec-server --listen stdio` inside the sandbox +over the `databricks-sdk` streaming command API +(`WorkspaceClient.sandbox.execute_command`, whose `CommandProcess` exposes the +command's `stdin`, `stdout` and exit). It does not parse the protocol; it only +drops a startup banner the sandbox's `codex` prints on stdout before the protocol +begins (non-JSON lines) so it never reaches the runtime as a bogus message. + +Because the runtime owns the launcher process and talks to it over ordinary +pipes, there is no WebSocket gateway, no TLS termination, and no shared-secret +handshake. `execute_command` reaches the sandbox outbound through the Databricks +control plane, so the sandbox needs no inbound ingress. The agent loop runs in +your process (via `NativeProvider`), which is what makes the `Environment` +approval / transform callbacks and `NetworkPolicy` available. `databricks_sandbox_environment` (`environment.py`) confirms the sandbox is -running, starts that gateway, and yields a configured `Environment`, so the whole -lifecycle fits one `async with` (the "manage the executor lifetime" pattern). +running, derives the workspace host and token from the `WorkspaceClient`, and +returns a configured `DatabricksStdioEnvironment` to hand to +`agent.session(environment=...)`. -Because `execute_command` reaches the sandbox outbound through the Databricks -control plane, the gateway runs on loopback next to the application and the -sandbox needs no inbound ingress. The agent loop runs in your process (via -`NativeProvider`), which is what makes the `Environment` approval / transform -callbacks and `NetworkPolicy` available. +> This subclass overrides `Environment._to_native` and `_validate_remote_url`, +> which are preview internals and can change across SDK builds. It mirrors the +> SDK's own `_DockerStdioEnvironment`. ## Files -- `gateway.py` - `SandboxExecServerGateway` plus a self-signed loopback TLS helper. -- `environment.py` - `databricks_sandbox_environment`, the lifetime context manager. +- `environment.py` - `DatabricksStdioEnvironment` and the + `databricks_sandbox_environment` factory. +- `launch.py` - the launcher the native runtime spawns to bridge stdio to the + sandbox. - `runner.py` - a runnable end-to-end example. ## Install and run -The v1.0 SDK is a GitHub preview wheel (off PyPI); this example is validated -against `openai-agents` 0.24.0-alpha.7. The wheel ships a compiled native -runtime, so it needs a supported host: **Linux x86_64 with glibc 2.39 or -newer**, macOS arm64, or Windows x64. Get the wheel URL from -`docs/sdk/installation.md`, then install it and this example's requirements: +The v1.0 SDK is a GitHub preview wheel (off PyPI). It ships a compiled native +runtime, so it needs a supported host: **Linux x86_64 with glibc 2.28 or newer**, +macOS arm64, or Windows x64. This example additionally needs the host-owned +`stdio://` executor source (see **Status** above), so build the SDK from this +branch per `packages/codex/MAINTAINING.md` until that change is in a released +wheel. Then install this example's requirements: ```sh -pip install "" # URL in docs/sdk/installation.md pip install -r examples/codex/databricks/requirements.txt ``` @@ -95,9 +81,9 @@ SANDBOX_NAME=openai-agent-sandbox DATABRICKS_CONFIG_PROFILE=my-workspace \ ``` `SANDBOX_NAME` accepts the bare id or the `sandboxes/` resource name. Set -`SANDBOX_CREATE=1` (with `SANDBOX_IMAGE=...`) to provision the sandbox first; -`exec-server` is killed when the sandbox stops, so a new connection after a stop -relaunches it. +`SANDBOX_CREATE=1` (with `SANDBOX_IMAGE=...`) to provision the sandbox first. The +launcher starts `exec-server` on each session; it is killed when the sandbox +stops and relaunched on the next session. To run the model through OpenAI directly instead of the Databricks AI Gateway, set `OPENAI_BASE_URL`, `OPENAI_API_KEY`, and an OpenAI model id your account can @@ -110,66 +96,35 @@ SANDBOX_NAME=openai-agent-sandbox DATABRICKS_CONFIG_PROFILE=my-workspace \ PYTHONPATH=. python -m examples.codex.databricks.runner "Inspect the workspace" ``` -Only the model provider changes; the sandbox, gateway, and tools are identical. +Only the model provider changes; the sandbox, launcher, and tools are identical. -## TLS - -`Environment` requires `wss`, so the gateway needs TLS even on loopback. By -default `databricks_sandbox_environment` generates an ephemeral self-signed -certificate and, for the session, points `SSL_CERT_FILE` at a bundle of the -public CAs (`certifi`) plus that certificate, then restores it on exit - so the -native runtime trusts the gateway without breaking model-provider TLS. This -mirrors the `remote_executor.py` guidance ("Set `SSL_CERT_FILE` to your executor -CA if it uses a private certificate"). Pass your own `ssl_context` and set -`trust_gateway_ca=False` to manage trust yourself. - -`SSL_CERT_FILE` is process-global, so auto-managed trust supports only one -environment per process; a concurrent second use raises rather than silently -corrupting trust. Open design question for OAI: a per-connection trust lever on -`Environment` (a client CA / SSL context) would let a self-hosted gateway avoid -mutating a process-global variable. - -## Prerequisites (validated 2026-11-11 against a Databricks sandbox) +## Prerequisites 1. **A running sandbox.** The application creates the sandbox (or reuses one), starts it if stopped, and polls its status until running before opening the environment - the exec-server is reached through `execute_command`, which needs a running sandbox. `runner.py` shows this, and - `databricks_sandbox_environment` confirms it before starting the gateway. -2. **exec-server stdio mode in the image - SUPPORTED.** The sandbox's `codex` - runs the standalone exec-server over stdio with `codex exec-server --listen - stdio`, which the gateway relays. -3. **Streaming bidirectional relay over `execute_command` - CONFIRMED.** An - external-controller turn drove tool calls through the gateway to the - exec-server and back over the real `databricks-sdk` `execute_command` - streaming `CommandProcess` (`stdin`, `stdout.readline`, `text=False`), - creating a file in the executor sandbox's workspace. -4. **WebSocket newline framing - CONFIRMED by the live turn.** The gateway frames - on newlines (one message per `stdout.readline`, newline appended inbound). The - live turn's tool calls parsed and executed, so the framing matches the - exec-server's stdio protocol. + `databricks_sandbox_environment` confirms it. +2. **exec-server stdio mode in the image.** The sandbox's `codex` runs the + standalone exec-server over stdio with `codex exec-server --listen stdio`, + which the launcher relays. +3. **An SDK build with the host-owned `stdio://` executor source** (see + **Status**). ## Tests -`tests/codex/test_databricks_gateway.py` and `test_databricks_environment.py` -cover the relay, startup-banner filtering, bearer auth, the large-frame cap, -teardown paths, the context manager, the running-sandbox precondition, and the -`SSL_CERT_FILE` trust-bundle helper with a fake `CommandProcess`. Install the -preview wheel, this example's requirements, and `pytest` + `pytest-asyncio`, -then run them explicitly from the repo root (the default `testpaths` does not -include `tests/codex`): +`tests/codex/test_databricks_environment.py` and `test_databricks_launcher.py` +cover the `stdio_command` emission, the `stdio://` / header validation, the +factory's running-sandbox precondition, name normalization, and credential and +launcher-argv wiring, plus the launcher's startup-banner filter. These run +against the released preview wheel (they do not need the native admission change +or a live sandbox). Install the preview wheel, this example's requirements, and +`pytest`, then run them explicitly from the repo root (the default `testpaths` +does not include `tests/codex`): ```sh pytest tests/codex ``` -(validated: 14 passed, and `mypy --strict` clean, against 0.24.0-alpha.7 on a -glibc-2.39 host.) - -These use a fake `CommandProcess`, so they do not exercise the real exec-server -framing themselves - that framing is instead covered end-to-end against a live -sandbox (see the validation note above). A hermetic variant that needs no -Databricks sandbox would point the gateway at a local `codex exec-server ---listen stdio` and drive one `agent.session(environment=...)` turn with the -repo's native model fixtures (see `packages/codex/tests/native_executor_fixtures.py` -and `packages/codex/tests/test_documented_executor_examples.py`). +The native admission change (`stdio://`) is covered by Rust unit tests in +`packages/codex/rust/environment.rs` and qualified by the native build. diff --git a/examples/codex/databricks/environment.py b/examples/codex/databricks/environment.py index 5c2bce785e..fa4ba04b5a 100644 --- a/examples/codex/databricks/environment.py +++ b/examples/codex/databricks/environment.py @@ -1,140 +1,83 @@ -"""Provision a native ``Environment`` backed by a Databricks sandbox. - -This async context manager starts a :class:`SandboxExecServerGateway` for an -existing sandbox and yields an ``Environment`` wired to it. It is the -"manage the executor lifetime" pattern from the remote-execution guide: the SDK -enters the context when opening the Session and exits after releasing native -resources, so the whole start-gateway / tear-down lifecycle fits one -``async with``: - - async with databricks_sandbox_environment( - workspace_client=WorkspaceClient(profile="my-workspace"), - sandbox_name="openai-agent-sandbox", - cwd="/home/sandbox-agent/work", - ) as environment: - async with agent.session(environment=environment) as session: - ... - -Provisioning the sandbox (``WorkspaceClient.sandbox.create_sandbox``), confirming -it is running, and ensuring the ``codex`` exec-server is present are the caller's -responsibility. This context manager confirms the sandbox is running before it -starts the gateway. See ``runner.py`` and the example README for the -create / wait-until-running pattern. +"""Provision a native ``Environment`` backed by a Databricks sandbox over stdio. + +This mirrors the SDK's Docker stdio executor (the private +``_DockerStdioEnvironment`` that :class:`agents.sandbox.DockerGateway` builds): an +``Environment`` subclass declares a host-owned ``stdio_command`` that the native +runtime spawns, then the runtime speaks the exec-server wire protocol over that +process's stdin/stdout. Here the spawned process is ``launch.py``, which relays +the protocol to ``codex exec-server --listen stdio`` inside a Databricks sandbox +over the ``databricks-sdk`` streaming command API. No inbound ingress, no +gateway server, and no TLS termination are needed: the native runtime owns the +launcher process and talks to it over ordinary pipes. + +The subclass overrides ``_to_native`` and ``_validate_remote_url`` - preview +internals that can change across SDK builds. The ``stdio://`` executor source +requires an SDK build with host-owned stdio executor support; see README.md. + +Provisioning the sandbox, confirming it is running, and ensuring the ``codex`` +exec-server image is present are the caller's responsibility. This module +confirms the sandbox is running before returning the environment. See +``runner.py`` and the README for the create / wait-until-running pattern. """ from __future__ import annotations -import os -import secrets -import ssl -import tempfile -import threading -from collections.abc import AsyncIterator, Callable, Mapping, Sequence -from contextlib import asynccontextmanager, suppress -from typing import TYPE_CHECKING +import sys +from collections.abc import Mapping, Sequence +from dataclasses import dataclass, field +from pathlib import Path +from typing import TYPE_CHECKING, Any from agents import Environment from agents.executor import ExecutorToolName -from examples.codex.databricks.gateway import ( - SandboxExecServerGateway, - self_signed_server_context, -) if TYPE_CHECKING: from databricks.sdk import WorkspaceClient _DEFAULT_TOOLS: tuple[ExecutorToolName, ...] = ("exec_command", "write_stdin", "apply_patch") -# Auto-managed trust rewrites the process-global ``SSL_CERT_FILE``, so only one -# auto-managed environment can be active per process. This guard turns a -# concurrent second use into a loud error instead of silent trust corruption. -_trust_lock = threading.Lock() -_trust_active = False +# The launcher the native runtime spawns to bridge executor stdio to the sandbox. +_LAUNCHER = Path(__file__).resolve().parent / "launch.py" -@asynccontextmanager -async def databricks_sandbox_environment( - *, - workspace_client: WorkspaceClient, - sandbox_name: str, - cwd: str, - tools: Sequence[ExecutorToolName] = _DEFAULT_TOOLS, - exec_server_command: Sequence[str] = ("codex", "exec-server", "--listen", "stdio"), - exec_server_env: Mapping[str, str] | None = None, - token: str | None = None, - ssl_context: ssl.SSLContext | None = None, - trust_gateway_ca: bool = True, -) -> AsyncIterator[Environment]: - """Yield an ``Environment`` connected to ``sandbox_name`` through a gateway. +@dataclass(frozen=True, kw_only=True) +class DatabricksStdioEnvironment(Environment[object]): + """An ``Environment`` that runs the executor through a local launcher process. - Args: - workspace_client: An authenticated ``databricks.sdk.WorkspaceClient``. - sandbox_name: An existing sandbox with the exec-server available, as either - the bare id or the ``sandboxes/`` resource name. It must be - running; this is confirmed before the gateway starts. - cwd: Absolute remote workspace path the executor operates in. - tools: Native executor tools to expose. ``write_stdin`` requires - ``exec_command``. - exec_server_command: Argv that starts the standalone exec-server over - stdio in the sandbox. Defaults to - ``("codex", "exec-server", "--listen", "stdio")``. - exec_server_env: Extra environment variables for the exec-server command. - Defaults to none. - token: Bearer secret shared between the gateway and the SDK. A random - value is generated when omitted. - ssl_context: Server TLS context for the gateway. A self-signed loopback - certificate is generated when omitted. - trust_gateway_ca: When a self-signed context is generated, add its CA to - a combined bundle and point ``SSL_CERT_FILE`` at it for the session, - so the native runtime trusts the gateway while keeping public CAs - (via ``certifi``) for the model provider. Restored on exit. Because - ``SSL_CERT_FILE`` is process-global, only one auto-managed - environment may be active per process; a concurrent second use - raises. To run several at once, pass your own ``ssl_context`` and set - ``trust_gateway_ca=False``, managing trust yourself. + The native runtime spawns ``_argv`` (with ``_launch_env`` added to its + environment) and speaks the exec-server protocol over the child's stdio. The + launcher bridges that to ``codex exec-server`` in the sandbox. A ``stdio://`` + url marks a host-owned stdio executor source; ``headers`` must be empty + because there is no HTTP/WebSocket connection to authenticate. """ - if not sandbox_name.startswith("sandboxes/"): - sandbox_name = f"sandboxes/{sandbox_name}" - _confirm_running(workspace_client, sandbox_name) - secret = token or secrets.token_urlsafe(32) - generated_ca: str | None = None - if ssl_context is None: - ssl_context, generated_ca = self_signed_server_context() - - gateway = SandboxExecServerGateway( - workspace_client=workspace_client, - sandbox_name=sandbox_name, - token=secret, - ssl_context=ssl_context, - exec_server_command=exec_server_command, - exec_server_env=exec_server_env, - ca_cert_path=generated_ca, - ) - handle = await gateway.start() - - restore: Callable[[], None] | None = None - try: - if trust_gateway_ca and handle.ca_cert_path is not None: - restore = _install_trust_bundle(handle.ca_cert_path) - yield Environment( - url=handle.url, - cwd=cwd, - tools=tuple(tools), - headers={"Authorization": f"Bearer {secret}"}, - ) - finally: - if restore is not None: - restore() - await gateway.aclose() - if generated_ca is not None: - with suppress(OSError): - os.unlink(generated_ca) + + _argv: tuple[str, ...] = field(default=(), repr=False) + _launch_env: Mapping[str, str] = field(default_factory=dict, repr=False) + + def _validate_remote_url(self) -> None: + if not self.url.startswith("stdio://") or self.headers: + raise ValueError("DatabricksStdioEnvironment requires a stdio:// url and no headers") + + def _to_native(self) -> dict[str, Any]: + result = dict(super()._to_native()) + result["stdio_command"] = { + "program": self._argv[0], + "args": list(self._argv[1:]), + "env": dict(self._launch_env), + "cwd": None, + } + return result + + +def _resource_name(name: str) -> str: + """Return the ``sandboxes/`` resource name the sandbox SDK APIs expect.""" + return name if name.startswith("sandboxes/") else f"sandboxes/{name}" def _confirm_running(workspace_client: WorkspaceClient, sandbox_name: str) -> None: - """Confirm the sandbox is running before the gateway launches the exec-server. + """Confirm the sandbox is running before the launcher reaches the exec-server. - The gateway reaches the exec-server with ``execute_command``, which needs a + The launcher reaches the exec-server with ``execute_command``, which needs a running sandbox. Lifecycle (create / start / poll until running) is the caller's responsibility; see ``runner.py``. This is a fast precondition check, not a wait. @@ -150,59 +93,45 @@ def _confirm_running(workspace_client: WorkspaceClient, sandbox_name: str) -> No ) -def _install_trust_bundle(ca_cert_path: str) -> Callable[[], None]: - """Point ``SSL_CERT_FILE`` at ``certifi`` plus the gateway CA; return a restorer. +def databricks_sandbox_environment( + *, + workspace_client: WorkspaceClient, + sandbox_name: str, + cwd: str, + tools: Sequence[ExecutorToolName] = _DEFAULT_TOOLS, + launcher: str | Path = _LAUNCHER, +) -> DatabricksStdioEnvironment: + """Return an ``Environment`` that reaches ``sandbox_name`` through a launcher. - The native runtime shares one trust store for the model provider and the - executor connection, so the gateway CA is appended to the public bundle - rather than replacing it. + Confirms the sandbox is running, derives the workspace host and token from + ``workspace_client``, and builds a :class:`DatabricksStdioEnvironment` whose + launcher the native runtime spawns when the session opens. The launcher + authenticates with those credentials and bridges to ``codex exec-server`` in + the sandbox. - ``SSL_CERT_FILE`` is process-global, so this refuses to run while another - auto-managed environment is active rather than silently overwriting its - trust. The returned restorer rewinds the variable and removes the bundle. + Args: + workspace_client: An authenticated ``databricks.sdk.WorkspaceClient``. + sandbox_name: An existing, running sandbox with the exec-server available, + as either the bare id or the ``sandboxes/`` resource name. + cwd: Absolute remote workspace path the executor operates in. + tools: Native executor tools to expose. ``write_stdin`` requires + ``exec_command``. + launcher: Path to the stdio launcher script. Defaults to the bundled + ``launch.py``. """ - import certifi - - global _trust_active - with _trust_lock: - if _trust_active: - raise RuntimeError( - "databricks_sandbox_environment is already auto-managing SSL_CERT_FILE " - "for another active environment in this process. Auto-managed trust is " - "process-global and supports one environment at a time. To run several, " - "pass your own ssl_context and set trust_gateway_ca=False." - ) - _trust_active = True - - try: - with open(certifi.where(), "rb") as public_bundle: - public = public_bundle.read() - with open(ca_cert_path, "rb") as gateway_ca: - extra = gateway_ca.read() - - combined = tempfile.NamedTemporaryFile(prefix="dbx-trust-", suffix=".pem", delete=False) - with combined: - combined.write(public) - if not public.endswith(b"\n"): - combined.write(b"\n") - combined.write(extra) - - previous = os.environ.get("SSL_CERT_FILE") - os.environ["SSL_CERT_FILE"] = combined.name - except BaseException: - with _trust_lock: - _trust_active = False - raise - - def restore() -> None: - global _trust_active - if previous is None: - os.environ.pop("SSL_CERT_FILE", None) - else: - os.environ["SSL_CERT_FILE"] = previous - with suppress(OSError): - os.unlink(combined.name) - with _trust_lock: - _trust_active = False - - return restore + sandbox_name = _resource_name(sandbox_name) + _confirm_running(workspace_client, sandbox_name) + host = (workspace_client.config.host or "").rstrip("/") + authorization = workspace_client.config.authenticate().get("Authorization", "") + token = authorization.removeprefix("Bearer ").strip() + if not host or not token: + raise RuntimeError("Could not derive the Databricks host and token from workspace_client") + sandbox_id = sandbox_name.removeprefix("sandboxes/") + return DatabricksStdioEnvironment( + url=f"stdio://databricks/{sandbox_id}", + cwd=cwd, + tools=tuple(tools), + headers={}, + _argv=(sys.executable, str(launcher), sandbox_name), + _launch_env={"DATABRICKS_HOST": host, "DATABRICKS_TOKEN": token}, + ) diff --git a/examples/codex/databricks/gateway.py b/examples/codex/databricks/gateway.py deleted file mode 100644 index 27de3189b1..0000000000 --- a/examples/codex/databricks/gateway.py +++ /dev/null @@ -1,272 +0,0 @@ -"""A localhost WSS gateway that bridges the SDK executor to a sandbox exec-server. - -The native ``Environment`` dials an authenticated ``wss://`` endpoint and relays -the exec-server wire protocol over it. A Databricks sandbox runs that -exec-server in stdio mode, reached through the ``databricks-sdk`` streaming -command API (``WorkspaceClient.sandbox.execute_command``). Nothing in the SDK -speaks stdio and nothing in the sandbox speaks WebSocket, so this gateway sits -between them: it terminates the WebSocket, authenticates the bearer token, -opens the exec-server's stdio stream, and relays bytes in both directions. It is -the application-owned gateway described in the "remote execution" guide, like -``offline_docker.py`` but backed by a Databricks sandbox instead of Docker. - -The gateway frames on newlines: it sends one WebSocket message per line read -from exec-server stdout, and ensures each inbound message ends with a newline -before writing it to stdin. This matches the newline-delimited stdio framing -indicated by ``offline_docker.py``, which opens the exec-server stdio stream -with a 4 MiB line-reader limit; confirm the framing against the executor if the -protocol changes (see the example README). Because ``execute_command`` reaches -the sandbox outbound through the Databricks control plane, the gateway can run -on ``localhost`` next to the application; the sandbox needs no inbound ingress. -""" - -from __future__ import annotations - -import asyncio -import hmac -import http -import logging -import os -import ssl -from collections.abc import Mapping, Sequence -from contextlib import suppress -from dataclasses import dataclass -from typing import TYPE_CHECKING, Any - -if TYPE_CHECKING: - from databricks.sdk import WorkspaceClient - from websockets.asyncio.server import ServerConnection - from websockets.http11 import Request, Response - -logger = logging.getLogger("examples.codex.databricks") - -# The sandbox runs the standalone exec-server over stdio; the gateway relays it. -_DEFAULT_EXEC_SERVER_COMMAND: tuple[str, ...] = ("codex", "exec-server", "--listen", "stdio") - -# Cap for inbound SDK->gateway WebSocket frames. The websockets default is 1 MiB, -# which would close the connection (1009) on a large apply_patch or write_stdin -# payload and kill the relay. Match offline_docker.py's 4 MiB exec-server line limit. -_MAX_WS_MESSAGE_BYTES = 4 * 1024 * 1024 - - -@dataclass(frozen=True, kw_only=True) -class GatewayHandle: - """A running gateway. - - Attributes: - url: The ``wss://`` endpoint to pass as ``Environment.url``. - ca_cert_path: Path to the CA that signed the gateway certificate, or - None when the caller supplied its own already-trusted context. Add - it to the trust store the native runtime uses (see - ``environment.databricks_sandbox_environment``). - """ - - url: str - ca_cert_path: str | None - - -class SandboxExecServerGateway: - """Serve one sandbox's exec-server over an authenticated localhost WebSocket. - - Args: - workspace_client: An authenticated ``databricks.sdk.WorkspaceClient``. - sandbox_name: The target sandbox name/id. - token: Shared secret the SDK must present as ``Authorization: Bearer``. - The provisioner puts the same value in ``Environment.headers``. - ssl_context: Server-side TLS context. ``Environment`` requires ``wss``, - so TLS is mandatory even on loopback. Use - ``self_signed_server_context`` for local runs or pass your own. - exec_server_command: Argv that starts the standalone exec-server over - stdio inside the sandbox. Defaults to - ``("codex", "exec-server", "--listen", "stdio")``, validated against - the sandbox image (``codex-cli`` 0.167.0). Override if a future image - changes the binary path or flags. - exec_server_env: Extra environment variables for the exec-server - command. Defaults to none. - host: Loopback interface to bind. - ca_cert_path: Path to the CA for ``ssl_context`` when self-signed, echoed - back on the handle so callers can trust it. - """ - - def __init__( - self, - *, - workspace_client: WorkspaceClient, - sandbox_name: str, - token: str, - ssl_context: ssl.SSLContext, - exec_server_command: Sequence[str] = _DEFAULT_EXEC_SERVER_COMMAND, - exec_server_env: Mapping[str, str] | None = None, - host: str = "127.0.0.1", - ca_cert_path: str | None = None, - ) -> None: - if not token: - raise ValueError("Gateway token must be a non-empty secret") - command = tuple(exec_server_command) - if not command: - raise ValueError("exec_server_command must name the exec-server program") - self._w = workspace_client - self._sandbox_name = sandbox_name - self._token = token - self._ssl_context = ssl_context - self._command = command - self._env = dict(exec_server_env) if exec_server_env is not None else {} - self._host = host - self._ca_cert_path = ca_cert_path - self._server: Any = None - - async def start(self) -> GatewayHandle: - """Bind the WebSocket server on an ephemeral port and start serving.""" - from websockets.asyncio.server import serve - - self._server = await serve( - self._handle, - self._host, - 0, - ssl=self._ssl_context, - process_request=self._process_request, - max_size=_MAX_WS_MESSAGE_BYTES, - ) - port = self._server.sockets[0].getsockname()[1] - return GatewayHandle(url=f"wss://{self._host}:{port}", ca_cert_path=self._ca_cert_path) - - async def aclose(self) -> None: - """Stop accepting connections and wait for the server to close.""" - if self._server is not None: - self._server.close() - await self._server.wait_closed() - self._server = None - - def _process_request(self, connection: ServerConnection, request: Request) -> Response | None: - """Reject an unauthenticated client at the HTTP handshake with 401.""" - presented = request.headers.get("Authorization", "") - if hmac.compare_digest(presented, f"Bearer {self._token}"): - return None - return connection.respond(http.HTTPStatus.UNAUTHORIZED, "unauthorized\n") - - async def _handle(self, connection: ServerConnection) -> None: - proc = await asyncio.to_thread(self._open_exec_server) - inbound = asyncio.create_task(self._ws_to_stdin(connection, proc)) - outbound = asyncio.create_task(self._stdout_to_ws(proc, connection)) - try: - await asyncio.wait({inbound, outbound}, return_when=asyncio.FIRST_COMPLETED) - finally: - # Closing the process unblocks the stdout read thread so both tasks finish. - await asyncio.to_thread(self._close_quietly, proc) - inbound.cancel() - outbound.cancel() - await asyncio.gather(inbound, outbound, return_exceptions=True) - - def _open_exec_server(self) -> Any: - return self._w.sandbox.execute_command( - self._sandbox_name, - self._command[0], - args=list(self._command[1:]), - envs=self._env or None, - text=False, - ) - - @staticmethod - def _close_quietly(proc: Any) -> None: - try: - proc.close() - except Exception: # teardown must not mask the real error - logger.debug("exec-server process close raised during teardown", exc_info=True) - - async def _ws_to_stdin(self, connection: ServerConnection, proc: Any) -> None: - async for message in connection: - data = message if isinstance(message, bytes) else message.encode() - if not data.endswith(b"\n"): - data += b"\n" # preserve newline message framing on stdin - await asyncio.to_thread(proc.stdin.write, data) - flush = getattr(proc.stdin, "flush", None) - if flush is not None: - await asyncio.to_thread(flush) - await asyncio.to_thread(self._close_stdin_quietly, proc) - - @staticmethod - def _close_stdin_quietly(proc: Any) -> None: - try: - proc.stdin.close() - except Exception: # half-closed stream during teardown - logger.debug("exec-server stdin close raised", exc_info=True) - - async def _stdout_to_ws(self, proc: Any, connection: ServerConnection) -> None: - # The exec-server protocol is newline-delimited JSON-RPC: every message is - # an object whose first non-space byte is '{'. The sandbox's codex prints a - # human-readable startup banner to stdout before the exec-server takes - # over; those non-JSON lines would corrupt the stream as bogus protocol - # frames. Drop the leading non-JSON preamble, then forward every line once - # the protocol starts (a no-op when stdout is JSON from the first line). - protocol_started = False - while True: - line = await asyncio.to_thread(proc.stdout.readline) - if not line: - break - if not protocol_started: - if not line.lstrip().startswith(b"{"): - logger.debug("dropping non-protocol stdout preamble: %r", line[:120]) - continue - protocol_started = True - await connection.send(line) # one WebSocket message per exec-server line - - -def self_signed_server_context(host: str = "127.0.0.1") -> tuple[ssl.SSLContext, str]: - """Build a TLS server context with an ephemeral self-signed certificate. - - Returns the server context and the path to the generated CA certificate so - the client side can trust it. Intended for local runs; supply your own - context and CA in production. Requires the ``cryptography`` dependency from - the example requirements. - - Args: - host: The loopback host the gateway binds, embedded as a SAN. - """ - import datetime - import ipaddress - import tempfile - - from cryptography import x509 - from cryptography.hazmat.primitives import hashes, serialization - from cryptography.hazmat.primitives.asymmetric import rsa - from cryptography.x509.oid import NameOID - - key = rsa.generate_private_key(public_exponent=65537, key_size=2048) - name = x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, host)]) - try: - san: x509.GeneralName = x509.IPAddress(ipaddress.ip_address(host)) - except ValueError: - san = x509.DNSName(host) - now = datetime.datetime.now(datetime.timezone.utc) - certificate = ( - x509.CertificateBuilder() - .subject_name(name) - .issuer_name(name) - .public_key(key.public_key()) - .serial_number(x509.random_serial_number()) - .not_valid_before(now - datetime.timedelta(minutes=5)) - .not_valid_after(now + datetime.timedelta(days=1)) - .add_extension(x509.SubjectAlternativeName([san]), critical=False) - .sign(key, hashes.SHA256()) - ) - - cert_pem = certificate.public_bytes(serialization.Encoding.PEM) - key_pem = key.private_bytes( - serialization.Encoding.PEM, - serialization.PrivateFormat.TraditionalOpenSSL, - serialization.NoEncryption(), - ) - cert_file = tempfile.NamedTemporaryFile(prefix="dbx-gw-", suffix=".crt", delete=False) - key_file = tempfile.NamedTemporaryFile(prefix="dbx-gw-", suffix=".key", delete=False) - with cert_file: - cert_file.write(cert_pem) - with key_file: - key_file.write(key_pem) - - context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER) - context.load_cert_chain(cert_file.name, key_file.name) - # load_cert_chain reads the key synchronously; drop the private key immediately. - with suppress(OSError): - os.unlink(key_file.name) - # The caller owns the returned cert path and must unlink it when done. - return context, cert_file.name diff --git a/examples/codex/databricks/launch.py b/examples/codex/databricks/launch.py new file mode 100644 index 0000000000..52c8c27220 --- /dev/null +++ b/examples/codex/databricks/launch.py @@ -0,0 +1,84 @@ +"""Launcher the native runtime spawns to bridge executor stdio to a sandbox. + +``DatabricksStdioEnvironment`` declares this script as a host-owned +``stdio_command``. The native runtime starts it and speaks the exec-server wire +protocol over its stdin/stdout. This launcher relays that protocol to +``codex exec-server --listen stdio`` running in the Databricks sandbox, over the +``databricks-sdk`` streaming command API (``WorkspaceClient.sandbox.execute_command``, +whose ``CommandProcess`` exposes the command's stdin, stdout and exit). + +Spawned as ``python launch.py `` with ``DATABRICKS_HOST`` and +``DATABRICKS_TOKEN`` in the environment (set by ``databricks_sandbox_environment``). +Diagnostics go to stderr so stdout stays a clean protocol channel. +""" + +from __future__ import annotations + +import os +import sys +import threading +from collections.abc import Callable + + +def _forward_stdout(read_line: Callable[[], bytes], write: Callable[[bytes], None]) -> None: + """Forward exec-server stdout, dropping the non-protocol startup banner. + + ``codex`` prints a human-readable startup banner to stdout before the + exec-server protocol begins; those non-JSON lines would corrupt the stream + as bogus protocol frames. Drop the leading non-JSON preamble, then forward + every line (a no-op once the protocol, newline-delimited JSON-RPC, starts). + """ + protocol_started = False + while True: + line = read_line() + if not line: + break + if not protocol_started: + if not line.lstrip().startswith(b"{"): + continue + protocol_started = True + write(line) + + +def main() -> int: + sandbox_name = sys.argv[1] + host = os.environ.get("DATABRICKS_HOST") + token = os.environ.get("DATABRICKS_TOKEN") + if not host or not token: + print("launch.py requires DATABRICKS_HOST and DATABRICKS_TOKEN", file=sys.stderr) + return 2 + + from databricks.sdk import WorkspaceClient + from databricks.sdk.mixins.sandbox import StreamMode + + workspace_client = WorkspaceClient(host=host, token=token) + process = workspace_client.sandbox.execute_command( + sandbox_name, + "codex", + args=["exec-server", "--listen", "stdio"], + text=False, + stderr=StreamMode.DEVNULL, + ) + + def pump_stdin() -> None: + try: + while True: + chunk = os.read(0, 65536) + if not chunk: + break + process.stdin.write(chunk) + except (ValueError, OSError): + pass # stdin closed when the command exits or the stream dropped + finally: + try: + process.stdin.close() + except (ValueError, OSError): + pass + + threading.Thread(target=pump_stdin, daemon=True).start() + _forward_stdout(process.stdout.readline, lambda line: os.write(1, line)) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/examples/codex/databricks/requirements.txt b/examples/codex/databricks/requirements.txt index b437d0df42..a70ab2fb17 100644 --- a/examples/codex/databricks/requirements.txt +++ b/examples/codex/databricks/requirements.txt @@ -1,4 +1 @@ databricks-sdk[sandbox]>=0.153.0 -websockets>=13 -cryptography>=42 -certifi diff --git a/examples/codex/databricks/runner.py b/examples/codex/databricks/runner.py index 1747599905..e375869ff9 100644 --- a/examples/codex/databricks/runner.py +++ b/examples/codex/databricks/runner.py @@ -20,11 +20,11 @@ With SANDBOX_CREATE=1 the runner provisions the sandbox. In all cases it then confirms the sandbox is running (starting it if stopped and polling until ready) -and ensures the workspace directory exists before opening -``databricks_sandbox_environment`` - the gateway reaches the exec-server through -``execute_command``, which needs a running sandbox. The gateway launches -``exec-server stdio`` on each connection, so no separate exec-server start is -needed here; a sandbox that auto-stops is started again before the next session. +and ensures the workspace directory exists before building +``databricks_sandbox_environment``. When the session opens, the native runtime +spawns the launcher, which reaches the exec-server through ``execute_command`` +(needs a running sandbox); no separate exec-server start is needed here. A +sandbox that auto-stops is started again before the next session. By default the model runs through the sandbox workspace's Databricks AI Gateway codex endpoint, authenticated with the profile's own token (PAT or OAuth), so no @@ -132,25 +132,25 @@ async def main(task: str) -> None: sandbox_name, "/bin/bash", args=["-lc", f"mkdir -p {cwd}"] ) - base_url, api_key = _model_credentials(workspace_client) - async with databricks_sandbox_environment( + environment = databricks_sandbox_environment( workspace_client=workspace_client, sandbox_name=sandbox_name, cwd=cwd, - ) as environment: - async with NativeProvider( - base_url=base_url, - api_key=api_key, - supports_websockets=False, - ) as provider: - agent = Agent( - instructions="Inspect the assigned workspace and report findings.", - model=os.getenv("OPENAI_MODEL", "gpt-5.5"), - provider=provider, - ) - async with agent.session(environment=environment) as session: - result = await (await session.submit(task)).get_result() - print(result.final_output) + ) + base_url, api_key = _model_credentials(workspace_client) + async with NativeProvider( + base_url=base_url, + api_key=api_key, + supports_websockets=False, + ) as provider: + agent = Agent( + instructions="Inspect the assigned workspace and report findings.", + model=os.getenv("OPENAI_MODEL", "gpt-5.5"), + provider=provider, + ) + async with agent.session(environment=environment) as session: + result = await (await session.submit(task)).get_result() + print(result.final_output) if __name__ == "__main__": diff --git a/packages/codex/rust/environment.rs b/packages/codex/rust/environment.rs index 771f6b1681..31b598eb60 100644 --- a/packages/codex/rust/environment.rs +++ b/packages/codex/rust/environment.rs @@ -837,8 +837,8 @@ impl EnvironmentOptions { ensure!( self.url .as_deref() - .is_some_and(|url| url.starts_with("docker://")), - "stdio executor requires a current SDK Docker source" + .is_some_and(|url| url.starts_with("docker://") || url.starts_with("stdio://")), + "stdio executor requires a current SDK Docker source or a stdio:// host-owned command" ); Ok(RemoteTransport::Stdio( StdioExecServerCommand { @@ -2838,6 +2838,58 @@ mod tests { ); } + #[test] + fn stdio_registration_accepts_host_owned_stdio_scheme() { + let options = serde_json::from_value::(json!({ + "url": "stdio://host-owned/executor", + "cwd": "file:///workspace", + "headers": {}, + "stdio_command": { + "program": "codex-missing-exec-server-for-test", "args": [], "env": {}, "cwd": null + } + })) + .expect("decode host options"); + let manager = codex_core_api::EnvironmentManager::without_environments( + codex_http_client::HttpClientFactory::new( + codex_http_client::OutboundProxyPolicy::ReqwestDefault, + ), + ); + options + .register(&manager) + .expect("register stdio:// host-owned command"); + assert!( + manager + .get_environment(codex_exec_server::REMOTE_ENVIRONMENT_ID) + .is_some() + ); + } + + #[test] + fn stdio_registration_rejects_unknown_source_scheme() { + let options = serde_json::from_value::(json!({ + "url": "https://executor.example", + "cwd": "file:///workspace", + "headers": {}, + "stdio_command": { + "program": "must-not-spawn", "args": [], "env": {}, "cwd": null + } + })) + .expect("decode host options"); + let manager = codex_core_api::EnvironmentManager::without_environments( + codex_http_client::HttpClientFactory::new( + codex_http_client::OutboundProxyPolicy::ReqwestDefault, + ), + ); + let error = options + .register(&manager) + .err() + .expect("reject unknown stdio source scheme"); + assert_eq!( + error.to_string(), + "stdio executor requires a current SDK Docker source or a stdio:// host-owned command" + ); + } + #[test] fn runtime_decoder_accepts_direct_environment_and_rejects_retired_fields() { let direct = json!({ diff --git a/tests/codex/test_databricks_environment.py b/tests/codex/test_databricks_environment.py index a3d8afa7a5..10873df11e 100644 --- a/tests/codex/test_databricks_environment.py +++ b/tests/codex/test_databricks_environment.py @@ -1,237 +1,132 @@ -"""Tests for the Databricks sandbox environment example context manager. +"""Tests for the Databricks sandbox stdio environment example. -Cover the public entry point (Environment wiring, teardown, trust handling) and -the ``SSL_CERT_FILE`` bundle helper. Run from the repo root with the preview -wheel and ``examples/codex/databricks/requirements.txt`` installed. +Cover the ``DatabricksStdioEnvironment`` subclass (native ``stdio_command`` +emission and url/header validation) and the ``databricks_sandbox_environment`` +factory (running precondition, name normalization, credential derivation, and +launcher argv/env wiring). Run from the repo root with the preview wheel and +``examples/codex/databricks/requirements.txt`` installed. """ from __future__ import annotations -import os -import queue -import ssl -from pathlib import Path +import sys from types import SimpleNamespace from typing import TYPE_CHECKING, Any, cast import pytest -pytest.importorskip("websockets") -pytest.importorskip("cryptography") -pytest.importorskip("certifi") +pytest.importorskip("databricks.sdk") -from databricks.sdk.service.sandbox import SandboxState # noqa: E402 -from websockets.asyncio.client import connect # noqa: E402 +from databricks.sdk.service.sandbox import SandboxState -from examples.codex.databricks.environment import ( # noqa: E402 - _install_trust_bundle, +from examples.codex.databricks.environment import ( + _LAUNCHER, + DatabricksStdioEnvironment, databricks_sandbox_environment, ) if TYPE_CHECKING: from databricks.sdk import WorkspaceClient -_FAKE_CA = b"-----BEGIN CERTIFICATE-----\nFAKE\n-----END CERTIFICATE-----\n" +class _FakeSandbox: + def __init__(self, state: Any) -> None: + self._state = state -class _FakeStdin: - def __init__(self) -> None: - self.written = bytearray() - - def write(self, data: bytes) -> None: - self.written.extend(data) - - def flush(self) -> None: - pass - - def close(self) -> None: - pass - + def get_sandbox(self, name: str) -> SimpleNamespace: + return SimpleNamespace(status=SimpleNamespace(state=self._state)) -class _FakeStdout: - def __init__(self) -> None: - self._lines: queue.Queue[bytes | None] = queue.Queue() - def eof(self) -> None: - self._lines.put(None) +class _FakeConfig: + host = "https://my-host.example.com/" - def readline(self) -> bytes: - item = self._lines.get() - return b"" if item is None else item + def authenticate(self) -> dict[str, str]: + return {"Authorization": "Bearer tok-abc"} -class _FakeProcess: - def __init__(self) -> None: - self.stdin = _FakeStdin() - self.stdout = _FakeStdout() +class _FakeWorkspaceClient: + def __init__(self, state: Any = SandboxState.SANDBOX_STATE_RUNNING) -> None: + self.sandbox = _FakeSandbox(state) + self.config = _FakeConfig() - def close(self) -> None: - self.stdout.eof() +def _client(state: Any = SandboxState.SANDBOX_STATE_RUNNING) -> WorkspaceClient: + return cast("WorkspaceClient", _FakeWorkspaceClient(state)) -class _FakeSandbox: - def __init__(self, proc: _FakeProcess, state: Any = None) -> None: - self._proc = proc - self._state = state if state is not None else SandboxState.SANDBOX_STATE_RUNNING - def get_sandbox(self, name: str) -> SimpleNamespace: - return SimpleNamespace(status=SimpleNamespace(state=self._state)) - - def execute_command( - self, - name: str, - program: str, - args: list[str], - text: bool, - envs: dict[str, str] | None = None, - ) -> _FakeProcess: - return self._proc +def test_to_native_emits_stdio_command() -> None: + environment = DatabricksStdioEnvironment( + url="stdio://databricks/sbx", + cwd="/home/sandbox-agent/work", + tools=("exec_command", "write_stdin", "apply_patch"), + headers={}, + _argv=("/usr/bin/python", "/pkg/launch.py", "sandboxes/sbx"), + _launch_env={"DATABRICKS_HOST": "https://h", "DATABRICKS_TOKEN": "t"}, + ) + native = environment._to_native() + assert native["stdio_command"] == { + "program": "/usr/bin/python", + "args": ["/pkg/launch.py", "sandboxes/sbx"], + "env": {"DATABRICKS_HOST": "https://h", "DATABRICKS_TOKEN": "t"}, + "cwd": None, + } + # The stdio url is carried through; the runtime admits it as a host-owned source. + assert native["url"] == "stdio://databricks/sbx" + + +def test_rejects_non_stdio_url() -> None: + with pytest.raises(ValueError, match="stdio://"): + DatabricksStdioEnvironment( + url="wss://127.0.0.1:9000", + cwd="/w", + headers={}, + _argv=("python", "launch.py", "sandboxes/sbx"), + ) -class _FakeWorkspaceClient: - def __init__(self, proc: _FakeProcess, state: Any = None) -> None: - self.sandbox = _FakeSandbox(proc, state) +def test_rejects_headers() -> None: + with pytest.raises(ValueError, match="no headers"): + DatabricksStdioEnvironment( + url="stdio://databricks/sbx", + cwd="/w", + headers={"Authorization": "Bearer x"}, + _argv=("python", "launch.py", "sandboxes/sbx"), + ) -async def test_rejects_non_running_sandbox(monkeypatch: pytest.MonkeyPatch) -> None: - monkeypatch.delenv("SSL_CERT_FILE", raising=False) - client = _FakeWorkspaceClient(_FakeProcess(), SandboxState.SANDBOX_STATE_STOPPED) +def test_factory_rejects_non_running_sandbox() -> None: with pytest.raises(RuntimeError, match="not running"): - async with databricks_sandbox_environment( - workspace_client=cast("WorkspaceClient", client), + databricks_sandbox_environment( + workspace_client=_client(SandboxState.SANDBOX_STATE_STOPPED), sandbox_name="sbx", cwd="/w", - token="t", - ): - pass - assert "SSL_CERT_FILE" not in os.environ + ) -async def test_environment_wiring(monkeypatch: pytest.MonkeyPatch) -> None: - monkeypatch.delenv("SSL_CERT_FILE", raising=False) - client = _FakeWorkspaceClient(_FakeProcess()) - async with databricks_sandbox_environment( - workspace_client=cast("WorkspaceClient", client), +def test_factory_wires_launcher_and_credentials() -> None: + environment = databricks_sandbox_environment( + workspace_client=_client(), sandbox_name="sbx", cwd="/home/sandbox-agent/work", - token="tok-123", - ) as environment: - assert environment.url.startswith("wss://127.0.0.1:") - assert environment.cwd == "/home/sandbox-agent/work" - # Environment lowercases header names. - assert environment.headers["authorization"] == "Bearer tok-123" - assert tuple(environment.tools) == ("exec_command", "write_stdin", "apply_patch") - assert "SSL_CERT_FILE" in os.environ - assert "SSL_CERT_FILE" not in os.environ - - -async def test_trust_gateway_ca_false_leaves_env(monkeypatch: pytest.MonkeyPatch) -> None: - monkeypatch.delenv("SSL_CERT_FILE", raising=False) - client = _FakeWorkspaceClient(_FakeProcess()) - async with databricks_sandbox_environment( - workspace_client=cast("WorkspaceClient", client), - sandbox_name="sbx", + ) + assert environment.url == "stdio://databricks/sbx" + assert environment.cwd == "/home/sandbox-agent/work" + assert dict(environment.headers) == {} + assert tuple(environment.tools) == ("exec_command", "write_stdin", "apply_patch") + # Name normalized to the resource form and passed to the launcher. + assert environment._argv == (sys.executable, str(_LAUNCHER), "sandboxes/sbx") + # Host trailing slash stripped; token derived from the profile (no OpenAI key). + assert environment._launch_env == { + "DATABRICKS_HOST": "https://my-host.example.com", + "DATABRICKS_TOKEN": "tok-abc", + } + + +def test_factory_accepts_resource_name() -> None: + environment = databricks_sandbox_environment( + workspace_client=_client(), + sandbox_name="sandboxes/sbx", cwd="/w", - token="t", - trust_gateway_ca=False, - ): - assert "SSL_CERT_FILE" not in os.environ - assert "SSL_CERT_FILE" not in os.environ - - -async def test_restores_and_closes_on_exception(monkeypatch: pytest.MonkeyPatch) -> None: - monkeypatch.setenv("SSL_CERT_FILE", "/orig") - client = _FakeWorkspaceClient(_FakeProcess()) - captured: dict[str, str] = {} - with pytest.raises(RuntimeError, match="boom"): - async with databricks_sandbox_environment( - workspace_client=cast("WorkspaceClient", client), - sandbox_name="sbx", - cwd="/w", - token="t", - ) as environment: - captured["url"] = environment.url - raise RuntimeError("boom") - - assert os.environ["SSL_CERT_FILE"] == "/orig" - - context = ssl.create_default_context() - context.check_hostname = False - context.verify_mode = ssl.CERT_NONE - with pytest.raises(OSError): - async with connect(captured["url"], ssl=context): - pass - - -def test_install_trust_bundle_sets_and_restores( - monkeypatch: pytest.MonkeyPatch, tmp_path: Path -) -> None: - import certifi - - ca = tmp_path / "ca.pem" - ca.write_bytes(_FAKE_CA) - monkeypatch.delenv("SSL_CERT_FILE", raising=False) - - restore = _install_trust_bundle(str(ca)) - bundle = Path(os.environ["SSL_CERT_FILE"]).read_bytes() - assert Path(certifi.where()).read_bytes() in bundle - assert _FAKE_CA in bundle - - restore() - assert "SSL_CERT_FILE" not in os.environ - - -def test_install_trust_bundle_restores_previous( - monkeypatch: pytest.MonkeyPatch, tmp_path: Path -) -> None: - ca = tmp_path / "ca.pem" - ca.write_bytes(_FAKE_CA) - monkeypatch.setenv("SSL_CERT_FILE", "/x") - - restore = _install_trust_bundle(str(ca)) - assert os.environ["SSL_CERT_FILE"] != "/x" - - restore() - assert os.environ["SSL_CERT_FILE"] == "/x" - - -def test_install_trust_bundle_rejects_concurrent( - monkeypatch: pytest.MonkeyPatch, tmp_path: Path -) -> None: - import examples.codex.databricks.environment as env_mod - - ca = tmp_path / "ca.pem" - ca.write_bytes(_FAKE_CA) - monkeypatch.delenv("SSL_CERT_FILE", raising=False) - - first = _install_trust_bundle(str(ca)) - bundle_path = os.environ["SSL_CERT_FILE"] - try: - with pytest.raises(RuntimeError, match="one environment at a time"): - _install_trust_bundle(str(ca)) - finally: - first() - - # The guard is released, the bundle is gone, and a fresh install works. - assert env_mod._trust_active is False - assert not os.path.exists(bundle_path) - second = _install_trust_bundle(str(ca)) - second() - - -def test_install_trust_bundle_rolls_back_on_failure( - monkeypatch: pytest.MonkeyPatch, tmp_path: Path -) -> None: - import examples.codex.databricks.environment as env_mod - - monkeypatch.delenv("SSL_CERT_FILE", raising=False) - with pytest.raises(OSError): - _install_trust_bundle(str(tmp_path / "does-not-exist.pem")) - - # The guard is rolled back and no env var leaked, so later calls still work. - assert env_mod._trust_active is False - assert "SSL_CERT_FILE" not in os.environ - ca = tmp_path / "ca.pem" - ca.write_bytes(_FAKE_CA) - restore = _install_trust_bundle(str(ca)) - restore() + ) + assert environment.url == "stdio://databricks/sbx" + assert environment._argv[-1] == "sandboxes/sbx" diff --git a/tests/codex/test_databricks_gateway.py b/tests/codex/test_databricks_gateway.py deleted file mode 100644 index 19e4776bb4..0000000000 --- a/tests/codex/test_databricks_gateway.py +++ /dev/null @@ -1,262 +0,0 @@ -"""Relay and auth tests for the Databricks sandbox gateway example. - -These exercise the certain core - byte relay and bearer auth - with a fake -``CommandProcess`` and a real TLS WebSocket client. Run from the repo root with -the preview wheel and ``examples/codex/databricks/requirements.txt`` installed. -""" - -from __future__ import annotations - -import queue -import ssl -from typing import TYPE_CHECKING, Any, cast - -import pytest - -pytest.importorskip("websockets") -pytest.importorskip("cryptography") - -from websockets.asyncio.client import connect # noqa: E402 -from websockets.exceptions import ConnectionClosed, InvalidStatus # noqa: E402 - -from examples.codex.databricks.gateway import ( # noqa: E402 - SandboxExecServerGateway, - self_signed_server_context, -) - -if TYPE_CHECKING: - from databricks.sdk import WorkspaceClient - - -class _FakeStdin: - def __init__(self) -> None: - self.written = bytearray() - self.closed = False - - def write(self, data: bytes) -> None: - self.written.extend(data) - - def flush(self) -> None: - pass - - def close(self) -> None: - self.closed = True - - -class _FakeStdout: - """Blocking stdout fed from the test; ``readline`` returns b'' after EOF.""" - - def __init__(self) -> None: - self._lines: queue.Queue[bytes | None] = queue.Queue() - - def feed(self, data: bytes) -> None: - self._lines.put(data) - - def eof(self) -> None: - self._lines.put(None) - - def readline(self) -> bytes: - item = self._lines.get() - return b"" if item is None else item - - -class _FakeProcess: - def __init__(self) -> None: - self.stdin = _FakeStdin() - self.stdout = _FakeStdout() - self.closed = False - - def close(self) -> None: - self.closed = True - self.stdout.eof() - - -class _FakeSandbox: - def __init__(self, proc: _FakeProcess) -> None: - self._proc = proc - self.calls: list[tuple[str, str, list[str]]] = [] - self.envs: list[dict[str, str] | None] = [] - - def execute_command( - self, - name: str, - program: str, - args: list[str], - text: bool, - envs: dict[str, str] | None = None, - ) -> _FakeProcess: - assert text is False - self.calls.append((name, program, args)) - self.envs.append(envs) - return self._proc - - -class _FakeWorkspaceClient: - def __init__(self, proc: _FakeProcess) -> None: - self.sandbox = _FakeSandbox(proc) - - -def _client_ssl(ca_path: str) -> ssl.SSLContext: - context = ssl.create_default_context(cafile=ca_path) - return context - - -async def _start(proc: _FakeProcess, token: str = "s3cret") -> tuple[SandboxExecServerGateway, Any]: - server_ctx, ca_path = self_signed_server_context("127.0.0.1") - gateway = SandboxExecServerGateway( - workspace_client=cast("WorkspaceClient", _FakeWorkspaceClient(proc)), - sandbox_name="sbx", - token=token, - ssl_context=server_ctx, - ca_cert_path=ca_path, - ) - handle = await gateway.start() - return gateway, handle - - -async def test_relay_both_directions() -> None: - proc = _FakeProcess() - client = _FakeWorkspaceClient(proc) - server_ctx, ca_path = self_signed_server_context("127.0.0.1") - gateway = SandboxExecServerGateway( - workspace_client=cast("WorkspaceClient", client), - sandbox_name="sbx", - token="s3cret", - ssl_context=server_ctx, - ca_cert_path=ca_path, - ) - handle = await gateway.start() - try: - async with connect( - handle.url, - ssl=_client_ssl(ca_path), - additional_headers={"Authorization": "Bearer s3cret"}, - ) as ws: - await ws.send(b"hello-stdin") - proc.stdout.feed(b'{"jsonrpc":"2.0","id":1,"result":{}}\n') - received = await ws.recv() - # One WebSocket message per exec-server line; JSON-RPC protocol frame. - assert received == b'{"jsonrpc":"2.0","id":1,"result":{}}\n' - finally: - await gateway.aclose() - - # The gateway appends the newline framing when the client omits it. - assert proc.stdin.written == b"hello-stdin\n" - assert proc.closed is True - assert proc.stdin.closed is True - assert client.sandbox.calls[0] == ("sbx", "codex", ["exec-server", "--listen", "stdio"]) - assert client.sandbox.envs[0] is None - - -async def test_drops_startup_banner_preamble() -> None: - proc = _FakeProcess() - gateway, handle = await _start(proc) - try: - async with connect( - handle.url, - ssl=_client_ssl(handle.ca_cert_path or ""), - additional_headers={"Authorization": "Bearer s3cret"}, - ) as ws: - # The sandbox's codex prints a startup banner to stdout before the real - # exec-server protocol. Those non-JSON lines must not reach the client. - proc.stdout.feed("✔ Databricks auth available\n".encode()) - proc.stdout.feed("╭- Launching Codex with Unity Gateway -╮\n".encode()) - proc.stdout.feed(b"\n") - proc.stdout.feed(b'{"jsonrpc":"2.0","id":1,"result":{}}\n') - proc.stdout.feed(b'{"method":"process/output","params":{"seq":1}}\n') - first = await ws.recv() - second = await ws.recv() - assert first == b'{"jsonrpc":"2.0","id":1,"result":{}}\n' - assert second == b'{"method":"process/output","params":{"seq":1}}\n' - finally: - await gateway.aclose() - - -async def test_relays_large_inbound_frame() -> None: - # A payload above the websockets 1 MiB default (e.g. a big apply_patch) must - # still reach stdin rather than closing the connection with 1009. - proc = _FakeProcess() - gateway, handle = await _start(proc) - payload = b"x" * (2 * 1024 * 1024) - try: - async with connect( - handle.url, - ssl=_client_ssl(handle.ca_cert_path or ""), - additional_headers={"Authorization": "Bearer s3cret"}, - max_size=4 * 1024 * 1024, - ) as ws: - await ws.send(payload) - proc.stdout.feed(b'{"jsonrpc":"2.0","id":1,"result":{}}\n') - assert await ws.recv() == b'{"jsonrpc":"2.0","id":1,"result":{}}\n' - finally: - await gateway.aclose() - - assert proc.stdin.written == payload + b"\n" - - -async def test_rejects_wrong_token() -> None: - proc = _FakeProcess() - gateway, handle = await _start(proc) - try: - with pytest.raises(InvalidStatus): - async with connect( - handle.url, - ssl=_client_ssl(handle.ca_cert_path or ""), - additional_headers={"Authorization": "Bearer wrong"}, - ): - pass - finally: - await gateway.aclose() - - assert proc.stdin.written == b"" - - -class _RaisingSandbox: - def execute_command(self, name: str, program: str, args: list[str], text: bool) -> Any: - raise RuntimeError("exec-server unavailable") - - -class _RaisingWorkspaceClient: - def __init__(self) -> None: - self.sandbox = _RaisingSandbox() - - -async def test_closes_websocket_when_exec_server_exits() -> None: - proc = _FakeProcess() - gateway, handle = await _start(proc) - try: - async with connect( - handle.url, - ssl=_client_ssl(handle.ca_cert_path or ""), - additional_headers={"Authorization": "Bearer s3cret"}, - ) as ws: - proc.stdout.eof() # exec-server exits first - with pytest.raises(ConnectionClosed): - await ws.recv() - finally: - await gateway.aclose() - - assert proc.closed is True - - -async def test_connection_fails_when_exec_server_cannot_start() -> None: - server_ctx, ca_path = self_signed_server_context("127.0.0.1") - gateway = SandboxExecServerGateway( - workspace_client=cast("WorkspaceClient", _RaisingWorkspaceClient()), - sandbox_name="sbx", - token="s3cret", - ssl_context=server_ctx, - ca_cert_path=ca_path, - ) - handle = await gateway.start() - try: - for _ in range(2): # the gateway keeps serving after a failed connection - async with connect( - handle.url, - ssl=_client_ssl(ca_path), - additional_headers={"Authorization": "Bearer s3cret"}, - ) as ws: - with pytest.raises(ConnectionClosed): - await ws.recv() - finally: - await gateway.aclose() diff --git a/tests/codex/test_databricks_launcher.py b/tests/codex/test_databricks_launcher.py new file mode 100644 index 0000000000..41282330e6 --- /dev/null +++ b/tests/codex/test_databricks_launcher.py @@ -0,0 +1,52 @@ +"""Tests for the Databricks stdio launcher's protocol forwarding. + +Cover the startup-banner filter in ``_forward_stdout``: the launcher must drop +``codex``'s non-JSON startup preamble, then forward every exec-server protocol +line verbatim. Run from the repo root with the example requirements installed. +""" + +from __future__ import annotations + +from examples.codex.databricks.launch import _forward_stdout + + +def _run(lines: list[bytes]) -> list[bytes]: + pending = list(lines) + + def read_line() -> bytes: + return pending.pop(0) if pending else b"" + + written: list[bytes] = [] + _forward_stdout(read_line, written.append) + return written + + +def test_drops_banner_then_forwards_protocol() -> None: + written = _run( + [ + b"\xe2\x9c\x94 Databricks auth already available\n", + b"Launching Codex with Unity Gateway\n", + b"\n", + b'{"jsonrpc":"2.0","id":1}\n', + b'{"jsonrpc":"2.0","method":"x"}\n', + ] + ) + assert written == [ + b'{"jsonrpc":"2.0","id":1}\n', + b'{"jsonrpc":"2.0","method":"x"}\n', + ] + + +def test_forwards_everything_after_protocol_starts() -> None: + # A non-JSON line after the protocol has started is still forwarded. + written = _run([b'{"a":1}\n', b"not-json-but-mid-stream\n", b'{"b":2}\n']) + assert written == [b'{"a":1}\n', b"not-json-but-mid-stream\n", b'{"b":2}\n'] + + +def test_leading_whitespace_before_brace_is_protocol() -> None: + written = _run([b" banner\n", b' {"a":1}\n']) + assert written == [b' {"a":1}\n'] + + +def test_stops_at_eof_with_no_protocol() -> None: + assert _run([b"banner one\n", b"banner two\n"]) == [] From 4edf7b0328461dab073db1213defc0b4d70e8661 Mon Sep 17 00:00:00 2001 From: Hsing Tang Date: Mon, 16 Nov 2026 23:06:22 +0000 Subject: [PATCH 3/9] feat: promote DatabricksStdioEnvironment to a first-class agents.sandbox API Move the Databricks stdio executor from example code into the SDK package as a supported, exported class: agents.sandbox.DatabricksStdioEnvironment, beside DockerGateway. It subclasses the native Environment, emits a host-owned stdio_command, and provides a for_sandbox(workspace_client, sandbox_name, cwd) constructor that confirms the sandbox is running and derives the host/token the launcher authenticates with. The launcher (_databricks_launcher.py) bridges the runtime's child stdio to codex exec-server in the sandbox over databricks-sdk; databricks-sdk is imported lazily so importing the module does not require it. The example now consumes the first-class class (runner uses DatabricksStdioEnvironment.for_sandbox); its environment.py/launch.py are removed. Tests move to the public path (agents.sandbox) and cover stdio_command emission, stdio://-url/header validation, the for_sandbox precondition and wiring, and the launcher banner filter. Note: agents.sandbox pulls agents.classic, so importing the class requires the [classic] extra. released_api_contract.json must be regenerated for the new public export during the native build (make update-released-api-contract); it is not editable without that build. Co-authored-by: Isaac --- examples/codex/databricks/README.md | 59 +++----- examples/codex/databricks/environment.py | 137 ------------------ examples/codex/databricks/runner.py | 14 +- .../codex/src/_agents_codex/_databricks.py | 111 ++++++++++++++ .../src/_agents_codex/_databricks_launcher.py | 11 +- packages/codex/src/_agents_codex/sandbox.py | 2 + src/agents/sandbox.py | 2 + tests/codex/test_databricks_environment.py | 52 +++---- tests/codex/test_databricks_launcher.py | 5 +- 9 files changed, 173 insertions(+), 220 deletions(-) delete mode 100644 examples/codex/databricks/environment.py create mode 100644 packages/codex/src/_agents_codex/_databricks.py rename examples/codex/databricks/launch.py => packages/codex/src/_agents_codex/_databricks_launcher.py (84%) diff --git a/examples/codex/databricks/README.md b/examples/codex/databricks/README.md index ffa4979cbe..57b7faa624 100644 --- a/examples/codex/databricks/README.md +++ b/examples/codex/databricks/README.md @@ -3,33 +3,33 @@ Back a native `Environment` with a Databricks sandbox, so an agent driven by this SDK runs `exec_command` / `write_stdin` / `apply_patch` inside the sandbox. This is the "remote execution" pattern from `docs/sdk/execution.md`, built the -same way the SDK's own Docker support is: an `Environment` subclass declares a -host-owned `stdio_command` that the native runtime spawns, and the runtime -speaks the exec-server protocol over that process's stdin/stdout. It is the -Databricks counterpart of `agents.sandbox.DockerGateway` / -`examples/codex/offline_docker.py`. +same way the SDK's own Docker support is: `agents.sandbox.DatabricksStdioEnvironment` +is an `Environment` subclass that declares a host-owned `stdio_command` the +native runtime spawns, and the runtime speaks the exec-server protocol over that +process's stdin/stdout. It is the Databricks counterpart of +`agents.sandbox.DockerGateway`. > **Status.** The stdio transport and the full turn are validated end-to-end > against a live Databricks sandbox on the `0.24.0-alpha.8` preview wheel: a real > `codex exec-server` ran the agent's tool call in the sandbox with no gateway > server and no TLS, driven over the `databricks-sdk` streaming command API, for > both model providers (Databricks AI Gateway and OpenAI direct). The `stdio://` -> executor source this example uses requires an Agents SDK build that includes -> the host-owned stdio admission change in this PR's native runtime -> (`packages/codex/rust/environment.rs`); it is not yet in a released preview -> wheel. Until it ships, build the SDK from this branch (see +> executor source requires the host-owned stdio admission change in this PR's +> native runtime (`packages/codex/rust/environment.rs`); it is not yet in a +> released preview wheel. Until it ships, build the SDK from this branch (see > `packages/codex/MAINTAINING.md`). The Python pieces are covered by > `tests/codex/` against the released wheel. ## How it works -`DatabricksStdioEnvironment` (`environment.py`) subclasses the native -`Environment` and emits a `stdio_command`: the argv of a local launcher process. -When the session opens, the native runtime spawns that launcher and speaks the -exec-server wire protocol over its stdin/stdout. The launcher (`launch.py`) -relays that protocol to `codex exec-server --listen stdio` inside the sandbox -over the `databricks-sdk` streaming command API -(`WorkspaceClient.sandbox.execute_command`, whose `CommandProcess` exposes the +`DatabricksStdioEnvironment.for_sandbox(...)` confirms the sandbox is running, +derives the workspace host and token from the `WorkspaceClient`, and returns an +environment to hand to `agent.session(environment=...)`. The environment emits a +`stdio_command`: the argv of a local launcher process. When the session opens, +the native runtime spawns that launcher and speaks the exec-server wire protocol +over its stdin/stdout. The launcher relays that protocol to `codex exec-server +--listen stdio` inside the sandbox over the `databricks-sdk` streaming command +API (`WorkspaceClient.sandbox.execute_command`, whose `CommandProcess` exposes the command's `stdin`, `stdout` and exit). It does not parse the protocol; it only drops a startup banner the sandbox's `codex` prints on stdout before the protocol begins (non-JSON lines) so it never reaches the runtime as a bogus message. @@ -41,22 +41,10 @@ control plane, so the sandbox needs no inbound ingress. The agent loop runs in your process (via `NativeProvider`), which is what makes the `Environment` approval / transform callbacks and `NetworkPolicy` available. -`databricks_sandbox_environment` (`environment.py`) confirms the sandbox is -running, derives the workspace host and token from the `WorkspaceClient`, and -returns a configured `DatabricksStdioEnvironment` to hand to -`agent.session(environment=...)`. - -> This subclass overrides `Environment._to_native` and `_validate_remote_url`, -> which are preview internals and can change across SDK builds. It mirrors the -> SDK's own `_DockerStdioEnvironment`. - ## Files -- `environment.py` - `DatabricksStdioEnvironment` and the - `databricks_sandbox_environment` factory. -- `launch.py` - the launcher the native runtime spawns to bridge stdio to the - sandbox. -- `runner.py` - a runnable end-to-end example. +- `runner.py` - a runnable end-to-end example. The environment itself is the + first-class `agents.sandbox.DatabricksStdioEnvironment`. ## Install and run @@ -104,7 +92,7 @@ Only the model provider changes; the sandbox, launcher, and tools are identical. starts it if stopped, and polls its status until running before opening the environment - the exec-server is reached through `execute_command`, which needs a running sandbox. `runner.py` shows this, and - `databricks_sandbox_environment` confirms it. + `DatabricksStdioEnvironment.for_sandbox` confirms it. 2. **exec-server stdio mode in the image.** The sandbox's `codex` runs the standalone exec-server over stdio with `codex exec-server --listen stdio`, which the launcher relays. @@ -116,10 +104,11 @@ Only the model provider changes; the sandbox, launcher, and tools are identical. `tests/codex/test_databricks_environment.py` and `test_databricks_launcher.py` cover the `stdio_command` emission, the `stdio://` / header validation, the factory's running-sandbox precondition, name normalization, and credential and -launcher-argv wiring, plus the launcher's startup-banner filter. These run -against the released preview wheel (they do not need the native admission change -or a live sandbox). Install the preview wheel, this example's requirements, and -`pytest`, then run them explicitly from the repo root (the default `testpaths` +launcher-argv wiring, plus the launcher's startup-banner filter. They exercise +only the Python layer (not the native admission or a live sandbox), but they +import the packaged class, so run them against an SDK built from this branch. +Install that wheel, this example's requirements, and `pytest`, then run them +explicitly from the repo root (the default `testpaths` does not include `tests/codex`): ```sh diff --git a/examples/codex/databricks/environment.py b/examples/codex/databricks/environment.py deleted file mode 100644 index fa4ba04b5a..0000000000 --- a/examples/codex/databricks/environment.py +++ /dev/null @@ -1,137 +0,0 @@ -"""Provision a native ``Environment`` backed by a Databricks sandbox over stdio. - -This mirrors the SDK's Docker stdio executor (the private -``_DockerStdioEnvironment`` that :class:`agents.sandbox.DockerGateway` builds): an -``Environment`` subclass declares a host-owned ``stdio_command`` that the native -runtime spawns, then the runtime speaks the exec-server wire protocol over that -process's stdin/stdout. Here the spawned process is ``launch.py``, which relays -the protocol to ``codex exec-server --listen stdio`` inside a Databricks sandbox -over the ``databricks-sdk`` streaming command API. No inbound ingress, no -gateway server, and no TLS termination are needed: the native runtime owns the -launcher process and talks to it over ordinary pipes. - -The subclass overrides ``_to_native`` and ``_validate_remote_url`` - preview -internals that can change across SDK builds. The ``stdio://`` executor source -requires an SDK build with host-owned stdio executor support; see README.md. - -Provisioning the sandbox, confirming it is running, and ensuring the ``codex`` -exec-server image is present are the caller's responsibility. This module -confirms the sandbox is running before returning the environment. See -``runner.py`` and the README for the create / wait-until-running pattern. -""" - -from __future__ import annotations - -import sys -from collections.abc import Mapping, Sequence -from dataclasses import dataclass, field -from pathlib import Path -from typing import TYPE_CHECKING, Any - -from agents import Environment -from agents.executor import ExecutorToolName - -if TYPE_CHECKING: - from databricks.sdk import WorkspaceClient - -_DEFAULT_TOOLS: tuple[ExecutorToolName, ...] = ("exec_command", "write_stdin", "apply_patch") - -# The launcher the native runtime spawns to bridge executor stdio to the sandbox. -_LAUNCHER = Path(__file__).resolve().parent / "launch.py" - - -@dataclass(frozen=True, kw_only=True) -class DatabricksStdioEnvironment(Environment[object]): - """An ``Environment`` that runs the executor through a local launcher process. - - The native runtime spawns ``_argv`` (with ``_launch_env`` added to its - environment) and speaks the exec-server protocol over the child's stdio. The - launcher bridges that to ``codex exec-server`` in the sandbox. A ``stdio://`` - url marks a host-owned stdio executor source; ``headers`` must be empty - because there is no HTTP/WebSocket connection to authenticate. - """ - - _argv: tuple[str, ...] = field(default=(), repr=False) - _launch_env: Mapping[str, str] = field(default_factory=dict, repr=False) - - def _validate_remote_url(self) -> None: - if not self.url.startswith("stdio://") or self.headers: - raise ValueError("DatabricksStdioEnvironment requires a stdio:// url and no headers") - - def _to_native(self) -> dict[str, Any]: - result = dict(super()._to_native()) - result["stdio_command"] = { - "program": self._argv[0], - "args": list(self._argv[1:]), - "env": dict(self._launch_env), - "cwd": None, - } - return result - - -def _resource_name(name: str) -> str: - """Return the ``sandboxes/`` resource name the sandbox SDK APIs expect.""" - return name if name.startswith("sandboxes/") else f"sandboxes/{name}" - - -def _confirm_running(workspace_client: WorkspaceClient, sandbox_name: str) -> None: - """Confirm the sandbox is running before the launcher reaches the exec-server. - - The launcher reaches the exec-server with ``execute_command``, which needs a - running sandbox. Lifecycle (create / start / poll until running) is the - caller's responsibility; see ``runner.py``. This is a fast precondition - check, not a wait. - """ - from databricks.sdk.service.sandbox import SandboxState - - sandbox = workspace_client.sandbox.get_sandbox(sandbox_name) - state = sandbox.status.state if sandbox.status is not None else None - if state != SandboxState.SANDBOX_STATE_RUNNING: - raise RuntimeError( - f"Sandbox {sandbox_name!r} is not running (state={state}). Create or start " - "it and poll until running before opening the environment (see runner.py)." - ) - - -def databricks_sandbox_environment( - *, - workspace_client: WorkspaceClient, - sandbox_name: str, - cwd: str, - tools: Sequence[ExecutorToolName] = _DEFAULT_TOOLS, - launcher: str | Path = _LAUNCHER, -) -> DatabricksStdioEnvironment: - """Return an ``Environment`` that reaches ``sandbox_name`` through a launcher. - - Confirms the sandbox is running, derives the workspace host and token from - ``workspace_client``, and builds a :class:`DatabricksStdioEnvironment` whose - launcher the native runtime spawns when the session opens. The launcher - authenticates with those credentials and bridges to ``codex exec-server`` in - the sandbox. - - Args: - workspace_client: An authenticated ``databricks.sdk.WorkspaceClient``. - sandbox_name: An existing, running sandbox with the exec-server available, - as either the bare id or the ``sandboxes/`` resource name. - cwd: Absolute remote workspace path the executor operates in. - tools: Native executor tools to expose. ``write_stdin`` requires - ``exec_command``. - launcher: Path to the stdio launcher script. Defaults to the bundled - ``launch.py``. - """ - sandbox_name = _resource_name(sandbox_name) - _confirm_running(workspace_client, sandbox_name) - host = (workspace_client.config.host or "").rstrip("/") - authorization = workspace_client.config.authenticate().get("Authorization", "") - token = authorization.removeprefix("Bearer ").strip() - if not host or not token: - raise RuntimeError("Could not derive the Databricks host and token from workspace_client") - sandbox_id = sandbox_name.removeprefix("sandboxes/") - return DatabricksStdioEnvironment( - url=f"stdio://databricks/{sandbox_id}", - cwd=cwd, - tools=tuple(tools), - headers={}, - _argv=(sys.executable, str(launcher), sandbox_name), - _launch_env={"DATABRICKS_HOST": host, "DATABRICKS_TOKEN": token}, - ) diff --git a/examples/codex/databricks/runner.py b/examples/codex/databricks/runner.py index e375869ff9..7b7a6711b3 100644 --- a/examples/codex/databricks/runner.py +++ b/examples/codex/databricks/runner.py @@ -20,11 +20,11 @@ With SANDBOX_CREATE=1 the runner provisions the sandbox. In all cases it then confirms the sandbox is running (starting it if stopped and polling until ready) -and ensures the workspace directory exists before building -``databricks_sandbox_environment``. When the session opens, the native runtime -spawns the launcher, which reaches the exec-server through ``execute_command`` -(needs a running sandbox); no separate exec-server start is needed here. A -sandbox that auto-stops is started again before the next session. +and ensures the workspace directory exists before building the environment with +``DatabricksStdioEnvironment.for_sandbox``. When the session opens, the native +runtime spawns the launcher, which reaches the exec-server through +``execute_command`` (needs a running sandbox); no separate exec-server start is +needed here. A sandbox that auto-stops is started again before the next session. By default the model runs through the sandbox workspace's Databricks AI Gateway codex endpoint, authenticated with the profile's own token (PAT or OAuth), so no @@ -44,7 +44,7 @@ from databricks.sdk import WorkspaceClient from agents import Agent, NativeProvider -from examples.codex.databricks.environment import databricks_sandbox_environment +from agents.sandbox import DatabricksStdioEnvironment def _resource_name(name: str) -> str: @@ -132,7 +132,7 @@ async def main(task: str) -> None: sandbox_name, "/bin/bash", args=["-lc", f"mkdir -p {cwd}"] ) - environment = databricks_sandbox_environment( + environment = DatabricksStdioEnvironment.for_sandbox( workspace_client=workspace_client, sandbox_name=sandbox_name, cwd=cwd, diff --git a/packages/codex/src/_agents_codex/_databricks.py b/packages/codex/src/_agents_codex/_databricks.py new file mode 100644 index 0000000000..d549038d1e --- /dev/null +++ b/packages/codex/src/_agents_codex/_databricks.py @@ -0,0 +1,111 @@ +"""Databricks sandbox executor as a host-owned stdio environment. + +``DatabricksStdioEnvironment`` is the Databricks counterpart of the Docker stdio +executor: it subclasses the native :class:`Environment` and declares a +host-owned ``stdio_command`` the runtime spawns, then speaks the exec-server +protocol over that process's stdio. The launcher relays the protocol to +``codex exec-server --listen stdio`` inside a Databricks sandbox over the +``databricks-sdk`` streaming command API, so there is no gateway server, no TLS, +and no inbound ingress. ``databricks-sdk`` is imported lazily, so importing this +module does not require it. +""" + +from __future__ import annotations + +import sys +from collections.abc import Mapping, Sequence +from dataclasses import dataclass, field +from pathlib import Path +from typing import Any + +from ._options import RuntimeEnvironment +from .executor import Environment, ExecutorToolName + +_DEFAULT_TOOLS: tuple[ExecutorToolName, ...] = ("exec_command", "write_stdin", "apply_patch") + +# The launcher the native runtime spawns to bridge executor stdio to the sandbox. +_LAUNCHER = Path(__file__).resolve().parent / "_databricks_launcher.py" + + +@dataclass(frozen=True, kw_only=True) +class DatabricksStdioEnvironment(Environment[object]): + """Run the executor in a Databricks sandbox over a host-owned stdio launcher. + + Build one with :meth:`for_sandbox`, then pass it to + ``agent.session(environment=...)``. The native runtime spawns ``_argv`` (with + ``_launch_env`` added to its environment) and speaks the exec-server protocol + over the child's stdio; the launcher relays it to ``codex exec-server`` in the + sandbox. A ``stdio://`` url marks a host-owned stdio executor source; + ``headers`` must be empty because there is no HTTP/WebSocket connection to + authenticate. + """ + + _argv: tuple[str, ...] = field(default=(), repr=False) + _launch_env: Mapping[str, str] = field(default_factory=dict, repr=False) + + def _validate_remote_url(self) -> None: + if not self.url.startswith("stdio://") or self.headers: + raise ValueError("DatabricksStdioEnvironment requires a stdio:// url and no headers") + + def _to_native(self) -> RuntimeEnvironment: + result = super()._to_native() + result["stdio_command"] = { + "program": self._argv[0], + "args": list(self._argv[1:]), + "env": dict(self._launch_env), + "cwd": None, + } + return result + + @classmethod + def for_sandbox( + cls, + *, + workspace_client: Any, + sandbox_name: str, + cwd: str, + tools: Sequence[ExecutorToolName] = _DEFAULT_TOOLS, + ) -> DatabricksStdioEnvironment: + """Return an environment bound to a running Databricks sandbox. + + Confirms the sandbox is running and derives the workspace host and token + from ``workspace_client`` (a ``databricks.sdk.WorkspaceClient``) for the + launcher to authenticate with. Lifecycle (create / start / poll until + running) is the caller's responsibility; this only checks the state. + + Args: + workspace_client: An authenticated ``databricks.sdk.WorkspaceClient``. + sandbox_name: An existing, running sandbox, as the bare id or the + ``sandboxes/`` resource name. + cwd: Absolute remote workspace path the executor operates in. + tools: Native executor tools to expose. ``write_stdin`` requires + ``exec_command``. + """ + from databricks.sdk.service.sandbox import SandboxState + + name = sandbox_name + if not name.startswith("sandboxes/"): + name = f"sandboxes/{name}" + sandbox = workspace_client.sandbox.get_sandbox(name) + state = sandbox.status.state if sandbox.status is not None else None + if state != SandboxState.SANDBOX_STATE_RUNNING: + raise RuntimeError( + f"Sandbox {name!r} is not running (state={state}). Create or start it and poll " + "until running before opening the environment." + ) + host = (workspace_client.config.host or "").rstrip("/") + authorization = workspace_client.config.authenticate().get("Authorization", "") + token = authorization.removeprefix("Bearer ").strip() + if not host or not token: + raise RuntimeError( + "Could not derive the Databricks host and token from workspace_client" + ) + sandbox_id = name.removeprefix("sandboxes/") + return cls( + url=f"stdio://databricks/{sandbox_id}", + cwd=cwd, + tools=tuple(tools), + headers={}, + _argv=(sys.executable, str(_LAUNCHER), name), + _launch_env={"DATABRICKS_HOST": host, "DATABRICKS_TOKEN": token}, + ) diff --git a/examples/codex/databricks/launch.py b/packages/codex/src/_agents_codex/_databricks_launcher.py similarity index 84% rename from examples/codex/databricks/launch.py rename to packages/codex/src/_agents_codex/_databricks_launcher.py index 52c8c27220..0226508dad 100644 --- a/examples/codex/databricks/launch.py +++ b/packages/codex/src/_agents_codex/_databricks_launcher.py @@ -1,15 +1,16 @@ """Launcher the native runtime spawns to bridge executor stdio to a sandbox. -``DatabricksStdioEnvironment`` declares this script as a host-owned +:class:`DatabricksStdioEnvironment` declares this file as a host-owned ``stdio_command``. The native runtime starts it and speaks the exec-server wire protocol over its stdin/stdout. This launcher relays that protocol to ``codex exec-server --listen stdio`` running in the Databricks sandbox, over the ``databricks-sdk`` streaming command API (``WorkspaceClient.sandbox.execute_command``, whose ``CommandProcess`` exposes the command's stdin, stdout and exit). -Spawned as ``python launch.py `` with ``DATABRICKS_HOST`` and -``DATABRICKS_TOKEN`` in the environment (set by ``databricks_sandbox_environment``). -Diagnostics go to stderr so stdout stays a clean protocol channel. +It is run as a standalone script - ``python _databricks_launcher.py `` +with ``DATABRICKS_HOST`` and ``DATABRICKS_TOKEN`` in the environment - so it does +not import the ``_agents_codex`` package or the native runtime. Diagnostics go to +stderr so stdout stays a clean protocol channel. """ from __future__ import annotations @@ -45,7 +46,7 @@ def main() -> int: host = os.environ.get("DATABRICKS_HOST") token = os.environ.get("DATABRICKS_TOKEN") if not host or not token: - print("launch.py requires DATABRICKS_HOST and DATABRICKS_TOKEN", file=sys.stderr) + print("launcher requires DATABRICKS_HOST and DATABRICKS_TOKEN", file=sys.stderr) return 2 from databricks.sdk import WorkspaceClient diff --git a/packages/codex/src/_agents_codex/sandbox.py b/packages/codex/src/_agents_codex/sandbox.py index 11a6240654..1cab28f6da 100644 --- a/packages/codex/src/_agents_codex/sandbox.py +++ b/packages/codex/src/_agents_codex/sandbox.py @@ -103,6 +103,7 @@ WorkspaceJsonlSink as WorkspaceJsonlSink, ) +from ._databricks import DatabricksStdioEnvironment from ._function_tools import FunctionTool from ._managed_workspace import ( _SANDBOX_CAPABILITIES_ATTRIBUTE, @@ -1221,6 +1222,7 @@ def encode(value: object) -> str: __all__ = [ + "DatabricksStdioEnvironment", "DockerGateway", "Instrumentation", "EventPayloadPolicy", diff --git a/src/agents/sandbox.py b/src/agents/sandbox.py index 9452eb2a29..593ade142e 100644 --- a/src/agents/sandbox.py +++ b/src/agents/sandbox.py @@ -7,6 +7,7 @@ BoxMount as BoxMount, CallbackSink as CallbackSink, ChainedSink as ChainedSink, + DatabricksStdioEnvironment as DatabricksStdioEnvironment, Dir as Dir, DockerGateway as DockerGateway, DockerVolumeMountStrategy as DockerVolumeMountStrategy, @@ -69,6 +70,7 @@ ) __all__ = [ + "DatabricksStdioEnvironment", "DockerGateway", "Skill", "Skills", diff --git a/tests/codex/test_databricks_environment.py b/tests/codex/test_databricks_environment.py index 10873df11e..5d71465357 100644 --- a/tests/codex/test_databricks_environment.py +++ b/tests/codex/test_databricks_environment.py @@ -1,17 +1,16 @@ -"""Tests for the Databricks sandbox stdio environment example. +"""Tests for the Databricks sandbox stdio environment (``agents.sandbox``). -Cover the ``DatabricksStdioEnvironment`` subclass (native ``stdio_command`` -emission and url/header validation) and the ``databricks_sandbox_environment`` -factory (running precondition, name normalization, credential derivation, and -launcher argv/env wiring). Run from the repo root with the preview wheel and -``examples/codex/databricks/requirements.txt`` installed. +Cover ``DatabricksStdioEnvironment`` (native ``stdio_command`` emission and +url/header validation) and its ``for_sandbox`` constructor (running precondition, +name normalization, credential derivation, and launcher argv/env wiring). Run +from the repo root with the preview wheel installed. """ from __future__ import annotations import sys from types import SimpleNamespace -from typing import TYPE_CHECKING, Any, cast +from typing import Any import pytest @@ -19,14 +18,8 @@ from databricks.sdk.service.sandbox import SandboxState -from examples.codex.databricks.environment import ( - _LAUNCHER, - DatabricksStdioEnvironment, - databricks_sandbox_environment, -) - -if TYPE_CHECKING: - from databricks.sdk import WorkspaceClient +from _agents_codex._databricks import _LAUNCHER +from agents.sandbox import DatabricksStdioEnvironment class _FakeSandbox: @@ -50,27 +43,22 @@ def __init__(self, state: Any = SandboxState.SANDBOX_STATE_RUNNING) -> None: self.config = _FakeConfig() -def _client(state: Any = SandboxState.SANDBOX_STATE_RUNNING) -> WorkspaceClient: - return cast("WorkspaceClient", _FakeWorkspaceClient(state)) - - def test_to_native_emits_stdio_command() -> None: environment = DatabricksStdioEnvironment( url="stdio://databricks/sbx", cwd="/home/sandbox-agent/work", tools=("exec_command", "write_stdin", "apply_patch"), headers={}, - _argv=("/usr/bin/python", "/pkg/launch.py", "sandboxes/sbx"), + _argv=("/usr/bin/python", "/pkg/_databricks_launcher.py", "sandboxes/sbx"), _launch_env={"DATABRICKS_HOST": "https://h", "DATABRICKS_TOKEN": "t"}, ) native = environment._to_native() assert native["stdio_command"] == { "program": "/usr/bin/python", - "args": ["/pkg/launch.py", "sandboxes/sbx"], + "args": ["/pkg/_databricks_launcher.py", "sandboxes/sbx"], "env": {"DATABRICKS_HOST": "https://h", "DATABRICKS_TOKEN": "t"}, "cwd": None, } - # The stdio url is carried through; the runtime admits it as a host-owned source. assert native["url"] == "stdio://databricks/sbx" @@ -94,18 +82,18 @@ def test_rejects_headers() -> None: ) -def test_factory_rejects_non_running_sandbox() -> None: +def test_for_sandbox_rejects_non_running() -> None: with pytest.raises(RuntimeError, match="not running"): - databricks_sandbox_environment( - workspace_client=_client(SandboxState.SANDBOX_STATE_STOPPED), + DatabricksStdioEnvironment.for_sandbox( + workspace_client=_FakeWorkspaceClient(SandboxState.SANDBOX_STATE_STOPPED), sandbox_name="sbx", cwd="/w", ) -def test_factory_wires_launcher_and_credentials() -> None: - environment = databricks_sandbox_environment( - workspace_client=_client(), +def test_for_sandbox_wires_launcher_and_credentials() -> None: + environment = DatabricksStdioEnvironment.for_sandbox( + workspace_client=_FakeWorkspaceClient(), sandbox_name="sbx", cwd="/home/sandbox-agent/work", ) @@ -113,18 +101,16 @@ def test_factory_wires_launcher_and_credentials() -> None: assert environment.cwd == "/home/sandbox-agent/work" assert dict(environment.headers) == {} assert tuple(environment.tools) == ("exec_command", "write_stdin", "apply_patch") - # Name normalized to the resource form and passed to the launcher. assert environment._argv == (sys.executable, str(_LAUNCHER), "sandboxes/sbx") - # Host trailing slash stripped; token derived from the profile (no OpenAI key). assert environment._launch_env == { "DATABRICKS_HOST": "https://my-host.example.com", "DATABRICKS_TOKEN": "tok-abc", } -def test_factory_accepts_resource_name() -> None: - environment = databricks_sandbox_environment( - workspace_client=_client(), +def test_for_sandbox_accepts_resource_name() -> None: + environment = DatabricksStdioEnvironment.for_sandbox( + workspace_client=_FakeWorkspaceClient(), sandbox_name="sandboxes/sbx", cwd="/w", ) diff --git a/tests/codex/test_databricks_launcher.py b/tests/codex/test_databricks_launcher.py index 41282330e6..624dc93279 100644 --- a/tests/codex/test_databricks_launcher.py +++ b/tests/codex/test_databricks_launcher.py @@ -2,12 +2,12 @@ Cover the startup-banner filter in ``_forward_stdout``: the launcher must drop ``codex``'s non-JSON startup preamble, then forward every exec-server protocol -line verbatim. Run from the repo root with the example requirements installed. +line verbatim. Run from the repo root with the preview wheel installed. """ from __future__ import annotations -from examples.codex.databricks.launch import _forward_stdout +from _agents_codex._databricks_launcher import _forward_stdout def _run(lines: list[bytes]) -> list[bytes]: @@ -38,7 +38,6 @@ def test_drops_banner_then_forwards_protocol() -> None: def test_forwards_everything_after_protocol_starts() -> None: - # A non-JSON line after the protocol has started is still forwarded. written = _run([b'{"a":1}\n', b"not-json-but-mid-stream\n", b'{"b":2}\n']) assert written == [b'{"a":1}\n', b"not-json-but-mid-stream\n", b'{"b":2}\n'] From 6fe128cc9c95d4e2dd2f755d37d4d91ec578a2dc Mon Sep 17 00:00:00 2001 From: Hsing Tang Date: Tue, 17 Nov 2026 00:14:53 +0000 Subject: [PATCH 4/9] fix: address review findings for the Databricks stdio executor - Launch the bridge as a module (python -m _agents_codex._databricks_launcher) instead of exec'ing a file path, so it resolves via the module system. - Harden the launcher: forward the exec-server's stderr for diagnostics, surface the remote command's exit code instead of always returning 0, and close the exec-server's stdin on teardown/SIGTERM/SIGINT so it shuts down (the SDK cannot kill the remote command; a lingering one is reaped by the sandbox inactivity timeout). Factor the relay into a testable _run. - Move the tests into packages/codex/tests so the default testpaths (and CI) collect them, and add coverage for the launcher's credential guard, protocol forwarding, stdin close, and exit-code handling. - Note that for_sandbox freezes the derived token, so a fresh environment is needed per session with short-lived OAuth/U2M credentials. Co-authored-by: Isaac --- examples/codex/databricks/README.md | 30 +++-- .../codex/src/_agents_codex/_databricks.py | 14 ++- .../src/_agents_codex/_databricks_launcher.py | 110 +++++++++++++---- .../tests}/test_databricks_environment.py | 17 +-- .../codex/tests/test_databricks_launcher.py | 112 ++++++++++++++++++ tests/codex/test_databricks_launcher.py | 51 -------- 6 files changed, 234 insertions(+), 100 deletions(-) rename {tests/codex => packages/codex/tests}/test_databricks_environment.py (88%) create mode 100644 packages/codex/tests/test_databricks_launcher.py delete mode 100644 tests/codex/test_databricks_launcher.py diff --git a/examples/codex/databricks/README.md b/examples/codex/databricks/README.md index 57b7faa624..689e958615 100644 --- a/examples/codex/databricks/README.md +++ b/examples/codex/databricks/README.md @@ -101,19 +101,27 @@ Only the model provider changes; the sandbox, launcher, and tools are identical. ## Tests -`tests/codex/test_databricks_environment.py` and `test_databricks_launcher.py` -cover the `stdio_command` emission, the `stdio://` / header validation, the -factory's running-sandbox precondition, name normalization, and credential and -launcher-argv wiring, plus the launcher's startup-banner filter. They exercise -only the Python layer (not the native admission or a live sandbox), but they -import the packaged class, so run them against an SDK built from this branch. -Install that wheel, this example's requirements, and `pytest`, then run them -explicitly from the repo root (the default `testpaths` -does not include `tests/codex`): +`packages/codex/tests/test_databricks_environment.py` and +`test_databricks_launcher.py` cover the `stdio_command` emission, the `stdio://` +/ header validation, the `for_sandbox` precondition and credential/launcher-argv +wiring, and the launcher's banner filter, credential guard, protocol forwarding, +and exit-code handling. They are in the default `testpaths`, so the normal suite +runs them: ```sh -pytest tests/codex +pytest packages/codex/tests/test_databricks_environment.py packages/codex/tests/test_databricks_launcher.py ``` -The native admission change (`stdio://`) is covered by Rust unit tests in +The environment tests skip without `databricks-sdk` and the `[classic]` extra +installed; the launcher tests run with neither. They exercise the Python layer +only - the native `stdio://` admission is covered by Rust unit tests in `packages/codex/rust/environment.rs` and qualified by the native build. + +## Credentials and session lifetime + +`for_sandbox` captures the workspace token into the environment. With short-lived +(OAuth / U2M) credentials that token expires (about an hour), so build a fresh +environment per session rather than reusing one; `runner.py` does this. The +launcher forwards the exec-server's stderr for diagnostics and returns its exit +code, and closes the exec-server's stdin on teardown so it shuts down (a lingering +one is reaped by the sandbox's inactivity timeout). diff --git a/packages/codex/src/_agents_codex/_databricks.py b/packages/codex/src/_agents_codex/_databricks.py index d549038d1e..8a716b9872 100644 --- a/packages/codex/src/_agents_codex/_databricks.py +++ b/packages/codex/src/_agents_codex/_databricks.py @@ -15,7 +15,6 @@ import sys from collections.abc import Mapping, Sequence from dataclasses import dataclass, field -from pathlib import Path from typing import Any from ._options import RuntimeEnvironment @@ -23,8 +22,10 @@ _DEFAULT_TOOLS: tuple[ExecutorToolName, ...] = ("exec_command", "write_stdin", "apply_patch") -# The launcher the native runtime spawns to bridge executor stdio to the sandbox. -_LAUNCHER = Path(__file__).resolve().parent / "_databricks_launcher.py" +# The launcher module the native runtime spawns (as ``python -m``) to bridge +# executor stdio to the sandbox. A light module with no native imports, so the +# spawned interpreter does not load the runtime. +_LAUNCHER_MODULE = "_agents_codex._databricks_launcher" @dataclass(frozen=True, kw_only=True) @@ -73,6 +74,11 @@ def for_sandbox( launcher to authenticate with. Lifecycle (create / start / poll until running) is the caller's responsibility; this only checks the state. + The derived token is captured into the returned environment. With + short-lived (OAuth / U2M) credentials it expires (about an hour), so + build a fresh environment per session rather than reusing one across + sessions or long-lived turns. + Args: workspace_client: An authenticated ``databricks.sdk.WorkspaceClient``. sandbox_name: An existing, running sandbox, as the bare id or the @@ -106,6 +112,6 @@ def for_sandbox( cwd=cwd, tools=tuple(tools), headers={}, - _argv=(sys.executable, str(_LAUNCHER), name), + _argv=(sys.executable, "-m", _LAUNCHER_MODULE, name), _launch_env={"DATABRICKS_HOST": host, "DATABRICKS_TOKEN": token}, ) diff --git a/packages/codex/src/_agents_codex/_databricks_launcher.py b/packages/codex/src/_agents_codex/_databricks_launcher.py index 0226508dad..957b9e977e 100644 --- a/packages/codex/src/_agents_codex/_databricks_launcher.py +++ b/packages/codex/src/_agents_codex/_databricks_launcher.py @@ -1,24 +1,33 @@ """Launcher the native runtime spawns to bridge executor stdio to a sandbox. -:class:`DatabricksStdioEnvironment` declares this file as a host-owned +:class:`DatabricksStdioEnvironment` declares this module as a host-owned ``stdio_command``. The native runtime starts it and speaks the exec-server wire protocol over its stdin/stdout. This launcher relays that protocol to ``codex exec-server --listen stdio`` running in the Databricks sandbox, over the ``databricks-sdk`` streaming command API (``WorkspaceClient.sandbox.execute_command``, -whose ``CommandProcess`` exposes the command's stdin, stdout and exit). +whose ``CommandProcess`` exposes the command's stdin, stdout, stderr and exit). -It is run as a standalone script - ``python _databricks_launcher.py `` -with ``DATABRICKS_HOST`` and ``DATABRICKS_TOKEN`` in the environment - so it does -not import the ``_agents_codex`` package or the native runtime. Diagnostics go to -stderr so stdout stays a clean protocol channel. +It is run as a module - ``python -m _agents_codex._databricks_launcher `` +with ``DATABRICKS_HOST`` and ``DATABRICKS_TOKEN`` in the environment. It imports +only the standard library and (lazily) ``databricks-sdk``, so the spawned +interpreter does not load the native runtime. Diagnostics go to stderr so stdout +stays a clean protocol channel. + +On session close or cancellation the launcher closes the exec-server's stdin so +it sees EOF and shuts down; the ``databricks-sdk`` command API has no call to kill +the remote process, so a lingering exec-server is reaped by the sandbox's +inactivity timeout. The launcher returns the remote command's exit code. """ from __future__ import annotations import os +import signal import sys import threading from collections.abc import Callable +from contextlib import suppress +from typing import Any def _forward_stdout(read_line: Callable[[], bytes], write: Callable[[bytes], None]) -> None: @@ -41,6 +50,73 @@ def _forward_stdout(read_line: Callable[[], bytes], write: Callable[[bytes], Non write(line) +def _close_stdin(process: Any) -> None: + """Close the exec-server's stdin so it sees EOF and shuts down. Idempotent.""" + with suppress(ValueError, OSError): + process.stdin.close() + + +def _pump_stdin(process: Any) -> None: + try: + while True: + chunk = os.read(0, 65536) + if not chunk: + break + process.stdin.write(chunk) + except (ValueError, OSError): + pass # stdin closed when the command exits or the stream dropped + finally: + _close_stdin(process) + + +def _pump_stderr(process: Any) -> None: + # stderr is a PIPE; forward it to the launcher's stderr so a failing or + # missing exec-server leaves diagnostics instead of vanishing. + try: + while True: + chunk = process.stderr.read1() + if not chunk: + break + os.write(2, chunk) + except (ValueError, OSError): + pass + + +def _run(process: Any, *, install_signals: bool = True) -> int: + """Relay the exec-server protocol over this process's stdio; return its exit code.""" + done = threading.Event() + + def forward() -> None: + try: + _forward_stdout(process.stdout.readline, lambda line: os.write(1, line)) + finally: + done.set() + + def terminate(*_args: object) -> None: + # Session close / cancellation: shut the exec-server down and unblock the relay. + _close_stdin(process) + with suppress(Exception): + process.close() + + if install_signals: + for sig in (signal.SIGTERM, signal.SIGINT): + with suppress(ValueError, OSError): + signal.signal(sig, terminate) + + threading.Thread(target=_pump_stdin, args=(process,), daemon=True).start() + threading.Thread(target=_pump_stderr, args=(process,), daemon=True).start() + threading.Thread(target=forward, daemon=True).start() + + # Loop on a timeout so signal handlers run in the main thread while we wait. + while not done.wait(timeout=1.0): + pass + _close_stdin(process) + try: + return process.wait(timeout=10) + except Exception: # best-effort exit code; cancellation closes the handle + return 0 + + def main() -> int: sandbox_name = sys.argv[1] host = os.environ.get("DATABRICKS_HOST") @@ -58,27 +134,9 @@ def main() -> int: "codex", args=["exec-server", "--listen", "stdio"], text=False, - stderr=StreamMode.DEVNULL, + stderr=StreamMode.PIPE, ) - - def pump_stdin() -> None: - try: - while True: - chunk = os.read(0, 65536) - if not chunk: - break - process.stdin.write(chunk) - except (ValueError, OSError): - pass # stdin closed when the command exits or the stream dropped - finally: - try: - process.stdin.close() - except (ValueError, OSError): - pass - - threading.Thread(target=pump_stdin, daemon=True).start() - _forward_stdout(process.stdout.readline, lambda line: os.write(1, line)) - return 0 + return _run(process) if __name__ == "__main__": diff --git a/tests/codex/test_databricks_environment.py b/packages/codex/tests/test_databricks_environment.py similarity index 88% rename from tests/codex/test_databricks_environment.py rename to packages/codex/tests/test_databricks_environment.py index 5d71465357..2dc8be6290 100644 --- a/tests/codex/test_databricks_environment.py +++ b/packages/codex/tests/test_databricks_environment.py @@ -2,8 +2,7 @@ Cover ``DatabricksStdioEnvironment`` (native ``stdio_command`` emission and url/header validation) and its ``for_sandbox`` constructor (running precondition, -name normalization, credential derivation, and launcher argv/env wiring). Run -from the repo root with the preview wheel installed. +name normalization, credential derivation, and launcher argv/env wiring). """ from __future__ import annotations @@ -15,12 +14,14 @@ import pytest pytest.importorskip("databricks.sdk") +pytest.importorskip("agents.sandbox") from databricks.sdk.service.sandbox import SandboxState -from _agents_codex._databricks import _LAUNCHER from agents.sandbox import DatabricksStdioEnvironment +_LAUNCHER_MODULE = "_agents_codex._databricks_launcher" + class _FakeSandbox: def __init__(self, state: Any) -> None: @@ -49,13 +50,13 @@ def test_to_native_emits_stdio_command() -> None: cwd="/home/sandbox-agent/work", tools=("exec_command", "write_stdin", "apply_patch"), headers={}, - _argv=("/usr/bin/python", "/pkg/_databricks_launcher.py", "sandboxes/sbx"), + _argv=("/usr/bin/python", "-m", _LAUNCHER_MODULE, "sandboxes/sbx"), _launch_env={"DATABRICKS_HOST": "https://h", "DATABRICKS_TOKEN": "t"}, ) native = environment._to_native() assert native["stdio_command"] == { "program": "/usr/bin/python", - "args": ["/pkg/_databricks_launcher.py", "sandboxes/sbx"], + "args": ["-m", _LAUNCHER_MODULE, "sandboxes/sbx"], "env": {"DATABRICKS_HOST": "https://h", "DATABRICKS_TOKEN": "t"}, "cwd": None, } @@ -68,7 +69,7 @@ def test_rejects_non_stdio_url() -> None: url="wss://127.0.0.1:9000", cwd="/w", headers={}, - _argv=("python", "launch.py", "sandboxes/sbx"), + _argv=("python", "-m", _LAUNCHER_MODULE, "sandboxes/sbx"), ) @@ -78,7 +79,7 @@ def test_rejects_headers() -> None: url="stdio://databricks/sbx", cwd="/w", headers={"Authorization": "Bearer x"}, - _argv=("python", "launch.py", "sandboxes/sbx"), + _argv=("python", "-m", _LAUNCHER_MODULE, "sandboxes/sbx"), ) @@ -101,7 +102,7 @@ def test_for_sandbox_wires_launcher_and_credentials() -> None: assert environment.cwd == "/home/sandbox-agent/work" assert dict(environment.headers) == {} assert tuple(environment.tools) == ("exec_command", "write_stdin", "apply_patch") - assert environment._argv == (sys.executable, str(_LAUNCHER), "sandboxes/sbx") + assert environment._argv == (sys.executable, "-m", _LAUNCHER_MODULE, "sandboxes/sbx") assert environment._launch_env == { "DATABRICKS_HOST": "https://my-host.example.com", "DATABRICKS_TOKEN": "tok-abc", diff --git a/packages/codex/tests/test_databricks_launcher.py b/packages/codex/tests/test_databricks_launcher.py new file mode 100644 index 0000000000..a0bc324f9b --- /dev/null +++ b/packages/codex/tests/test_databricks_launcher.py @@ -0,0 +1,112 @@ +"""Tests for the Databricks stdio launcher. + +Cover the startup-banner filter, the credential guard in ``main``, and the +``_run`` bridge: forwarding protocol lines, closing the exec-server stdin, and +surfacing the remote command's exit code. These import only the launcher module +(standard library; ``databricks-sdk`` is lazy), so they run without the optional +dependency. +""" + +from __future__ import annotations + +import os +import sys + +from _agents_codex._databricks_launcher import _forward_stdout, _run, main + + +def _run_forward(lines: list[bytes]) -> list[bytes]: + pending = list(lines) + + def read_line() -> bytes: + return pending.pop(0) if pending else b"" + + written: list[bytes] = [] + _forward_stdout(read_line, written.append) + return written + + +def test_drops_banner_then_forwards_protocol() -> None: + written = _run_forward( + [ + b"\xe2\x9c\x94 Databricks auth already available\n", + b"Launching Codex with Unity Gateway\n", + b"\n", + b'{"jsonrpc":"2.0","id":1}\n', + b'{"jsonrpc":"2.0","method":"x"}\n', + ] + ) + assert written == [ + b'{"jsonrpc":"2.0","id":1}\n', + b'{"jsonrpc":"2.0","method":"x"}\n', + ] + + +def test_forwards_everything_after_protocol_starts() -> None: + written = _run_forward([b'{"a":1}\n', b"not-json-but-mid-stream\n", b'{"b":2}\n']) + assert written == [b'{"a":1}\n', b"not-json-but-mid-stream\n", b'{"b":2}\n'] + + +def test_leading_whitespace_before_brace_is_protocol() -> None: + assert _run_forward([b" banner\n", b' {"a":1}\n']) == [b' {"a":1}\n'] + + +def test_main_requires_credentials(monkeypatch) -> None: + monkeypatch.setattr(sys, "argv", ["launcher", "sandboxes/s"]) + monkeypatch.delenv("DATABRICKS_HOST", raising=False) + monkeypatch.delenv("DATABRICKS_TOKEN", raising=False) + assert main() == 2 + + +class _FakeOutput: + def __init__(self, lines: list[bytes]) -> None: + self._lines = list(lines) + + def readline(self) -> bytes: + return self._lines.pop(0) if self._lines else b"" + + def read1(self) -> bytes: + return self._lines.pop(0) if self._lines else b"" + + +class _FakeStdin: + def __init__(self) -> None: + self.written = bytearray() + self.closed = False + + def write(self, data: bytes) -> None: + self.written.extend(data) + + def close(self) -> None: + self.closed = True + + +class _FakeProcess: + def __init__(self, stdout_lines: list[bytes], exit_code: int = 0) -> None: + self.stdout = _FakeOutput(stdout_lines) + self.stderr = _FakeOutput([]) + self.stdin = _FakeStdin() + self._exit_code = exit_code + + def close(self) -> None: + pass + + def wait(self, timeout: float | None = None) -> int: + return self._exit_code + + +def test_run_forwards_protocol_closes_stdin_and_returns_exit(monkeypatch) -> None: + captured = bytearray() + monkeypatch.setattr(os, "read", lambda fd, n: b"") # stdin EOF immediately + monkeypatch.setattr(os, "write", lambda fd, data: captured.extend(data) if fd == 1 else None) + process = _FakeProcess([b"banner\n", b'{"a":1}\n'], exit_code=0) + assert _run(process, install_signals=False) == 0 + assert bytes(captured) == b'{"a":1}\n' + assert process.stdin.closed + + +def test_run_surfaces_remote_exit_code(monkeypatch) -> None: + monkeypatch.setattr(os, "read", lambda fd, n: b"") + monkeypatch.setattr(os, "write", lambda fd, data: None) + process = _FakeProcess([b'{"x":1}\n'], exit_code=3) + assert _run(process, install_signals=False) == 3 diff --git a/tests/codex/test_databricks_launcher.py b/tests/codex/test_databricks_launcher.py deleted file mode 100644 index 624dc93279..0000000000 --- a/tests/codex/test_databricks_launcher.py +++ /dev/null @@ -1,51 +0,0 @@ -"""Tests for the Databricks stdio launcher's protocol forwarding. - -Cover the startup-banner filter in ``_forward_stdout``: the launcher must drop -``codex``'s non-JSON startup preamble, then forward every exec-server protocol -line verbatim. Run from the repo root with the preview wheel installed. -""" - -from __future__ import annotations - -from _agents_codex._databricks_launcher import _forward_stdout - - -def _run(lines: list[bytes]) -> list[bytes]: - pending = list(lines) - - def read_line() -> bytes: - return pending.pop(0) if pending else b"" - - written: list[bytes] = [] - _forward_stdout(read_line, written.append) - return written - - -def test_drops_banner_then_forwards_protocol() -> None: - written = _run( - [ - b"\xe2\x9c\x94 Databricks auth already available\n", - b"Launching Codex with Unity Gateway\n", - b"\n", - b'{"jsonrpc":"2.0","id":1}\n', - b'{"jsonrpc":"2.0","method":"x"}\n', - ] - ) - assert written == [ - b'{"jsonrpc":"2.0","id":1}\n', - b'{"jsonrpc":"2.0","method":"x"}\n', - ] - - -def test_forwards_everything_after_protocol_starts() -> None: - written = _run([b'{"a":1}\n', b"not-json-but-mid-stream\n", b'{"b":2}\n']) - assert written == [b'{"a":1}\n', b"not-json-but-mid-stream\n", b'{"b":2}\n'] - - -def test_leading_whitespace_before_brace_is_protocol() -> None: - written = _run([b" banner\n", b' {"a":1}\n']) - assert written == [b' {"a":1}\n'] - - -def test_stops_at_eof_with_no_protocol() -> None: - assert _run([b"banner one\n", b"banner two\n"]) == [] From 9257a3ec98fd67f81041b99ff514c98c7d68811c Mon Sep 17 00:00:00 2001 From: Hsing Tang Date: Tue, 17 Nov 2026 00:23:57 +0000 Subject: [PATCH 5/9] fix: guarantee launcher exits on signal and expand launcher/env tests - Set the done event in the SIGTERM/SIGINT handler so the launcher's main loop always returns, even if closing the stream does not unblock the relay read (previously it could ignore SIGTERM until SIGKILL). Factor the teardown into a module-level _terminate for testing. - Make the environment tests run without databricks-sdk / the [classic] extra: import the class from its owning module and satisfy for_sandbox's lazy databricks.sdk import with an injected fake. Add missing-token and None-status cases and an agents.sandbox export assertion. - Cover the launcher's stdin relay (and close-on-write-error), the terminate / signal-installation path, and main()'s execute_command call shape. Co-authored-by: Isaac --- .../src/_agents_codex/_databricks_launcher.py | 24 ++- .../tests/test_databricks_environment.py | 113 ++++++++----- .../codex/tests/test_databricks_launcher.py | 150 +++++++++++++++--- 3 files changed, 219 insertions(+), 68 deletions(-) diff --git a/packages/codex/src/_agents_codex/_databricks_launcher.py b/packages/codex/src/_agents_codex/_databricks_launcher.py index 957b9e977e..dca27b5124 100644 --- a/packages/codex/src/_agents_codex/_databricks_launcher.py +++ b/packages/codex/src/_agents_codex/_databricks_launcher.py @@ -82,6 +82,18 @@ def _pump_stderr(process: Any) -> None: pass +def _terminate(process: Any, done: threading.Event) -> None: + """Shut the exec-server down and release the relay on session close/cancellation. + + Sets ``done`` so the main loop always returns, even if closing the stream does + not unblock a pending read; the daemon relay thread is then abandoned. + """ + _close_stdin(process) + with suppress(Exception): + process.close() + done.set() + + def _run(process: Any, *, install_signals: bool = True) -> int: """Relay the exec-server protocol over this process's stdio; return its exit code.""" done = threading.Event() @@ -92,16 +104,14 @@ def forward() -> None: finally: done.set() - def terminate(*_args: object) -> None: - # Session close / cancellation: shut the exec-server down and unblock the relay. - _close_stdin(process) - with suppress(Exception): - process.close() - if install_signals: + + def handler(*_args: object) -> None: + _terminate(process, done) + for sig in (signal.SIGTERM, signal.SIGINT): with suppress(ValueError, OSError): - signal.signal(sig, terminate) + signal.signal(sig, handler) threading.Thread(target=_pump_stdin, args=(process,), daemon=True).start() threading.Thread(target=_pump_stderr, args=(process,), daemon=True).start() diff --git a/packages/codex/tests/test_databricks_environment.py b/packages/codex/tests/test_databricks_environment.py index 2dc8be6290..c9fffe72bd 100644 --- a/packages/codex/tests/test_databricks_environment.py +++ b/packages/codex/tests/test_databricks_environment.py @@ -1,47 +1,23 @@ -"""Tests for the Databricks sandbox stdio environment (``agents.sandbox``). +"""Tests for the Databricks sandbox stdio environment. Cover ``DatabricksStdioEnvironment`` (native ``stdio_command`` emission and url/header validation) and its ``for_sandbox`` constructor (running precondition, -name normalization, credential derivation, and launcher argv/env wiring). +name normalization, credential derivation, launcher argv/env wiring). The class +is imported from its owning module so these run without the optional +``databricks-sdk`` / ``[classic]`` extras; ``for_sandbox``'s lazy +``databricks.sdk`` import is satisfied with an injected fake. """ from __future__ import annotations import sys +import types from types import SimpleNamespace from typing import Any import pytest -pytest.importorskip("databricks.sdk") -pytest.importorskip("agents.sandbox") - -from databricks.sdk.service.sandbox import SandboxState - -from agents.sandbox import DatabricksStdioEnvironment - -_LAUNCHER_MODULE = "_agents_codex._databricks_launcher" - - -class _FakeSandbox: - def __init__(self, state: Any) -> None: - self._state = state - - def get_sandbox(self, name: str) -> SimpleNamespace: - return SimpleNamespace(status=SimpleNamespace(state=self._state)) - - -class _FakeConfig: - host = "https://my-host.example.com/" - - def authenticate(self) -> dict[str, str]: - return {"Authorization": "Bearer tok-abc"} - - -class _FakeWorkspaceClient: - def __init__(self, state: Any = SandboxState.SANDBOX_STATE_RUNNING) -> None: - self.sandbox = _FakeSandbox(state) - self.config = _FakeConfig() +from _agents_codex._databricks import _LAUNCHER_MODULE, DatabricksStdioEnvironment def test_to_native_emits_stdio_command() -> None: @@ -83,18 +59,75 @@ def test_rejects_headers() -> None: ) -def test_for_sandbox_rejects_non_running() -> None: +class _FakeSandboxState: + SANDBOX_STATE_RUNNING = "RUNNING" + SANDBOX_STATE_STOPPED = "STOPPED" + + +@pytest.fixture +def fake_sandbox_state(monkeypatch: pytest.MonkeyPatch) -> type[_FakeSandboxState]: + for name in ("databricks", "databricks.sdk", "databricks.sdk.service"): + monkeypatch.setitem(sys.modules, name, types.ModuleType(name)) + module = types.ModuleType("databricks.sdk.service.sandbox") + module.SandboxState = _FakeSandboxState # type: ignore[attr-defined] + monkeypatch.setitem(sys.modules, "databricks.sdk.service.sandbox", module) + return _FakeSandboxState + + +class _FakeSandbox: + def __init__(self, state: Any) -> None: + self._state = state + + def get_sandbox(self, name: str) -> SimpleNamespace: + return SimpleNamespace(status=SimpleNamespace(state=self._state)) + + +class _FakeConfig: + def __init__(self, auth: dict[str, str]) -> None: + self.host = "https://my-host.example.com/" + self._auth = auth + + def authenticate(self) -> dict[str, str]: + return self._auth + + +class _FakeWorkspaceClient: + def __init__(self, state: Any, auth: dict[str, str] | None = None) -> None: + self.sandbox = _FakeSandbox(state) + self.config = _FakeConfig({"Authorization": "Bearer tok-abc"} if auth is None else auth) + + +def test_for_sandbox_rejects_non_running(fake_sandbox_state: type[_FakeSandboxState]) -> None: with pytest.raises(RuntimeError, match="not running"): DatabricksStdioEnvironment.for_sandbox( - workspace_client=_FakeWorkspaceClient(SandboxState.SANDBOX_STATE_STOPPED), + workspace_client=_FakeWorkspaceClient(fake_sandbox_state.SANDBOX_STATE_STOPPED), sandbox_name="sbx", cwd="/w", ) -def test_for_sandbox_wires_launcher_and_credentials() -> None: +def test_for_sandbox_rejects_none_status(fake_sandbox_state: type[_FakeSandboxState]) -> None: + client = _FakeWorkspaceClient(fake_sandbox_state.SANDBOX_STATE_RUNNING) + client.sandbox.get_sandbox = lambda name: SimpleNamespace(status=None) # type: ignore[method-assign] + with pytest.raises(RuntimeError, match="not running"): + DatabricksStdioEnvironment.for_sandbox( + workspace_client=client, sandbox_name="sbx", cwd="/w" + ) + + +def test_for_sandbox_rejects_missing_token(fake_sandbox_state: type[_FakeSandboxState]) -> None: + client = _FakeWorkspaceClient(fake_sandbox_state.SANDBOX_STATE_RUNNING, auth={}) + with pytest.raises(RuntimeError, match="Could not derive"): + DatabricksStdioEnvironment.for_sandbox( + workspace_client=client, sandbox_name="sbx", cwd="/w" + ) + + +def test_for_sandbox_wires_launcher_and_credentials( + fake_sandbox_state: type[_FakeSandboxState], +) -> None: environment = DatabricksStdioEnvironment.for_sandbox( - workspace_client=_FakeWorkspaceClient(), + workspace_client=_FakeWorkspaceClient(fake_sandbox_state.SANDBOX_STATE_RUNNING), sandbox_name="sbx", cwd="/home/sandbox-agent/work", ) @@ -109,11 +142,17 @@ def test_for_sandbox_wires_launcher_and_credentials() -> None: } -def test_for_sandbox_accepts_resource_name() -> None: +def test_for_sandbox_accepts_resource_name(fake_sandbox_state: type[_FakeSandboxState]) -> None: environment = DatabricksStdioEnvironment.for_sandbox( - workspace_client=_FakeWorkspaceClient(), + workspace_client=_FakeWorkspaceClient(fake_sandbox_state.SANDBOX_STATE_RUNNING), sandbox_name="sandboxes/sbx", cwd="/w", ) assert environment.url == "stdio://databricks/sbx" assert environment._argv[-1] == "sandboxes/sbx" + + +def test_exported_from_agents_sandbox() -> None: + sandbox = pytest.importorskip("agents.sandbox") + assert "DatabricksStdioEnvironment" in sandbox.__all__ + assert sandbox.DatabricksStdioEnvironment is DatabricksStdioEnvironment diff --git a/packages/codex/tests/test_databricks_launcher.py b/packages/codex/tests/test_databricks_launcher.py index a0bc324f9b..3ce899f689 100644 --- a/packages/codex/tests/test_databricks_launcher.py +++ b/packages/codex/tests/test_databricks_launcher.py @@ -1,18 +1,28 @@ """Tests for the Databricks stdio launcher. -Cover the startup-banner filter, the credential guard in ``main``, and the -``_run`` bridge: forwarding protocol lines, closing the exec-server stdin, and -surfacing the remote command's exit code. These import only the launcher module -(standard library; ``databricks-sdk`` is lazy), so they run without the optional -dependency. +Cover the startup-banner filter, the credential guard, the stdin relay, the +teardown/signal path, the remote exit-code handling, and ``main``'s +``execute_command`` wiring. These import only the launcher module (standard +library; ``databricks-sdk`` is lazy), so they run without the optional +dependency; ``main``'s lazy imports are satisfied with injected fakes. """ from __future__ import annotations import os +import signal import sys +import threading +import types +from types import SimpleNamespace -from _agents_codex._databricks_launcher import _forward_stdout, _run, main +from _agents_codex._databricks_launcher import ( + _forward_stdout, + _pump_stdin, + _run, + _terminate, + main, +) def _run_forward(lines: list[bytes]) -> list[bytes]: @@ -36,10 +46,7 @@ def test_drops_banner_then_forwards_protocol() -> None: b'{"jsonrpc":"2.0","method":"x"}\n', ] ) - assert written == [ - b'{"jsonrpc":"2.0","id":1}\n', - b'{"jsonrpc":"2.0","method":"x"}\n', - ] + assert written == [b'{"jsonrpc":"2.0","id":1}\n', b'{"jsonrpc":"2.0","method":"x"}\n'] def test_forwards_everything_after_protocol_starts() -> None: @@ -58,17 +65,6 @@ def test_main_requires_credentials(monkeypatch) -> None: assert main() == 2 -class _FakeOutput: - def __init__(self, lines: list[bytes]) -> None: - self._lines = list(lines) - - def readline(self) -> bytes: - return self._lines.pop(0) if self._lines else b"" - - def read1(self) -> bytes: - return self._lines.pop(0) if self._lines else b"" - - class _FakeStdin: def __init__(self) -> None: self.written = bytearray() @@ -81,23 +77,71 @@ def close(self) -> None: self.closed = True +class _FakeOutput: + def __init__(self, lines: list[bytes]) -> None: + self._lines = list(lines) + + def readline(self) -> bytes: + return self._lines.pop(0) if self._lines else b"" + + def read1(self) -> bytes: + return self._lines.pop(0) if self._lines else b"" + + class _FakeProcess: def __init__(self, stdout_lines: list[bytes], exit_code: int = 0) -> None: self.stdout = _FakeOutput(stdout_lines) self.stderr = _FakeOutput([]) self.stdin = _FakeStdin() + self.closed = False self._exit_code = exit_code def close(self) -> None: - pass + self.closed = True def wait(self, timeout: float | None = None) -> int: return self._exit_code -def test_run_forwards_protocol_closes_stdin_and_returns_exit(monkeypatch) -> None: +def test_pump_stdin_relays_chunks_and_closes(monkeypatch) -> None: + chunks = [b'{"id":1}\n', b"more\n", b""] + monkeypatch.setattr(os, "read", lambda fd, n: chunks.pop(0) if chunks else b"") + process = _FakeProcess([]) + _pump_stdin(process) + assert bytes(process.stdin.written) == b'{"id":1}\nmore\n' + assert process.stdin.closed + + +def test_pump_stdin_closes_on_write_error(monkeypatch) -> None: + monkeypatch.setattr(os, "read", lambda fd, n: b"x") + + class _BadStdin: + def __init__(self) -> None: + self.closed = False + + def write(self, data: bytes) -> None: + raise OSError("boom") + + def close(self) -> None: + self.closed = True + + process = SimpleNamespace(stdin=_BadStdin()) + _pump_stdin(process) + assert process.stdin.closed + + +def test_terminate_closes_stdin_and_sets_done() -> None: + done = threading.Event() + process = _FakeProcess([]) + _terminate(process, done) + assert process.stdin.closed + assert process.closed + assert done.is_set() + + +def test_run_forwards_protocol_and_returns_exit(monkeypatch) -> None: captured = bytearray() - monkeypatch.setattr(os, "read", lambda fd, n: b"") # stdin EOF immediately + monkeypatch.setattr(os, "read", lambda fd, n: b"") monkeypatch.setattr(os, "write", lambda fd, data: captured.extend(data) if fd == 1 else None) process = _FakeProcess([b"banner\n", b'{"a":1}\n'], exit_code=0) assert _run(process, install_signals=False) == 0 @@ -110,3 +154,61 @@ def test_run_surfaces_remote_exit_code(monkeypatch) -> None: monkeypatch.setattr(os, "write", lambda fd, data: None) process = _FakeProcess([b'{"x":1}\n'], exit_code=3) assert _run(process, install_signals=False) == 3 + + +def test_run_installs_signal_handlers(monkeypatch) -> None: + registered: dict[int, object] = {} + monkeypatch.setattr(signal, "signal", lambda sig, handler: registered.__setitem__(sig, handler)) + monkeypatch.setattr(os, "read", lambda fd, n: b"") + monkeypatch.setattr(os, "write", lambda fd, data: None) + process = _FakeProcess([b'{"a":1}\n'], exit_code=0) + _run(process, install_signals=True) + assert signal.SIGTERM in registered + assert signal.SIGINT in registered + registered[signal.SIGTERM]() # type: ignore[operator] + assert process.stdin.closed + assert process.closed + + +def test_main_launches_exec_server(monkeypatch) -> None: + recorded: dict[str, object] = {} + + class _FakeStreamMode: + PIPE = "PIPE" + DEVNULL = "DEVNULL" + + class _FakeSandboxService: + def execute_command(self, name, cmd, *, args, text, stderr) -> _FakeProcess: + recorded.update(name=name, cmd=cmd, args=args, text=text, stderr=stderr) + return _FakeProcess([b'{"a":1}\n']) + + class _FakeWorkspaceClient: + def __init__(self, *, host, token) -> None: + recorded.update(host=host, token=token) + self.sandbox = _FakeSandboxService() + + sdk = types.ModuleType("databricks.sdk") + sdk.WorkspaceClient = _FakeWorkspaceClient # type: ignore[attr-defined] + mixins_sandbox = types.ModuleType("databricks.sdk.mixins.sandbox") + mixins_sandbox.StreamMode = _FakeStreamMode # type: ignore[attr-defined] + modules = { + "databricks": types.ModuleType("databricks"), + "databricks.sdk": sdk, + "databricks.sdk.mixins": types.ModuleType("databricks.sdk.mixins"), + "databricks.sdk.mixins.sandbox": mixins_sandbox, + } + for name, module in modules.items(): + monkeypatch.setitem(sys.modules, name, module) + monkeypatch.setenv("DATABRICKS_HOST", "https://h") + monkeypatch.setenv("DATABRICKS_TOKEN", "t") + monkeypatch.setattr(sys, "argv", ["launcher", "sandboxes/s"]) + monkeypatch.setattr("_agents_codex._databricks_launcher._run", lambda process, **kwargs: 0) + + assert main() == 0 + assert recorded["host"] == "https://h" + assert recorded["token"] == "t" + assert recorded["name"] == "sandboxes/s" + assert recorded["cmd"] == "codex" + assert recorded["args"] == ["exec-server", "--listen", "stdio"] + assert recorded["text"] is False + assert recorded["stderr"] == "PIPE" From 7d7d34a2586bd32fbec28de2b377ab280fd12b61 Mon Sep 17 00:00:00 2001 From: Hsing Tang Date: Tue, 17 Nov 2026 03:58:26 +0000 Subject: [PATCH 6/9] docs: fix staleness and tone in Databricks example README Correct the Tests-section claim (the tests run without databricks-sdk / the [classic] extra via an injected fake), lead with the first-class class, name the [classic] extra (openai-agents[classic]) needed by the public import path, drop the invented "v1.0" label, add stderr to the CommandProcess description, and fix tests/codex -> packages/codex/tests. Co-authored-by: Isaac --- examples/codex/databricks/README.md | 39 ++++++++++++++++------------- 1 file changed, 21 insertions(+), 18 deletions(-) diff --git a/examples/codex/databricks/README.md b/examples/codex/databricks/README.md index 689e958615..fcdac153c3 100644 --- a/examples/codex/databricks/README.md +++ b/examples/codex/databricks/README.md @@ -1,13 +1,13 @@ # Databricks sandbox executor -Back a native `Environment` with a Databricks sandbox, so an agent driven by -this SDK runs `exec_command` / `write_stdin` / `apply_patch` inside the sandbox. -This is the "remote execution" pattern from `docs/sdk/execution.md`, built the -same way the SDK's own Docker support is: `agents.sandbox.DatabricksStdioEnvironment` -is an `Environment` subclass that declares a host-owned `stdio_command` the -native runtime spawns, and the runtime speaks the exec-server protocol over that -process's stdin/stdout. It is the Databricks counterpart of -`agents.sandbox.DockerGateway`. +Run an agent driven by this SDK with its `exec_command` / `write_stdin` / +`apply_patch` tools executing inside a Databricks sandbox. +`agents.sandbox.DatabricksStdioEnvironment` is the first-class `Environment` +subclass that does this - the "remote execution" pattern from +`docs/sdk/execution.md`, built the same way the SDK's own Docker support is: it +declares a host-owned `stdio_command` the native runtime spawns, and the runtime +speaks the exec-server protocol over that process's stdin/stdout. It is the +Databricks counterpart of `agents.sandbox.DockerGateway`. > **Status.** The stdio transport and the full turn are validated end-to-end > against a live Databricks sandbox on the `0.24.0-alpha.8` preview wheel: a real @@ -18,7 +18,7 @@ process's stdin/stdout. It is the Databricks counterpart of > native runtime (`packages/codex/rust/environment.rs`); it is not yet in a > released preview wheel. Until it ships, build the SDK from this branch (see > `packages/codex/MAINTAINING.md`). The Python pieces are covered by -> `tests/codex/` against the released wheel. +> `packages/codex/tests/` against the released wheel. ## How it works @@ -30,7 +30,7 @@ the native runtime spawns that launcher and speaks the exec-server wire protocol over its stdin/stdout. The launcher relays that protocol to `codex exec-server --listen stdio` inside the sandbox over the `databricks-sdk` streaming command API (`WorkspaceClient.sandbox.execute_command`, whose `CommandProcess` exposes the -command's `stdin`, `stdout` and exit). It does not parse the protocol; it only +command's `stdin`, `stdout`, `stderr` and exit). It does not parse the protocol; it only drops a startup banner the sandbox's `codex` prints on stdout before the protocol begins (non-JSON lines) so it never reaches the runtime as a bogus message. @@ -38,8 +38,8 @@ Because the runtime owns the launcher process and talks to it over ordinary pipes, there is no WebSocket gateway, no TLS termination, and no shared-secret handshake. `execute_command` reaches the sandbox outbound through the Databricks control plane, so the sandbox needs no inbound ingress. The agent loop runs in -your process (via `NativeProvider`), which is what makes the `Environment` -approval / transform callbacks and `NetworkPolicy` available. +your process (via `NativeProvider`), so the `Environment` approval / transform +callbacks and `NetworkPolicy` stay available. ## Files @@ -48,12 +48,13 @@ approval / transform callbacks and `NetworkPolicy` available. ## Install and run -The v1.0 SDK is a GitHub preview wheel (off PyPI). It ships a compiled native -runtime, so it needs a supported host: **Linux x86_64 with glibc 2.28 or newer**, +The SDK is distributed as a GitHub preview wheel (off PyPI). It ships a compiled +native runtime, so it needs a supported host: **Linux x86_64 with glibc 2.28 or newer**, macOS arm64, or Windows x64. This example additionally needs the host-owned `stdio://` executor source (see **Status** above), so build the SDK from this branch per `packages/codex/MAINTAINING.md` until that change is in a released -wheel. Then install this example's requirements: +wheel. Install it with the `[classic]` extra (`openai-agents[classic]`). Then +install this example's requirements: ```sh pip install -r examples/codex/databricks/requirements.txt @@ -112,9 +113,11 @@ runs them: pytest packages/codex/tests/test_databricks_environment.py packages/codex/tests/test_databricks_launcher.py ``` -The environment tests skip without `databricks-sdk` and the `[classic]` extra -installed; the launcher tests run with neither. They exercise the Python layer -only - the native `stdio://` admission is covered by Rust unit tests in +Both test modules run without `databricks-sdk` or the `[classic]` extra - +`for_sandbox`'s lazy `databricks.sdk` import is satisfied with an injected fake - +except one assertion that imports `agents.sandbox` and is skipped unless +`[classic]` is installed. They exercise the Python layer only; the native +`stdio://` admission is covered by Rust unit tests in `packages/codex/rust/environment.rs` and qualified by the native build. ## Credentials and session lifetime From 1c94ad34fb37b5ee80aca23e2f1084001024d01f Mon Sep 17 00:00:00 2001 From: Hsing Tang Date: Tue, 17 Nov 2026 04:18:02 +0000 Subject: [PATCH 7/9] docs: trim and retone Databricks example README Cut the Status, How it works, Files, and Tests sections; add a Usage example Python snippet; rename the run section to "Install and run the example" and make the shell blocks clearly launch runner.py; use my-sandbox in all examples; call the config a .databrickscfg profile (not a CLI profile); qualify DatabricksStdioEnvironment.for_sandbox in prose; rework the codex-binary prerequisite; and add a References section. Co-authored-by: Isaac --- examples/codex/databricks/README.md | 140 +++++++++++----------------- examples/codex/databricks/runner.py | 6 +- 2 files changed, 56 insertions(+), 90 deletions(-) diff --git a/examples/codex/databricks/README.md b/examples/codex/databricks/README.md index fcdac153c3..78997718c2 100644 --- a/examples/codex/databricks/README.md +++ b/examples/codex/databricks/README.md @@ -2,70 +2,52 @@ Run an agent driven by this SDK with its `exec_command` / `write_stdin` / `apply_patch` tools executing inside a Databricks sandbox. -`agents.sandbox.DatabricksStdioEnvironment` is the first-class `Environment` -subclass that does this - the "remote execution" pattern from -`docs/sdk/execution.md`, built the same way the SDK's own Docker support is: it -declares a host-owned `stdio_command` the native runtime spawns, and the runtime -speaks the exec-server protocol over that process's stdin/stdout. It is the -Databricks counterpart of `agents.sandbox.DockerGateway`. - -> **Status.** The stdio transport and the full turn are validated end-to-end -> against a live Databricks sandbox on the `0.24.0-alpha.8` preview wheel: a real -> `codex exec-server` ran the agent's tool call in the sandbox with no gateway -> server and no TLS, driven over the `databricks-sdk` streaming command API, for -> both model providers (Databricks AI Gateway and OpenAI direct). The `stdio://` -> executor source requires the host-owned stdio admission change in this PR's -> native runtime (`packages/codex/rust/environment.rs`); it is not yet in a -> released preview wheel. Until it ships, build the SDK from this branch (see -> `packages/codex/MAINTAINING.md`). The Python pieces are covered by -> `packages/codex/tests/` against the released wheel. - -## How it works - -`DatabricksStdioEnvironment.for_sandbox(...)` confirms the sandbox is running, -derives the workspace host and token from the `WorkspaceClient`, and returns an -environment to hand to `agent.session(environment=...)`. The environment emits a -`stdio_command`: the argv of a local launcher process. When the session opens, -the native runtime spawns that launcher and speaks the exec-server wire protocol -over its stdin/stdout. The launcher relays that protocol to `codex exec-server ---listen stdio` inside the sandbox over the `databricks-sdk` streaming command -API (`WorkspaceClient.sandbox.execute_command`, whose `CommandProcess` exposes the -command's `stdin`, `stdout`, `stderr` and exit). It does not parse the protocol; it only -drops a startup banner the sandbox's `codex` prints on stdout before the protocol -begins (non-JSON lines) so it never reaches the runtime as a bogus message. - -Because the runtime owns the launcher process and talks to it over ordinary -pipes, there is no WebSocket gateway, no TLS termination, and no shared-secret -handshake. `execute_command` reaches the sandbox outbound through the Databricks -control plane, so the sandbox needs no inbound ingress. The agent loop runs in -your process (via `NativeProvider`), so the `Environment` approval / transform -callbacks and `NetworkPolicy` stay available. - -## Files - -- `runner.py` - a runnable end-to-end example. The environment itself is the - first-class `agents.sandbox.DatabricksStdioEnvironment`. - -## Install and run +`agents.sandbox.DatabricksStdioEnvironment` is the first-class `Environment` for +this - the Databricks counterpart of `agents.sandbox.DockerGateway`, following +the SDK's "remote execution" pattern (`docs/sdk/execution.md`). + +## Usage example + +```python +from databricks.sdk import WorkspaceClient +from agents import Agent, NativeProvider +from agents.sandbox import DatabricksStdioEnvironment + +w = WorkspaceClient(profile="my-workspace") +# Provision "my-sandbox" (create_sandbox + poll until running); see runner.py. + +environment = DatabricksStdioEnvironment.for_sandbox( + workspace_client=w, + sandbox_name="my-sandbox", + cwd="/home/sandbox-agent/work", +) +async with NativeProvider( + base_url="https:///ai-gateway/codex/v1", + api_key=w.config.authenticate()["Authorization"].removeprefix("Bearer "), + supports_websockets=False, +) as provider: + agent = Agent(model="gpt-5.5", provider=provider, instructions="...") + async with agent.session(environment=environment) as session: + result = await (await session.submit("Inspect the workspace")).get_result() + print(result.final_output) +``` + +## Install and run the example The SDK is distributed as a GitHub preview wheel (off PyPI). It ships a compiled native runtime, so it needs a supported host: **Linux x86_64 with glibc 2.28 or newer**, -macOS arm64, or Windows x64. This example additionally needs the host-owned -`stdio://` executor source (see **Status** above), so build the SDK from this -branch per `packages/codex/MAINTAINING.md` until that change is in a released -wheel. Install it with the `[classic]` extra (`openai-agents[classic]`). Then -install this example's requirements: +macOS arm64, or Windows x64. ```sh pip install -r examples/codex/databricks/requirements.txt ``` -Provide Databricks auth (a CLI profile) and run from the repo root. The model -runs through the workspace's Databricks AI Gateway by default, using the -profile's own token, so no OpenAI key is needed: +Provide Databricks auth (a `.databrickscfg` profile), then run the example script +`runner.py` from the repo root. The model runs through the workspace's Databricks +AI Gateway by default, using the profile's own token, so no OpenAI key is needed: ```sh -SANDBOX_NAME=openai-agent-sandbox DATABRICKS_CONFIG_PROFILE=my-workspace \ +SANDBOX_NAME=my-sandbox DATABRICKS_CONFIG_PROFILE=my-workspace \ PYTHONPATH=. python -m examples.codex.databricks.runner "Inspect the workspace" ``` @@ -79,7 +61,7 @@ set `OPENAI_BASE_URL`, `OPENAI_API_KEY`, and an OpenAI model id your account can use: ```sh -SANDBOX_NAME=openai-agent-sandbox DATABRICKS_CONFIG_PROFILE=my-workspace \ +SANDBOX_NAME=my-sandbox DATABRICKS_CONFIG_PROFILE=my-workspace \ OPENAI_BASE_URL=https://api.openai.com/v1 OPENAI_API_KEY=sk-... \ OPENAI_MODEL=gpt-5.3-codex \ PYTHONPATH=. python -m examples.codex.databricks.runner "Inspect the workspace" @@ -92,39 +74,23 @@ Only the model provider changes; the sandbox, launcher, and tools are identical. 1. **A running sandbox.** The application creates the sandbox (or reuses one), starts it if stopped, and polls its status until running before opening the environment - the exec-server is reached through `execute_command`, which - needs a running sandbox. `runner.py` shows this, and - `DatabricksStdioEnvironment.for_sandbox` confirms it. -2. **exec-server stdio mode in the image.** The sandbox's `codex` runs the - standalone exec-server over stdio with `codex exec-server --listen stdio`, - which the launcher relays. -3. **An SDK build with the host-owned `stdio://` executor source** (see - **Status**). - -## Tests - -`packages/codex/tests/test_databricks_environment.py` and -`test_databricks_launcher.py` cover the `stdio_command` emission, the `stdio://` -/ header validation, the `for_sandbox` precondition and credential/launcher-argv -wiring, and the launcher's banner filter, credential guard, protocol forwarding, -and exit-code handling. They are in the default `testpaths`, so the normal suite -runs them: - -```sh -pytest packages/codex/tests/test_databricks_environment.py packages/codex/tests/test_databricks_launcher.py -``` - -Both test modules run without `databricks-sdk` or the `[classic]` extra - -`for_sandbox`'s lazy `databricks.sdk` import is satisfied with an injected fake - -except one assertion that imports `agents.sandbox` and is skipped unless -`[classic]` is installed. They exercise the Python layer only; the native -`stdio://` admission is covered by Rust unit tests in -`packages/codex/rust/environment.rs` and qualified by the native build. + needs a running sandbox. +2. **A `codex` binary in the sandbox image.** The launcher runs + `codex exec-server --listen stdio` in the sandbox. The default sandbox image + already contains a compatible `codex` binary; for a + [user-supplied custom image](https://docs.databricks.com/aws/en/compute/serverless/sandbox-custom-image), + ensure `codex` is installed. +3. **An SDK build with the host-owned `stdio://` executor source.** ## Credentials and session lifetime -`for_sandbox` captures the workspace token into the environment. With short-lived +`DatabricksStdioEnvironment.for_sandbox` captures the workspace token into the environment. With short-lived (OAuth / U2M) credentials that token expires (about an hour), so build a fresh -environment per session rather than reusing one; `runner.py` does this. The -launcher forwards the exec-server's stderr for diagnostics and returns its exit -code, and closes the exec-server's stdin on teardown so it shuts down (a lingering -one is reaped by the sandbox's inactivity timeout). +environment per session rather than reusing one. The launcher forwards the +exec-server's stderr for diagnostics and returns its exit code, and closes the +exec-server's stdin on teardown so it shuts down. + +## References + +- [Databricks Sandbox documentation](https://docs.databricks.com/aws/en/compute/serverless/sandbox) +- [Sandbox SDK on databricks-sdk for Python](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/sandbox/sandbox.html) diff --git a/examples/codex/databricks/runner.py b/examples/codex/databricks/runner.py index 7b7a6711b3..39c21352a2 100644 --- a/examples/codex/databricks/runner.py +++ b/examples/codex/databricks/runner.py @@ -3,10 +3,10 @@ Prerequisites (see README.md): - the SDK preview wheel plus this example's requirements.txt - a Databricks sandbox whose image carries the ``codex`` exec-server - - Databricks auth (a CLI profile) + - Databricks auth (a .databrickscfg profile) Environment variables: - DATABRICKS_CONFIG_PROFILE Databricks CLI profile (default: DEFAULT) + DATABRICKS_CONFIG_PROFILE .databrickscfg profile name (default: DEFAULT) SANDBOX_NAME sandbox id or ``sandboxes/`` resource name (required) SANDBOX_CWD remote workspace path (default: /home/sandbox-agent/work) SANDBOX_CREATE "1" to provision the sandbox if absent (default: off) @@ -32,7 +32,7 @@ provider (for example OpenAI directly). Run: - SANDBOX_NAME=openai-agent-sandbox DATABRICKS_CONFIG_PROFILE=my-workspace \ + SANDBOX_NAME=my-sandbox DATABRICKS_CONFIG_PROFILE=my-workspace \ PYTHONPATH=. python -m examples.codex.databricks.runner "Inspect the project" """ From 59ca166a10fcb0e1dfaa4198b84e40fa75776142 Mon Sep 17 00:00:00 2001 From: Hsing Tang Date: Tue, 17 Nov 2026 04:27:04 +0000 Subject: [PATCH 8/9] docs: tighten Databricks example README Drop the redundant "only the model provider changes" line and the stdio:// SDK-build prerequisite, and rewrap the credentials paragraph. Co-authored-by: Isaac --- examples/codex/databricks/README.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/examples/codex/databricks/README.md b/examples/codex/databricks/README.md index 78997718c2..8d7f79a3a3 100644 --- a/examples/codex/databricks/README.md +++ b/examples/codex/databricks/README.md @@ -67,8 +67,6 @@ SANDBOX_NAME=my-sandbox DATABRICKS_CONFIG_PROFILE=my-workspace \ PYTHONPATH=. python -m examples.codex.databricks.runner "Inspect the workspace" ``` -Only the model provider changes; the sandbox, launcher, and tools are identical. - ## Prerequisites 1. **A running sandbox.** The application creates the sandbox (or reuses one), @@ -80,15 +78,14 @@ Only the model provider changes; the sandbox, launcher, and tools are identical. already contains a compatible `codex` binary; for a [user-supplied custom image](https://docs.databricks.com/aws/en/compute/serverless/sandbox-custom-image), ensure `codex` is installed. -3. **An SDK build with the host-owned `stdio://` executor source.** ## Credentials and session lifetime -`DatabricksStdioEnvironment.for_sandbox` captures the workspace token into the environment. With short-lived -(OAuth / U2M) credentials that token expires (about an hour), so build a fresh -environment per session rather than reusing one. The launcher forwards the -exec-server's stderr for diagnostics and returns its exit code, and closes the -exec-server's stdin on teardown so it shuts down. +`DatabricksStdioEnvironment.for_sandbox` captures the workspace token into the +environment. With short-lived (OAuth / U2M) credentials that token expires (about +an hour), so build a fresh environment per session rather than reusing one. The +launcher forwards the exec-server's stderr for diagnostics and returns its exit +code, and closes the exec-server's stdin on teardown so it shuts down. ## References From a7341ac046276e4715dfadaeb60242da9d4ee303 Mon Sep 17 00:00:00 2001 From: Hsing Tang Date: Tue, 17 Nov 2026 04:48:42 +0000 Subject: [PATCH 9/9] fix: require both OpenAI overrides together in the Databricks example Resolve OPENAI_BASE_URL and OPENAI_API_KEY as a pair in runner.py: with neither set, use the Databricks AI Gateway and a profile token; with both, use the given provider; with exactly one, raise instead of silently sending a key to the wrong endpoint. Document the pairing in the README, and correct the SANDBOX_CREATE docstring - the runner creates unconditionally when set, it does not check for an existing sandbox. Co-authored-by: Isaac --- examples/codex/databricks/README.md | 4 ++-- examples/codex/databricks/runner.py | 37 ++++++++++++++++------------- 2 files changed, 23 insertions(+), 18 deletions(-) diff --git a/examples/codex/databricks/README.md b/examples/codex/databricks/README.md index 8d7f79a3a3..35876ec68f 100644 --- a/examples/codex/databricks/README.md +++ b/examples/codex/databricks/README.md @@ -57,8 +57,8 @@ launcher starts `exec-server` on each session; it is killed when the sandbox stops and relaunched on the next session. To run the model through OpenAI directly instead of the Databricks AI Gateway, -set `OPENAI_BASE_URL`, `OPENAI_API_KEY`, and an OpenAI model id your account can -use: +set `OPENAI_BASE_URL` and `OPENAI_API_KEY` together (set both or neither), plus an +OpenAI model id your account can use: ```sh SANDBOX_NAME=my-sandbox DATABRICKS_CONFIG_PROFILE=my-workspace \ diff --git a/examples/codex/databricks/runner.py b/examples/codex/databricks/runner.py index 39c21352a2..2ef7e6387a 100644 --- a/examples/codex/databricks/runner.py +++ b/examples/codex/databricks/runner.py @@ -9,14 +9,15 @@ DATABRICKS_CONFIG_PROFILE .databrickscfg profile name (default: DEFAULT) SANDBOX_NAME sandbox id or ``sandboxes/`` resource name (required) SANDBOX_CWD remote workspace path (default: /home/sandbox-agent/work) - SANDBOX_CREATE "1" to provision the sandbox if absent (default: off) + SANDBOX_CREATE "1" to create the sandbox before running (default: off) SANDBOX_IMAGE image with the codex exec-server (used when creating) SANDBOX_INACTIVITY_TIMEOUT_S auto-stop timeout in seconds (default: 900) OPENAI_MODEL model name (default: gpt-5.5) - OPENAI_BASE_URL model-provider base URL (default: the workspace's - Databricks AI Gateway codex endpoint) - OPENAI_API_KEY model-provider key (default: a token minted from the - Databricks profile, so no OpenAI key is needed) + OPENAI_BASE_URL model-provider base URL, set together with + OPENAI_API_KEY (default: the Databricks AI Gateway + codex endpoint) + OPENAI_API_KEY model-provider key, set together with OPENAI_BASE_URL + (default: a token minted from the Databricks profile) With SANDBOX_CREATE=1 the runner provisions the sandbox. In all cases it then confirms the sandbox is running (starting it if stopped and polling until ready) @@ -28,8 +29,8 @@ By default the model runs through the sandbox workspace's Databricks AI Gateway codex endpoint, authenticated with the profile's own token (PAT or OAuth), so no -OpenAI key is required. Set OPENAI_BASE_URL / OPENAI_API_KEY to use a different -provider (for example OpenAI directly). +OpenAI key is required. To use a different provider (for example OpenAI directly), +set OPENAI_BASE_URL and OPENAI_API_KEY together; setting only one is rejected. Run: SANDBOX_NAME=my-sandbox DATABRICKS_CONFIG_PROFILE=my-workspace \ @@ -105,17 +106,21 @@ def _wait_until_running( def _model_credentials(workspace_client: WorkspaceClient) -> tuple[str, str]: """Return ``(base_url, api_key)`` for ``NativeProvider``. - Defaults to the workspace's Databricks AI Gateway codex endpoint, with a - token minted from the Databricks profile (PAT or OAuth) - no OpenAI key - needed. Override with OPENAI_BASE_URL / OPENAI_API_KEY for another provider. + With neither OPENAI_BASE_URL nor OPENAI_API_KEY set, defaults to the + workspace's Databricks AI Gateway codex endpoint with a token minted from the + Databricks profile (PAT or OAuth) - no OpenAI key needed. To use another + provider (for example OpenAI directly), set both. Setting only one is rejected + so a key is never sent to the wrong endpoint. """ - host = (workspace_client.config.host or "").rstrip("/") - base_url = os.getenv("OPENAI_BASE_URL") or f"{host}/ai-gateway/codex/v1" + base_url = os.getenv("OPENAI_BASE_URL") api_key = os.getenv("OPENAI_API_KEY") - if not api_key: - authorization = workspace_client.config.authenticate().get("Authorization", "") - api_key = authorization.removeprefix("Bearer ").strip() - return base_url, api_key + if bool(base_url) != bool(api_key): + raise ValueError("set OPENAI_BASE_URL and OPENAI_API_KEY together, or neither") + if base_url and api_key: + return base_url, api_key + host = (workspace_client.config.host or "").rstrip("/") + authorization = workspace_client.config.authenticate().get("Authorization", "") + return f"{host}/ai-gateway/codex/v1", authorization.removeprefix("Bearer ").strip() async def main(task: str) -> None: