mirror of
https://github.com/pchuan98/codex.git
synced 2026-07-01 00:31:56 +08:00
Ahmed Ibrahim
b1cbf622ad
## Why
The Python SDK currently exposes sandbox selection differently depending
on where it is used: thread lifecycle methods accept `SandboxMode`,
while turns accept the lower-level `SandboxPolicy` shape. For the common
case of choosing an access level, that leaks app-server wire details
into otherwise straightforward SDK usage.
This makes the common path explicit and discoverable: callers choose a
named sandbox preset once, using the same keyword on threads and turns.
The preset name `workspace_write` also makes the granted capability
clear at the callsite.
## What changed
- Added a root-level `Sandbox` enum with documented presets:
- `Sandbox.read_only`: read files without allowing writes.
- `Sandbox.workspace_write`: the normal default for projects with a
recorded trust decision; read files and write inside the workspace and
configured writable roots.
- `Sandbox.full_access`: run without filesystem access restrictions.
- Documented that omitting `sandbox=` delegates to app-server's
configured default, while explicit turn overrides remain sticky for
subsequent turns.
- Updated sync and async thread lifecycle and turn APIs to consistently
accept `sandbox=Sandbox...`, translating to the existing app-server
thread and turn representations internally.
- Updated the public API artifact generator so regenerated SDK wrappers
retain the friendly enum shape.
- Replaced low-level policy construction in Python docs, examples, and
the walkthrough notebook with the preset API.
- Added focused coverage for root exports, method signatures,
preset-to-wire mapping, and rejection of raw string sandbox inputs.
## API impact
High-level turn calls now use `sandbox=` instead of `sandbox_policy=`:
```python
from openai_codex import Codex, Sandbox
with Codex() as codex:
thread = codex.thread_start(sandbox=Sandbox.workspace_write)
result = thread.run("Review the diff only.", sandbox=Sandbox.read_only)
```
`thread_start(...)` already defaults to `ApprovalMode.auto_review`, so
normal writable usage is concise:
```python
with Codex() as codex:
thread = codex.thread_start(sandbox=Sandbox.workspace_write)
thread.run("Update the files in this workspace.")
```
With that combination, edits inside `cwd` and configured writable roots
run within the workspace-write sandbox. Operations that require
approval, such as edits outside those roots, are routed through auto
review. When `sandbox=` is omitted, app-server resolves its configured
default. A sandbox supplied to `run(...)` or `turn(...)` applies to that
turn and subsequent turns.
## Test coverage
- `sdk/python/tests/test_public_api_signatures.py` covers the public
export and parameter names, including the default approval mode.
- `sdk/python/tests/test_public_api_runtime_behavior.py` covers preset
mappings to the existing wire types and raw string rejection.
79 lines
2.4 KiB
Python
79 lines
2.4 KiB
Python
from __future__ import annotations
|
|
|
|
from enum import Enum
|
|
from typing import NoReturn
|
|
|
|
from .generated.v2_all import (
|
|
DangerFullAccessSandboxPolicy,
|
|
ReadOnlySandboxPolicy,
|
|
SandboxMode,
|
|
SandboxPolicy,
|
|
WorkspaceWriteSandboxPolicy,
|
|
)
|
|
|
|
|
|
class Sandbox(str, Enum):
|
|
"""Preset filesystem access levels for threads and turns.
|
|
|
|
`read_only` allows file reads without writes. `workspace_write` is the
|
|
normal default for projects with a recorded trust decision and allows
|
|
writes inside the workspace and configured writable roots. `full_access`
|
|
removes filesystem access restrictions.
|
|
"""
|
|
|
|
read_only = "read-only"
|
|
workspace_write = "workspace-write"
|
|
full_access = "full-access"
|
|
|
|
|
|
def _require_sandbox(sandbox: Sandbox) -> None:
|
|
if isinstance(sandbox, Sandbox):
|
|
return
|
|
options = ", ".join(f"Sandbox.{value.name}" for value in Sandbox)
|
|
raise ValueError(f"sandbox must be one of: {options}")
|
|
|
|
|
|
def _sandbox_mode(sandbox: Sandbox | None) -> SandboxMode | None:
|
|
"""Translate a public preset to the thread lifecycle wire mode."""
|
|
if sandbox is None:
|
|
return None
|
|
_require_sandbox(sandbox)
|
|
|
|
match sandbox:
|
|
case Sandbox.read_only:
|
|
return SandboxMode.read_only
|
|
case Sandbox.workspace_write:
|
|
return SandboxMode.workspace_write
|
|
case Sandbox.full_access:
|
|
return SandboxMode.danger_full_access
|
|
case _:
|
|
return _assert_never_sandbox(sandbox)
|
|
|
|
|
|
def _sandbox_policy(sandbox: Sandbox | None) -> SandboxPolicy | None:
|
|
"""Translate a public preset to the turn override wire policy."""
|
|
if sandbox is None:
|
|
return None
|
|
_require_sandbox(sandbox)
|
|
|
|
match sandbox:
|
|
case Sandbox.read_only:
|
|
return SandboxPolicy(
|
|
root=ReadOnlySandboxPolicy(type="readOnly"),
|
|
)
|
|
case Sandbox.workspace_write:
|
|
return SandboxPolicy(
|
|
root=WorkspaceWriteSandboxPolicy(type="workspaceWrite"),
|
|
)
|
|
case Sandbox.full_access:
|
|
return SandboxPolicy(
|
|
root=DangerFullAccessSandboxPolicy(type="dangerFullAccess"),
|
|
)
|
|
case _:
|
|
return _assert_never_sandbox(sandbox)
|
|
|
|
|
|
def _assert_never_sandbox(sandbox: NoReturn) -> NoReturn:
|
|
"""Make sandbox mapping exhaustive for static type checkers."""
|
|
raise AssertionError(f"Unhandled sandbox: {sandbox!r}")
|