diff --git a/examples/codex/databricks/README.md b/examples/codex/databricks/README.md new file mode 100644 index 0000000000..a9ff35bbf2 --- /dev/null +++ b/examples/codex/databricks/README.md @@ -0,0 +1,169 @@ +# 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/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` (reached with +> `_UCODE_DISPATCH_ACTIVE=1`, the ucode wrapper's internal recursion sentinel - +> see the prerequisites note). `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. +> - **Static checks.** `pytest tests/codex` (13 passed) and `mypy --strict` run +> against the preview wheel on a glibc-2.39 host. +> - **Plain-wrapper banner filter (2026-11-16).** With the bypass disabled +> (`exec_server_env={}`), a live turn ran through the plain `codex` wrapper: the +> gateway dropped the wrapper's 9-line launch banner from stdout and the tool +> still executed (`proof_pw.txt` created), so the `_UCODE_DISPATCH_ACTIVE` +> bypass is now optional. + +## 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 the image +wrapper's human launch banner (the non-JSON lines that can precede the first +protocol frame on stdout) so it never reaches the SDK as a bogus message (see +the ucode-wrapper note under Prerequisites). + +`databricks_sandbox_environment` (`environment.py`) starts that gateway for an +existing sandbox 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). Install it, then this +example's requirements: + +```sh +pip install "" # see docs/sdk/installation.md +pip install -r examples/codex/databricks/requirements.txt +``` + +Provide Databricks auth (a CLI profile) and a model-provider key, then run from +the repo root: + +```sh +SANDBOX_NAME=openai-agent-sandbox OPENAI_API_KEY=... \ + PYTHONPATH=. python -m examples.codex.databricks.runner "Inspect the workspace" +``` + +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. + +## 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. **exec-server stdio mode in the image - SUPPORTED.** The image's real codex + (`/usr/local/libexec/codex-package/bin/codex`, reached with + `_UCODE_DISPATCH_ACTIVE=1`) runs the standalone exec-server over stdio with + `exec-server --listen stdio`. `stdio` is a `--listen` transport value + (`ws://IP:PORT` default, `stdio`, `stdio://`), not a subcommand - + `exec-server stdio` errors. (The exec-server also offers a native + `--listen ws://` mode with built-in `--ws-auth`; not used here since + `Environment` requires wss/TLS, which the loopback gateway terminates.) + + > **Note - launching past the ucode wrapper.** On the image, `codex` is a + > Databricks "ucode" self-healing wrapper that re-dispatches through + > `ucode codex` and prints a launch banner to stdout. Two ways to reach a clean + > exec-server: (1) the default sets `_UCODE_DISPATCH_ACTIVE=1`, the wrapper's + > internal recursion sentinel, so it execs the real binary directly + > (deterministic, but an internal, feature-flag-gated detail - not a documented + > interface, and may change); or (2) run the plain wrapper (`exec_server_env={}`) + > and let the gateway's banner filter drop the preamble - validated end-to-end + > on 2026-11-16 (the tool executed and the 9-line banner was dropped). The CLIs + > expose no quiet/no-banner flag (`ucode` / `ug` / `codex --help`). The cleanest + > long-term fix is Databricks-side: have the wrapper pass `exec-server` through + > (it is infrastructure that needs no model routing), or send its banner to + > stderr. Confirm a supported launch with the Databricks sandbox team before + > production. +2. **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. +3. **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, bearer auth, teardown paths, the context manager, and the +`SSL_CERT_FILE` trust-bundle helper with a fake `CommandProcess`. Run them from +the repo root with the preview wheel and this example's requirements installed +(validated: 13 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 `tests/native_executor_fixtures.py` and +`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..42e60ca260 --- /dev/null +++ b/examples/codex/databricks/environment.py @@ -0,0 +1,184 @@ +"""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 itself (``WorkspaceClient.sandbox.create_sandbox``) and +ensuring the ``codex`` exec-server is present are left to the caller. See +``runner.py`` and the example README for the create/ensure 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, running sandbox with the exec-server available. + 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: Environment for the exec-server command. Defaults to + ``{"_UCODE_DISPATCH_ACTIVE": "1"}``, the sandbox image's ucode-wrapper + recursion sentinel (an internal detail; see ``gateway.py``); pass + ``{}`` to run unmodified. + 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. + """ + 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 _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..6f07df7f99 --- /dev/null +++ b/examples/codex/databricks/gateway.py @@ -0,0 +1,289 @@ +"""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") + +# `codex exec-server --listen stdio` runs the standalone exec-server over stdio +# (``stdio`` is a --listen transport value, not a subcommand). The sandbox image +# ships `codex` as a Databricks "ucode" wrapper that re-dispatches through +# `ucode codex`, injecting profile/settings this integration does not need (the +# agent loop and model calls run in the controller, not the sandbox). +# `_UCODE_DISPATCH_ACTIVE=1` is that wrapper's internal recursion sentinel: +# setting it makes the wrapper exec the real codex binary directly instead of +# re-dispatching. This is an internal detail of the image, not a documented or +# supported interface - confirm a supported way to launch the exec-server with +# the Databricks sandbox team before relying on it in production. +_DEFAULT_EXEC_SERVER_COMMAND: tuple[str, ...] = ("codex", "exec-server", "--listen", "stdio") +_DEFAULT_EXEC_SERVER_ENV: dict[str, str] = {"_UCODE_DISPATCH_ACTIVE": "1"} + +# 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: Environment for the exec-server command. Defaults to + ``{"_UCODE_DISPATCH_ACTIVE": "1"}``, the image's ucode-wrapper + recursion sentinel (an internal detail; see the module docstring). + Pass ``{}`` to run the command unmodified. + 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 dict(_DEFAULT_EXEC_SERVER_ENV) + ) + 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, so every real + # message is an object whose first non-space byte is '{'. When codex runs + # through the image's ucode wrapper it prints a human launch banner + # (box-drawing characters and status checkmarks) to stdout before the real + # exec-server takes over; those lines would corrupt the stream as bogus + # protocol frames. Drop that non-JSON preamble, then forward every line + # once the protocol starts. This is a no-op when the exec-server is reached + # without the wrapper (raw binary or _UCODE_DISPATCH_ACTIVE), whose first + # line is already JSON. + 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..f46246ee16 --- /dev/null +++ b/examples/codex/databricks/runner.py @@ -0,0 +1,89 @@ +"""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) and model-provider auth + +Environment variables: + DATABRICKS_CONFIG_PROFILE Databricks CLI profile (default: DEFAULT) + SANDBOX_NAME target sandbox name/id (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_API_KEY model-provider key for NativeProvider (required) + OPENAI_BASE_URL optional model-provider base URL + OPENAI_MODEL model name (default: gpt-5.5) + +With SANDBOX_CREATE=1 the runner provisions the sandbox, then hands its name to +``databricks_sandbox_environment``. The gateway launches ``exec-server stdio`` on +each connection, so no separate exec-server start is needed here; a sandbox that +auto-stops is relaunched on the next connection. + +Run: + PYTHONPATH=. python -m examples.codex.databricks.runner "Inspect the project and list next steps" +""" + +import asyncio +import os +import sys + +from databricks.sdk import WorkspaceClient + +from agents import Agent, NativeProvider +from examples.codex.databricks.environment import databricks_sandbox_environment + + +def _ensure_sandbox(workspace_client: WorkspaceClient, sandbox_name: str) -> None: + """Provision ``sandbox_name`` if it does not already exist. + + 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) + workspace_client.sandbox.create_sandbox(Sandbox(spec=spec), sandbox_id=sandbox_name) + + +async def main(task: str) -> None: + workspace_client = WorkspaceClient(profile=os.getenv("DATABRICKS_CONFIG_PROFILE", "DEFAULT")) + sandbox_name = os.environ["SANDBOX_NAME"] + if os.getenv("SANDBOX_CREATE") == "1": + _ensure_sandbox(workspace_client, sandbox_name) + + async with databricks_sandbox_environment( + workspace_client=workspace_client, + sandbox_name=sandbox_name, + cwd=os.getenv("SANDBOX_CWD", "/home/sandbox-agent/work"), + ) as environment: + async with NativeProvider( + base_url=os.getenv("OPENAI_BASE_URL"), + api_key=os.environ["OPENAI_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..7a68039544 --- /dev/null +++ b/tests/codex/test_databricks_environment.py @@ -0,0 +1,217 @@ +"""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 typing import TYPE_CHECKING, cast + +import pytest + +pytest.importorskip("websockets") +pytest.importorskip("cryptography") +pytest.importorskip("certifi") + +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) -> None: + self._proc = proc + + 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) -> None: + self.sandbox = _FakeSandbox(proc) + + +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..23d0550ba9 --- /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] == {"_UCODE_DISPATCH_ACTIVE": "1"} + + +async def test_drops_ucode_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 ucode wrapper prints a launch 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()