diff --git a/examples/codex/databricks/README.md b/examples/codex/databricks/README.md new file mode 100644 index 0000000000..35876ec68f --- /dev/null +++ b/examples/codex/databricks/README.md @@ -0,0 +1,93 @@ +# Databricks sandbox executor + +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` 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. + +```sh +pip install -r examples/codex/databricks/requirements.txt +``` + +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=my-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. 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` 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 \ + 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" +``` + +## 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. +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. + +## 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. + +## 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/requirements.txt b/examples/codex/databricks/requirements.txt new file mode 100644 index 0000000000..a70ab2fb17 --- /dev/null +++ b/examples/codex/databricks/requirements.txt @@ -0,0 +1 @@ +databricks-sdk[sandbox]>=0.153.0 diff --git a/examples/codex/databricks/runner.py b/examples/codex/databricks/runner.py new file mode 100644 index 0000000000..2ef7e6387a --- /dev/null +++ b/examples/codex/databricks/runner.py @@ -0,0 +1,162 @@ +"""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 .databrickscfg profile) + +Environment variables: + 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 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, 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) +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 +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 \ + 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 agents.sandbox import DatabricksStdioEnvironment + + +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``. + + 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. + """ + base_url = os.getenv("OPENAI_BASE_URL") + api_key = os.getenv("OPENAI_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: + 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}"] + ) + + environment = DatabricksStdioEnvironment.for_sandbox( + workspace_client=workspace_client, + sandbox_name=sandbox_name, + cwd=cwd, + ) + 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__": + asyncio.run(main(" ".join(sys.argv[1:]) or "Inspect the assigned workspace")) 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/packages/codex/src/_agents_codex/_databricks.py b/packages/codex/src/_agents_codex/_databricks.py new file mode 100644 index 0000000000..8a716b9872 --- /dev/null +++ b/packages/codex/src/_agents_codex/_databricks.py @@ -0,0 +1,117 @@ +"""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 typing import Any + +from ._options import RuntimeEnvironment +from .executor import Environment, ExecutorToolName + +_DEFAULT_TOOLS: tuple[ExecutorToolName, ...] = ("exec_command", "write_stdin", "apply_patch") + +# 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) +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. + + 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 + ``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, "-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 new file mode 100644 index 0000000000..dca27b5124 --- /dev/null +++ b/packages/codex/src/_agents_codex/_databricks_launcher.py @@ -0,0 +1,153 @@ +"""Launcher the native runtime spawns to bridge executor stdio to a sandbox. + +: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, stderr and exit). + +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: + """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 _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 _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() + + def forward() -> None: + try: + _forward_stdout(process.stdout.readline, lambda line: os.write(1, line)) + finally: + done.set() + + 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, handler) + + 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") + token = os.environ.get("DATABRICKS_TOKEN") + if not host or not token: + print("launcher 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.PIPE, + ) + return _run(process) + + +if __name__ == "__main__": + sys.exit(main()) 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/packages/codex/tests/test_databricks_environment.py b/packages/codex/tests/test_databricks_environment.py new file mode 100644 index 0000000000..c9fffe72bd --- /dev/null +++ b/packages/codex/tests/test_databricks_environment.py @@ -0,0 +1,158 @@ +"""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, 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 + +from _agents_codex._databricks import _LAUNCHER_MODULE, DatabricksStdioEnvironment + + +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", "-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": ["-m", _LAUNCHER_MODULE, "sandboxes/sbx"], + "env": {"DATABRICKS_HOST": "https://h", "DATABRICKS_TOKEN": "t"}, + "cwd": None, + } + 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", "-m", _LAUNCHER_MODULE, "sandboxes/sbx"), + ) + + +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", "-m", _LAUNCHER_MODULE, "sandboxes/sbx"), + ) + + +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(fake_sandbox_state.SANDBOX_STATE_STOPPED), + sandbox_name="sbx", + cwd="/w", + ) + + +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(fake_sandbox_state.SANDBOX_STATE_RUNNING), + sandbox_name="sbx", + cwd="/home/sandbox-agent/work", + ) + 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") + 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", + } + + +def test_for_sandbox_accepts_resource_name(fake_sandbox_state: type[_FakeSandboxState]) -> None: + environment = DatabricksStdioEnvironment.for_sandbox( + 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 new file mode 100644 index 0000000000..3ce899f689 --- /dev/null +++ b/packages/codex/tests/test_databricks_launcher.py @@ -0,0 +1,214 @@ +"""Tests for the Databricks stdio launcher. + +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, + _pump_stdin, + _run, + _terminate, + 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 _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 _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: + self.closed = True + + def wait(self, timeout: float | None = None) -> int: + return self._exit_code + + +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"") + 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 + + +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" 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",