Compare commits

...
13 changed files with 1650 additions and 39 deletions

No files matched your search

+13
View File
@@ -152,6 +152,8 @@ attempt. API-key login completes synchronously and does not return a handle.
- `run(input: str | Input, *, approval_mode=None, cwd=None, effort=None, model=None, output_schema=None, personality=None, sandbox: Sandbox | None = None, service_tier=None, summary=None) -> TurnResult`
- `turn(input: str | Input, *, approval_mode=None, cwd=None, effort=None, model=None, output_schema=None, personality=None, sandbox: Sandbox | None = None, service_tier=None, summary=None) -> TurnHandle`
- `run_goal(objective: str) -> TurnResult`
- `start_goal(objective: str) -> TurnHandle`
- `read(*, include_turns: bool = False) -> ThreadReadResponse`
- `set_name(name: str) -> ThreadSetNameResponse`
- `compact() -> ThreadCompactStartResponse`
@@ -160,6 +162,8 @@ attempt. API-key login completes synchronously and does not return a handle.
- `run(input: str | Input, *, approval_mode=None, cwd=None, effort=None, model=None, output_schema=None, personality=None, sandbox: Sandbox | None = None, service_tier=None, summary=None) -> Awaitable[TurnResult]`
- `turn(input: str | Input, *, approval_mode=None, cwd=None, effort=None, model=None, output_schema=None, personality=None, sandbox: Sandbox | None = None, service_tier=None, summary=None) -> Awaitable[AsyncTurnHandle]`
- `run_goal(objective: str) -> Awaitable[TurnResult]`
- `start_goal(objective: str) -> Awaitable[AsyncTurnHandle]`
- `read(*, include_turns: bool = False) -> Awaitable[ThreadReadResponse]`
- `set_name(name: str) -> Awaitable[ThreadSetNameResponse]`
- `compact() -> Awaitable[ThreadCompactStartResponse]`
@@ -184,6 +188,15 @@ phase-less assistant message item.
Use `turn(...)` when you need low-level turn control (`stream()`, `steer()`,
`interrupt()`) before collecting the turn result.
Use `run_goal(...)` or `start_goal(...)` for an objective that can continue
through multiple internal turns. Goal operations require an idle, persisted
thread and use its existing configuration. Starting one replaces any stored
goal. Streaming, steering, interruption, and the returned `TurnResult` still
present one logical turn with one stable ID.
Closing a goal stream releases its SDK routing state. It does not pause the
persisted goal or stop work already running on the server.
## Sandbox
Use `sandbox=` consistently on thread lifecycle methods and turns:
+11
View File
@@ -72,6 +72,17 @@ with Codex() as codex:
Use `Thread.turn(...)` when you need a `TurnHandle` for streaming, steering,
or interrupting an active turn.
For a longer objective on an idle, persisted thread, run a dedicated goal
operation:
```python
result = thread.run_goal("Improve the benchmark coverage in this repository.")
```
A goal may continue working internally, but it streams and returns as one
logical turn. It uses the thread's existing configuration and replaces any
stored goal.
## 4. Choose Sandbox Access
Use one enum for the initial thread and later turn overrides:
@@ -0,0 +1,26 @@
import sys
from pathlib import Path
_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
if str(_EXAMPLES_ROOT) not in sys.path:
sys.path.insert(0, str(_EXAMPLES_ROOT))
from _bootstrap import ensure_local_sdk_src, runtime_config
ensure_local_sdk_src()
import asyncio
from openai_codex import AsyncCodex
async def main() -> None:
async with AsyncCodex(config=runtime_config()) as codex:
thread = await codex.thread_start()
goal = await thread.start_goal("Improve the benchmark coverage in this repository.")
result = await goal.run()
print(result.final_response)
if __name__ == "__main__":
asyncio.run(main())
+17
View File
@@ -0,0 +1,17 @@
import sys
from pathlib import Path
_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
if str(_EXAMPLES_ROOT) not in sys.path:
sys.path.insert(0, str(_EXAMPLES_ROOT))
from _bootstrap import ensure_local_sdk_src, runtime_config
ensure_local_sdk_src()
from openai_codex import Codex
with Codex(config=runtime_config()) as codex:
thread = codex.thread_start()
result = thread.run_goal("Improve the benchmark coverage in this repository.")
print(result.final_response)
+2
View File
@@ -89,3 +89,5 @@ python examples/01_quickstart_constructor/async.py
- separate `steer()` and `interrupt()` demos with concise summaries
- `15_login_and_account/`
- browser-login handle lifecycle, cancellation, and account inspection
- `16_goal_turns/`
- run a longer autonomous objective as one logical turn
+6 -1
View File
@@ -174,7 +174,12 @@ class _GoalOperationState:
"""Adopt a server-reported active id when routed state is still stale."""
with self._condition:
if self.current_turn_id in {None, expected}:
self.current_turn_id = active
if self.completed_turn is not None and self.completed_turn.id == active:
self.current_turn_id = None
if self.cleared or _terminal_goal_status(self.status):
self._finished = True
else:
self.current_turn_id = active
self._condition.notify_all()
def turn_for_interrupt(self) -> str | None:
+182
View File
@@ -0,0 +1,182 @@
import asyncio
from dataclasses import dataclass
from ._goal import (
_AsyncGoalNotificationStream,
_GoalNotificationStream,
_GoalOperationState,
)
from ._inputs import RunInput, _normalize_run_input, _to_wire_input
from .async_client import AsyncCodexClient
from .client import CodexClient, _active_turn_id_from_error
from .errors import InvalidRequestError
from .generated.v2_all import TurnInterruptResponse, TurnSteerResponse
def _inactive_turn_error() -> InvalidRequestError:
return InvalidRequestError(-32600, "no active turn to steer")
def _inactive_interrupt_error() -> InvalidRequestError:
return InvalidRequestError(-32600, "no active turn to interrupt")
@dataclass(slots=True)
class _GoalTurnHandleAdapter:
"""Implement synchronous turn controls for one logical goal operation."""
client: CodexClient
state: _GoalOperationState
thread_id: str
logical_turn_id: str
def steer(self, input: RunInput) -> TurnSteerResponse:
wire_input = _to_wire_input(_normalize_run_input(input))
turn_id = self.state.active_turn()
if turn_id is None:
raise _inactive_turn_error()
try:
response = self.client.turn_steer(self.thread_id, turn_id, wire_input)
except InvalidRequestError as exc:
if not (
exc.message == "no active turn to steer"
or exc.message.startswith("expected active turn id")
):
raise
next_turn_id = _active_turn_id_from_error(exc)
if next_turn_id is None:
next_turn_id = self.state.active_turn(after=turn_id)
if next_turn_id is None:
raise _inactive_turn_error() from exc
response = self.client.turn_steer(self.thread_id, next_turn_id, wire_input)
self.state.resolve_active_turn(turn_id, next_turn_id)
return response.model_copy(update={"turn_id": self.logical_turn_id})
def interrupt(self) -> TurnInterruptResponse:
if not self.state.begin_interrupt():
raise _inactive_interrupt_error()
try:
self.client.pause_goal(self.thread_id)
turn_id = self.state.turn_for_interrupt()
if turn_id is None:
response = TurnInterruptResponse()
else:
try:
response = self.client.turn_interrupt(self.thread_id, turn_id)
except InvalidRequestError as exc:
if exc.message == "no active turn to interrupt":
response = TurnInterruptResponse()
elif exc.message.startswith("expected active turn id"):
next_turn_id = _active_turn_id_from_error(exc) or self.state.current_turn()
if next_turn_id is None or next_turn_id == turn_id:
response = TurnInterruptResponse()
else:
try:
response = self.client.turn_interrupt(
self.thread_id,
next_turn_id,
)
except InvalidRequestError as retry_exc:
if retry_exc.message != "no active turn to interrupt":
raise
response = TurnInterruptResponse()
self.state.resolve_active_turn(turn_id, next_turn_id)
else:
raise
self.state.confirm_interrupt()
return response
except BaseException:
self.state.cancel_interrupt()
raise
def stream(self) -> _GoalNotificationStream:
return _GoalNotificationStream(
self.state,
lambda: self.client.next_goal_notification(self.state),
lambda: self.client.unregister_goal_operation(self.state),
lambda: self.client.cancel_goal_operation(self.state),
)
@dataclass(slots=True)
class _AsyncGoalTurnHandleAdapter:
"""Implement asynchronous turn controls for one logical goal operation."""
client: AsyncCodexClient
state: _GoalOperationState
thread_id: str
logical_turn_id: str
async def steer(self, input: RunInput) -> TurnSteerResponse:
wire_input = _to_wire_input(_normalize_run_input(input))
turn_id = await asyncio.to_thread(self.state.active_turn)
if turn_id is None:
raise _inactive_turn_error()
try:
response = await self.client.turn_steer(self.thread_id, turn_id, wire_input)
except InvalidRequestError as exc:
if not (
exc.message == "no active turn to steer"
or exc.message.startswith("expected active turn id")
):
raise
next_turn_id = _active_turn_id_from_error(exc)
if next_turn_id is None:
next_turn_id = await asyncio.to_thread(
self.state.active_turn,
after=turn_id,
)
if next_turn_id is None:
raise _inactive_turn_error() from exc
response = await self.client.turn_steer(
self.thread_id,
next_turn_id,
wire_input,
)
self.state.resolve_active_turn(turn_id, next_turn_id)
return response.model_copy(update={"turn_id": self.logical_turn_id})
async def interrupt(self) -> TurnInterruptResponse:
if not self.state.begin_interrupt():
raise _inactive_interrupt_error()
try:
await self.client.pause_goal(self.thread_id)
turn_id = self.state.turn_for_interrupt()
if turn_id is None:
response = TurnInterruptResponse()
else:
try:
response = await self.client.turn_interrupt(self.thread_id, turn_id)
except InvalidRequestError as exc:
if exc.message == "no active turn to interrupt":
response = TurnInterruptResponse()
elif exc.message.startswith("expected active turn id"):
next_turn_id = _active_turn_id_from_error(exc) or self.state.current_turn()
if next_turn_id is None or next_turn_id == turn_id:
response = TurnInterruptResponse()
else:
try:
response = await self.client.turn_interrupt(
self.thread_id,
next_turn_id,
)
except InvalidRequestError as retry_exc:
if retry_exc.message != "no active turn to interrupt":
raise
response = TurnInterruptResponse()
self.state.resolve_active_turn(turn_id, next_turn_id)
else:
raise
self.state.confirm_interrupt()
return response
except BaseException:
self.state.cancel_interrupt()
raise
def stream(self) -> _AsyncGoalNotificationStream:
return _AsyncGoalNotificationStream(
self.state,
lambda: self.client.next_goal_notification(self.state),
lambda: self.client.unregister_goal_operation(self.state),
lambda: self.client.cancel_goal_operation(self.state),
)
+116 -29
View File
@@ -1,7 +1,7 @@
from __future__ import annotations
import asyncio
from dataclasses import dataclass
from dataclasses import dataclass, field
from typing import AsyncIterator, Iterator
from ._approval_mode import (
@@ -9,6 +9,10 @@ from ._approval_mode import (
_approval_mode_override_settings,
_approval_mode_settings,
)
from ._goal_handle import (
_AsyncGoalTurnHandleAdapter,
_GoalTurnHandleAdapter,
)
from ._initialize_metadata import validate_initialize_metadata
from ._inputs import (
ImageInput as ImageInput,
@@ -71,6 +75,21 @@ from .generated.v2_all import (
)
from .models import InitializeResponse, JsonObject, Notification
_MAX_THREAD_GOAL_OBJECTIVE_CHARS = 4_000
def _normalize_goal_objective(objective: str) -> str:
if not isinstance(objective, str):
raise TypeError("goal objective must be a string")
objective = objective.strip()
if not objective:
raise ValueError("goal objective must not be empty")
if len(objective) > _MAX_THREAD_GOAL_OBJECTIVE_CHARS:
raise ValueError(
f"goal objective must be at most {_MAX_THREAD_GOAL_OBJECTIVE_CHARS} characters"
)
return objective
class Codex:
"""Synchronous client for creating threads and running Codex turns.
@@ -570,6 +589,10 @@ class Thread:
finally:
stream.close()
def run_goal(self, objective: str) -> TurnResult:
"""Run a persisted goal to completion as one logical turn."""
return self.start_goal(objective).run()
# BEGIN GENERATED: Thread.flat_methods
def turn(
self,
@@ -607,6 +630,19 @@ class Thread:
# END GENERATED: Thread.flat_methods
def start_goal(self, objective: str) -> TurnHandle:
"""Activate a persisted goal and return its logical turn handle."""
objective = _normalize_goal_objective(objective)
state, turn_id = self._client.start_goal_operation(self.id, objective)
handle = TurnHandle(self._client, self.id, turn_id)
handle._goal = _GoalTurnHandleAdapter(
client=self._client,
state=state,
thread_id=self.id,
logical_turn_id=turn_id,
)
return handle
def read(self, *, include_turns: bool = False) -> ThreadReadResponse:
"""Read this thread, optionally including its turn history."""
return self._client.thread_read(self.id, include_turns=include_turns)
@@ -658,6 +694,11 @@ class AsyncThread:
finally:
await stream.aclose()
async def run_goal(self, objective: str) -> TurnResult:
"""Run a persisted goal asynchronously as one logical turn."""
goal = await self.start_goal(objective)
return await goal.run()
# BEGIN GENERATED: AsyncThread.flat_methods
async def turn(
self,
@@ -700,6 +741,20 @@ class AsyncThread:
# END GENERATED: AsyncThread.flat_methods
async def start_goal(self, objective: str) -> AsyncTurnHandle:
"""Activate a persisted goal and return its async logical turn handle."""
objective = _normalize_goal_objective(objective)
await self._codex._ensure_initialized()
state, turn_id = await self._codex._client.start_goal_operation(self.id, objective)
handle = AsyncTurnHandle(self._codex, self.id, turn_id)
handle._goal = _AsyncGoalTurnHandleAdapter(
client=self._codex._client,
state=state,
thread_id=self.id,
logical_turn_id=turn_id,
)
return handle
async def read(self, *, include_turns: bool = False) -> ThreadReadResponse:
"""Read this thread, optionally including its turn history."""
await self._codex._ensure_initialized()
@@ -721,9 +776,17 @@ class TurnHandle:
_client: CodexClient
thread_id: str
id: str
_goal: _GoalTurnHandleAdapter | None = field(
default=None,
init=False,
repr=False,
compare=False,
)
def steer(self, input: RunInput) -> TurnSteerResponse:
"""Send additional input to this active turn."""
if self._goal is not None:
return self._goal.steer(input)
return self._client.turn_steer(
self.thread_id,
self.id,
@@ -732,23 +795,31 @@ class TurnHandle:
def interrupt(self) -> TurnInterruptResponse:
"""Request interruption of this active turn."""
if self._goal is not None:
return self._goal.interrupt()
return self._client.turn_interrupt(self.thread_id, self.id)
def stream(self) -> Iterator[Notification]:
"""Yield only notifications routed to this turn handle."""
self._client.register_turn_notifications(self.id)
try:
while True:
event = self._client.next_turn_notification(self.id)
yield event
if (
event.method == "turn/completed"
and isinstance(event.payload, TurnCompletedNotification)
and event.payload.turn.id == self.id
):
break
finally:
self._client.unregister_turn_notifications(self.id)
if self._goal is not None:
return self._goal.stream()
def notifications() -> Iterator[Notification]:
self._client.register_turn_notifications(self.id)
try:
while True:
event = self._client.next_turn_notification(self.id)
yield event
if (
event.method == "turn/completed"
and isinstance(event.payload, TurnCompletedNotification)
and event.payload.turn.id == self.id
):
break
finally:
self._client.unregister_turn_notifications(self.id)
return notifications()
def run(self) -> TurnResult:
"""Consume the turn stream and return its completed result."""
@@ -766,10 +837,18 @@ class AsyncTurnHandle:
_codex: AsyncCodex
thread_id: str
id: str
_goal: _AsyncGoalTurnHandleAdapter | None = field(
default=None,
init=False,
repr=False,
compare=False,
)
async def steer(self, input: RunInput) -> TurnSteerResponse:
"""Send additional input to this active turn."""
await self._codex._ensure_initialized()
if self._goal is not None:
return await self._goal.steer(input)
return await self._codex._client.turn_steer(
self.thread_id,
self.id,
@@ -779,24 +858,32 @@ class AsyncTurnHandle:
async def interrupt(self) -> TurnInterruptResponse:
"""Request interruption of this active turn."""
await self._codex._ensure_initialized()
if self._goal is not None:
return await self._goal.interrupt()
return await self._codex._client.turn_interrupt(self.thread_id, self.id)
async def stream(self) -> AsyncIterator[Notification]:
def stream(self) -> AsyncIterator[Notification]:
"""Yield only notifications routed to this async turn handle."""
await self._codex._ensure_initialized()
self._codex._client.register_turn_notifications(self.id)
try:
while True:
event = await self._codex._client.next_turn_notification(self.id)
yield event
if (
event.method == "turn/completed"
and isinstance(event.payload, TurnCompletedNotification)
and event.payload.turn.id == self.id
):
break
finally:
self._codex._client.unregister_turn_notifications(self.id)
if self._goal is not None:
return self._goal.stream()
async def notifications() -> AsyncIterator[Notification]:
await self._codex._ensure_initialized()
self._codex._client.register_turn_notifications(self.id)
try:
while True:
event = await self._codex._client.next_turn_notification(self.id)
yield event
if (
event.method == "turn/completed"
and isinstance(event.payload, TurnCompletedNotification)
and event.payload.turn.id == self.id
):
break
finally:
self._codex._client.unregister_turn_notifications(self.id)
return notifications()
async def run(self) -> TurnResult:
"""Consume the turn stream and return its completed result."""
+41 -9
View File
@@ -5,7 +5,7 @@ import queue
import shutil
import threading
import time
from dataclasses import dataclass
from dataclasses import dataclass, field
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path
from typing import Any
@@ -82,12 +82,26 @@ class CapturedResponsesRequest:
return self.headers.get(name.lower())
@dataclass(frozen=True)
class SseGate:
"""Hold an SSE response after its first event has been flushed."""
ready: threading.Event = field(default_factory=threading.Event)
release: threading.Event = field(default_factory=threading.Event)
def wait_until_ready(self, timeout_s: float = 5.0) -> None:
"""Wait until the response is active and held before its second event."""
if not self.ready.wait(timeout_s):
raise AssertionError("SSE response did not reach its gate")
@dataclass(frozen=True)
class MockSseResponse:
"""One queued SSE response served by the mock Responses API."""
body: str
delay_between_events_s: float = 0.0
gate: SseGate | None = None
def chunks(self) -> list[bytes]:
"""Split an SSE body into event chunks while preserving framing."""
@@ -137,12 +151,14 @@ class MockResponsesServer:
body: str,
*,
delay_between_events_s: float = 0.0,
gate: SseGate | None = None,
) -> None:
"""Queue one SSE body for the next `/v1/responses` request."""
"""Queue SSE, optionally holding after its first event until released."""
self._responses.put(
MockSseResponse(
body=body,
delay_between_events_s=delay_between_events_s,
gate=gate,
)
)
@@ -206,11 +222,18 @@ class MockResponsesServer:
class AppServerHarness:
"""Test fixture that points a pinned runtime app-server at MockResponsesServer."""
def __init__(self, tmp_path: Path, *, requires_openai_auth: bool = False) -> None:
def __init__(
self,
tmp_path: Path,
*,
requires_openai_auth: bool = False,
enable_goals: bool | None = None,
) -> None:
self.tmp_path = tmp_path
self.codex_home = tmp_path / "codex-home"
self.workspace = tmp_path / "workspace"
self.requires_openai_auth = requires_openai_auth
self.enable_goals = enable_goals
self.responses = MockResponsesServer()
def __enter__(self) -> AppServerHarness:
@@ -240,6 +263,9 @@ class AppServerHarness:
"""Write config.toml that routes model calls to the mock server."""
config_toml = self.codex_home / "config.toml"
requires_openai_auth = "requires_openai_auth = true\n" if self.requires_openai_auth else ""
goals = ""
if self.enable_goals is not None:
goals = f"[features]\ngoals = {str(self.enable_goals).lower()}\n\n"
config_toml.write_text(
f"""
model = "mock-model"
@@ -248,7 +274,7 @@ sandbox_mode = "read-only"
model_provider = "mock_provider"
[model_providers.mock_provider]
{goals}[model_providers.mock_provider]
name = "Mock provider for Python SDK tests"
base_url = "{self.responses.url}/v1"
wire_api = "responses"
@@ -319,9 +345,15 @@ class _ResponsesHandler(BaseHTTPRequestHandler):
self.send_response(200)
self.send_header("content-type", "text/event-stream")
self.end_headers()
for chunk in response.chunks():
self.wfile.write(chunk)
self.wfile.flush()
for index, chunk in enumerate(response.chunks()):
try:
self.wfile.write(chunk)
self.wfile.flush()
except (BrokenPipeError, ConnectionResetError):
return
if index == 0 and response.gate is not None:
response.gate.ready.set()
response.gate.release.wait()
if response.delay_between_events_s:
time.sleep(response.delay_between_events_s)
@@ -440,12 +472,12 @@ def ev_function_call(call_id: str, name: str, arguments: str) -> Json:
}
def ev_failed(response_id: str, message: str) -> Json:
def ev_failed(response_id: str, message: str, *, code: str = "server_error") -> Json:
"""Return a failed model response event."""
return {
"type": "response.failed",
"response": {
"id": response_id,
"error": {"code": "server_error", "message": message},
"error": {"code": code, "message": message},
},
}
@@ -0,0 +1,487 @@
import _thread
import asyncio
import threading
import time
import pytest
from app_server_harness import AppServerHarness, SseGate, ev_failed, ev_response_created, sse
from app_server_helpers import streaming_response
from openai_codex import AsyncCodex, Codex
from openai_codex.api import _MAX_THREAD_GOAL_OBJECTIVE_CHARS
from openai_codex.errors import InvalidRequestError, TransportClosedError
from openai_codex.generated.v2_all import (
IdleThreadStatus,
ThreadGoalGetResponse,
ThreadGoalStatus,
TurnStatus,
)
def _queued_notification(state):
notifications = state._notifications
with notifications.not_empty:
if not notifications.not_empty.wait_for(lambda: bool(notifications.queue), timeout=5):
raise AssertionError("goal notification was not queued")
return notifications.queue[0]
def _wait_until_consumed(state, marker) -> None:
notifications = state._notifications
with notifications.not_full:
if not notifications.not_full.wait_for(
lambda: all(item is not marker for item in notifications.queue),
timeout=5,
):
raise AssertionError("goal stream did not begin collecting")
def test_terminal_goal_failure_preserves_status_and_releases_routing(tmp_path) -> None:
"""A failed server turn should stop rollover work and leave the thread usable."""
with AppServerHarness(tmp_path) as harness:
harness.responses.enqueue_sse(
sse(
[
ev_response_created("goal-terminal-failure"),
ev_failed(
"goal-terminal-failure",
"goal model failed",
code="insufficient_quota",
),
]
)
)
with Codex(config=harness.app_server_config()) as codex:
thread = codex.thread_start()
with pytest.raises(RuntimeError) as error:
thread.run_goal("Fail this goal turn")
persisted = codex._client.request(
"thread/goal/get",
{"threadId": thread.id},
response_model=ThreadGoalGetResponse,
).goal
harness.responses.enqueue_assistant_message(
"Recovered with an ordinary turn.",
response_id="goal-failure-follow-up",
)
follow_up = thread.run("Run after the goal failure")
harness.responses.wait_for_requests(2)
requests = harness.responses.requests()
assert {
"error": str(error.value),
"goal_status": persisted.status if persisted else None,
"follow_up": (follow_up.status, follow_up.final_response),
"request_count": len(requests),
"follow_up_input": requests[1].message_input_texts("user")[-1:],
} == {
"error": "Quota exceeded. Check your plan and billing details.",
"goal_status": ThreadGoalStatus.usage_limited,
"follow_up": (TurnStatus.completed, "Recovered with an ordinary turn."),
"request_count": 2,
"follow_up_input": ["Run after the goal failure"],
}
def test_sync_goal_run_cancellation_stops_work_and_releases_routing(tmp_path) -> None:
"""Keyboard interruption should pause and interrupt a running logical goal."""
with AppServerHarness(tmp_path) as harness:
work_gate = SseGate()
harness.responses.enqueue_sse(
streaming_response(
"cancelled-sync-run",
"msg-cancelled-sync-run",
["cancelled ", "sync ", "goal"],
),
delay_between_events_s=0.5,
gate=work_gate,
)
harness.responses.enqueue_assistant_message(
"Sync follow-up complete.",
response_id="cancelled-sync-run-follow-up",
)
with Codex(config=harness.app_server_config()) as codex:
try:
thread = codex.thread_start()
turn = thread.start_goal("Cancel this running sync goal")
goal = turn._goal
assert goal is not None
goal_state = goal.state
work_gate.wait_until_ready()
marker = _queued_notification(goal_state)
worker_errors: list[BaseException] = []
def interrupt_when_collecting() -> None:
try:
_wait_until_consumed(goal_state, marker)
except BaseException as exc:
worker_errors.append(exc)
finally:
_thread.interrupt_main()
work_gate.release.set()
interrupter = threading.Thread(target=interrupt_when_collecting)
try:
with pytest.raises(KeyboardInterrupt):
interrupter.start()
turn.run()
finally:
interrupter.join()
finally:
work_gate.release.set()
deadline = time.monotonic() + 5
while True:
current = thread.read()
if isinstance(current.thread.status.root, IdleThreadStatus):
break
if time.monotonic() >= deadline:
raise AssertionError("cancelled sync goal turn did not stop")
time.sleep(0.01)
persisted = codex._client.request(
"thread/goal/get",
{"threadId": thread.id},
response_model=ThreadGoalGetResponse,
).goal
registered_goals = dict(codex._client._router._goal_operations)
follow_up = thread.run("Continue after cancelling the sync goal")
requests = harness.responses.wait_for_requests(2)
assert {
"goal_status": persisted.status if persisted else None,
"follow_up": (follow_up.status, follow_up.final_response),
"request_count": len(requests),
"registered_goals": registered_goals,
"interrupter_errors": [str(error) for error in worker_errors],
} == {
"goal_status": ThreadGoalStatus.paused,
"follow_up": (TurnStatus.completed, "Sync follow-up complete."),
"request_count": 2,
"registered_goals": {},
"interrupter_errors": [],
}
def test_closing_goal_stream_releases_real_process_routing(tmp_path) -> None:
"""Closing a stream should release SDK routing without pausing the persisted goal."""
with AppServerHarness(tmp_path) as harness:
work_gate = SseGate()
harness.responses.enqueue_sse(
streaming_response(
"stream-close",
"msg-stream-close",
["long ", "running ", "goal"],
),
delay_between_events_s=0.5,
gate=work_gate,
)
with Codex(config=harness.app_server_config()) as codex:
try:
thread = codex.thread_start()
turn = thread.start_goal("Close this goal stream")
work_gate.wait_until_ready()
stream = turn.stream()
stream.close()
registered_goals = dict(codex._client._router._goal_operations)
persisted = codex._client.request(
"thread/goal/get",
{"threadId": thread.id},
response_model=ThreadGoalGetResponse,
).goal
finally:
work_gate.release.set()
assert {
"registered_goals": registered_goals,
"persisted_status": persisted.status if persisted else None,
} == {
"registered_goals": {},
"persisted_status": ThreadGoalStatus.active,
}
def test_app_server_exit_unblocks_goal_stream_and_releases_routing(tmp_path) -> None:
"""A real transport death should wake the logical reader and clean up routing."""
with AppServerHarness(tmp_path) as harness:
work_gate = SseGate()
harness.responses.enqueue_sse(
streaming_response(
"transport-exit",
"msg-transport-exit",
["long ", "running ", "goal"],
),
delay_between_events_s=0.5,
gate=work_gate,
)
with Codex(config=harness.app_server_config()) as codex:
try:
turn = codex.thread_start().start_goal("Stop the app-server during this goal")
work_gate.wait_until_ready()
process = codex._client._proc
assert process is not None
process.terminate()
process.wait(timeout=5)
finally:
work_gate.release.set()
with pytest.raises(TransportClosedError):
turn.run()
registered_goals = dict(codex._client._router._goal_operations)
assert registered_goals == {}
def test_failed_goal_starts_release_routing_without_model_requests(tmp_path) -> None:
"""Validation failures should leave the client and persisted thread usable."""
with AppServerHarness(tmp_path) as harness:
harness.responses.enqueue_assistant_message(
"Ordinary turn complete.",
response_id="validation-follow-up",
)
with Codex(config=harness.app_server_config()) as codex:
thread = codex.thread_start()
with pytest.raises(ValueError) as empty_error:
thread.start_goal(" ")
with pytest.raises(TypeError) as type_error:
thread.start_goal(123) # type: ignore[arg-type]
with pytest.raises(ValueError) as long_error:
thread.start_goal("x" * (_MAX_THREAD_GOAL_OBJECTIVE_CHARS + 1))
ephemeral = codex.thread_start(ephemeral=True)
with pytest.raises(InvalidRequestError) as ephemeral_error:
ephemeral.start_goal("Persist this goal")
follow_up = thread.run("Run after rejected goals")
requests = harness.responses.wait_for_requests(1)
registered_goals = dict(codex._client._router._goal_operations)
assert {
"errors": [
str(empty_error.value),
str(type_error.value),
str(long_error.value),
ephemeral_error.value.message,
],
"follow_up": (follow_up.status, follow_up.final_response),
"request_count": len(requests),
"registered_goals": registered_goals,
} == {
"errors": [
"goal objective must not be empty",
"goal objective must be a string",
"goal objective must be at most 4000 characters",
f"thread must be persisted before starting a goal: {ephemeral.id}",
],
"follow_up": (TurnStatus.completed, "Ordinary turn complete."),
"request_count": 1,
"registered_goals": {},
}
def test_disabled_goals_fail_before_model_work_or_routing(tmp_path) -> None:
"""A runtime with goals disabled should reject startup without leaking state."""
with AppServerHarness(tmp_path, enable_goals=False) as harness:
with Codex(config=harness.app_server_config()) as codex:
thread = codex.thread_start()
with pytest.raises(InvalidRequestError) as error:
thread.start_goal("This goal must not start")
registered_goals = dict(codex._client._router._goal_operations)
requests = harness.responses.requests()
assert {
"error": error.value.message,
"registered_goals": registered_goals,
"request_count": len(requests),
} == {
"error": "goals feature is disabled",
"registered_goals": {},
"request_count": 0,
}
def test_active_thread_rejects_goal_start_and_keeps_ordinary_turn_usable(tmp_path) -> None:
"""Goal startup should require an idle thread without disturbing active work."""
with AppServerHarness(tmp_path) as harness:
work_gate = SseGate()
harness.responses.enqueue_sse(
streaming_response(
"active-ordinary-turn",
"msg-active-ordinary-turn",
["ordinary ", "work"],
),
delay_between_events_s=0.5,
gate=work_gate,
)
with Codex(config=harness.app_server_config()) as codex:
try:
thread = codex.thread_start()
ordinary = thread.turn("Keep this ordinary turn active")
work_gate.wait_until_ready()
with pytest.raises(InvalidRequestError) as error:
thread.start_goal("Do not replace active work")
ordinary.interrupt()
finally:
work_gate.release.set()
result = ordinary.run()
registered_goals = dict(codex._client._router._goal_operations)
assert {
"error": error.value.message,
"ordinary_result": (result.id, result.status),
"registered_goals": registered_goals,
} == {
"error": f"thread must be idle before starting a goal: {thread.id}",
"ordinary_result": (ordinary.id, TurnStatus.interrupted),
"registered_goals": {},
}
def test_async_goal_run_cancellation_stops_work_and_releases_routing(tmp_path) -> None:
"""Task cancellation should pause and interrupt a running logical goal."""
async def scenario() -> None:
with AppServerHarness(tmp_path) as harness:
work_gate = SseGate()
harness.responses.enqueue_sse(
streaming_response(
"cancelled-async-run",
"msg-cancelled-async-run",
["cancelled ", "async ", "goal"],
),
delay_between_events_s=0.5,
gate=work_gate,
)
harness.responses.enqueue_assistant_message(
"Async run follow-up complete.",
response_id="cancelled-async-run-follow-up",
)
async with AsyncCodex(config=harness.app_server_config()) as codex:
try:
thread = await codex.thread_start()
turn = await thread.start_goal("Cancel this running async goal")
goal = turn._goal
assert goal is not None
goal_state = goal.state
marker = _queued_notification(goal_state)
running = asyncio.create_task(turn.run())
await asyncio.to_thread(work_gate.wait_until_ready)
await asyncio.to_thread(_wait_until_consumed, goal_state, marker)
running.cancel()
with pytest.raises(asyncio.CancelledError):
await running
finally:
work_gate.release.set()
deadline = time.monotonic() + 5
while True:
current = await thread.read()
if isinstance(current.thread.status.root, IdleThreadStatus):
break
if time.monotonic() >= deadline:
raise AssertionError("cancelled async goal turn did not stop")
await asyncio.sleep(0.01)
persisted = await codex._client.request(
"thread/goal/get",
{"threadId": thread.id},
response_model=ThreadGoalGetResponse,
)
registered_goals = dict(codex._client._sync._router._goal_operations)
follow_up = await thread.run("Continue after cancelling the async goal")
requests = await asyncio.to_thread(harness.responses.wait_for_requests, 2)
assert {
"goal_status": persisted.goal.status if persisted.goal else None,
"follow_up": (follow_up.status, follow_up.final_response),
"request_count": len(requests),
"registered_goals": registered_goals,
} == {
"goal_status": ThreadGoalStatus.paused,
"follow_up": (TurnStatus.completed, "Async run follow-up complete."),
"request_count": 2,
"registered_goals": {},
}
asyncio.run(scenario())
def test_async_goal_start_cancellation_interrupts_work_and_releases_routing(tmp_path) -> None:
"""Cancelling startup should pause and interrupt the physical goal turn."""
async def scenario() -> None:
with AppServerHarness(tmp_path) as harness:
work_gate = SseGate()
harness.responses.enqueue_sse(
streaming_response(
"cancelled-start",
"msg-cancelled-start",
["cancelled ", "goal ", "work"],
),
delay_between_events_s=0.5,
gate=work_gate,
)
harness.responses.enqueue_assistant_message(
"Async follow-up complete.",
response_id="cancelled-start-follow-up",
)
async with AsyncCodex(config=harness.app_server_config()) as codex:
try:
thread = await codex.thread_start()
startup = asyncio.create_task(
thread.start_goal("Cancel this goal during startup")
)
await asyncio.sleep(0)
work_gate.wait_until_ready()
startup.cancel()
with pytest.raises(asyncio.CancelledError):
await asyncio.wait_for(startup, timeout=1)
finally:
work_gate.release.set()
router = codex._client._sync._router
deadline = time.monotonic() + 5
while True:
current = await thread.read()
with router._lock:
registered_goals = dict(router._goal_operations)
if (
isinstance(current.thread.status.root, IdleThreadStatus)
and not registered_goals
):
break
if time.monotonic() >= deadline:
raise AssertionError("cancelled goal startup did not stop")
await asyncio.sleep(0.01)
persisted = await codex._client.request(
"thread/goal/get",
{"threadId": thread.id},
response_model=ThreadGoalGetResponse,
)
follow_up = await thread.run("Continue after cancelled goal startup")
requests = harness.responses.wait_for_requests(2)
assert {
"goal_status": persisted.goal.status if persisted.goal else None,
"follow_up": (follow_up.status, follow_up.final_response),
"request_count": len(requests),
"registered_goals": registered_goals,
"thread_status": current.thread.status.root,
} == {
"goal_status": ThreadGoalStatus.paused,
"follow_up": (TurnStatus.completed, "Async follow-up complete."),
"request_count": 2,
"registered_goals": {},
"thread_status": IdleThreadStatus(type="idle"),
}
asyncio.run(scenario())
@@ -0,0 +1,317 @@
import asyncio
import time
import pytest
from app_server_harness import (
AppServerHarness,
SseGate,
ev_completed_with_usage,
ev_function_call,
ev_response_created,
sse,
)
from app_server_helpers import agent_message_texts_from_items, streaming_response
from openai_codex import AsyncCodex, Codex
from openai_codex.generated.v2_all import (
ThreadGoalGetResponse,
ThreadGoalStatus,
TurnStatus,
)
def _enqueue_steerable_goal(
harness: AppServerHarness,
prefix: str,
*,
initial_text: str,
continuation_chunks: list[str],
final_text: str,
) -> SseGate:
continuation_gate = SseGate()
harness.responses.enqueue_assistant_message(
initial_text,
response_id=f"{prefix}-initial",
)
harness.responses.enqueue_sse(
streaming_response(
f"{prefix}-continuation",
f"msg-{prefix}-continuation",
continuation_chunks,
),
delay_between_events_s=0.15,
gate=continuation_gate,
)
harness.responses.enqueue_sse(
sse(
[
ev_response_created(f"{prefix}-complete-tool"),
ev_function_call(
f"call-{prefix}-complete",
"update_goal",
'{"status":"complete"}',
),
ev_completed_with_usage(
f"{prefix}-complete-tool",
input_tokens=1,
cached_input_tokens=0,
output_tokens=1,
reasoning_output_tokens=0,
total_tokens=2,
),
]
)
)
harness.responses.enqueue_assistant_message(
final_text,
response_id=f"{prefix}-final",
)
return continuation_gate
def _enqueue_interruptible_goal(
harness: AppServerHarness,
prefix: str,
*,
initial_text: str,
continuation_chunks: list[str],
follow_up_text: str,
) -> SseGate:
continuation_gate = SseGate()
harness.responses.enqueue_assistant_message(
initial_text,
response_id=f"{prefix}-initial",
)
harness.responses.enqueue_sse(
streaming_response(
f"{prefix}-continuation",
f"msg-{prefix}-continuation",
continuation_chunks,
),
delay_between_events_s=0.2,
gate=continuation_gate,
)
harness.responses.enqueue_assistant_message(
follow_up_text,
response_id=f"{prefix}-follow-up",
)
return continuation_gate
def _stale_routed_turn_id(turn) -> None:
goal = turn._goal
assert goal is not None
goal_state = goal.state
deadline = time.monotonic() + 5
with goal_state._condition:
while goal_state.current_turn_id in {None, turn.id}:
remaining = deadline - time.monotonic()
if remaining <= 0:
raise AssertionError("continuation turn was not routed")
goal_state._condition.wait(remaining)
goal_state.current_turn_id = turn.id
def test_goal_steer_targets_an_active_continuation(tmp_path) -> None:
"""Steering should reach the active server turn while returning the logical ID."""
with AppServerHarness(tmp_path) as harness:
continuation_gate = _enqueue_steerable_goal(
harness,
"steer",
initial_text="Initial work complete.",
continuation_chunks=["continuation ", "work"],
final_text="Steered goal complete.",
)
with Codex(config=harness.app_server_config()) as codex:
try:
turn = codex.thread_start().start_goal("Start a goal that needs refinement")
continuation_gate.wait_until_ready()
steer = turn.steer("Prioritize the edge-case coverage.")
finally:
continuation_gate.release.set()
result = turn.run()
requests = harness.responses.wait_for_requests(4)
assert {
"steer_id": steer.turn_id,
"result": (result.id, result.status, result.final_response),
"messages": agent_message_texts_from_items(result.items),
"steering_input": requests[2].message_input_texts("user")[-1:],
} == {
"steer_id": turn.id,
"result": (turn.id, TurnStatus.completed, "Steered goal complete."),
"messages": [
"Initial work complete.",
"continuation work",
"Steered goal complete.",
],
"steering_input": ["Prioritize the edge-case coverage."],
}
def test_goal_steer_retries_the_server_reported_rollover_turn(tmp_path) -> None:
"""Steering should recover when routed state trails the server continuation."""
with AppServerHarness(tmp_path) as harness:
continuation_gate = _enqueue_steerable_goal(
harness,
"steer-rollover",
initial_text="Initial rollover work complete.",
continuation_chunks=["rollover ", "work"],
final_text="Rollover steering complete.",
)
with Codex(config=harness.app_server_config()) as codex:
try:
turn = codex.thread_start().start_goal("Steer while routing catches up")
continuation_gate.wait_until_ready()
_stale_routed_turn_id(turn)
steer = turn.steer("Steer through the rollover window.")
finally:
continuation_gate.release.set()
result = turn.run()
requests = harness.responses.wait_for_requests(4)
assert {
"steer_id": steer.turn_id,
"result": (result.id, result.status, result.final_response),
"steering_input": requests[2].message_input_texts("user")[-1:],
} == {
"steer_id": turn.id,
"result": (turn.id, TurnStatus.completed, "Rollover steering complete."),
"steering_input": ["Steer through the rollover window."],
}
@pytest.mark.parametrize("stale_route", [False, True])
def test_goal_interrupts_active_and_stale_routed_continuations(tmp_path, stale_route) -> None:
"""Interruption should stop active work despite notification rollover lag."""
with AppServerHarness(tmp_path) as harness:
continuation_gate = _enqueue_interruptible_goal(
harness,
"interrupt",
initial_text="Initial work complete.",
continuation_chunks=["still ", "working"],
follow_up_text="Ordinary follow-up complete.",
)
with Codex(config=harness.app_server_config()) as codex:
try:
thread = codex.thread_start()
turn = thread.start_goal("Start interruptible goal work")
continuation_gate.wait_until_ready()
if stale_route:
_stale_routed_turn_id(turn)
interrupt = turn.interrupt()
finally:
continuation_gate.release.set()
interrupted = turn.run()
follow_up = thread.run("Continue with an ordinary turn")
requests = harness.responses.wait_for_requests(3)
persisted = codex._client.request(
"thread/goal/get",
{"threadId": thread.id},
response_model=ThreadGoalGetResponse,
).goal
assert {
"interrupt": interrupt.model_dump(by_alias=True, mode="json"),
"goal_status": persisted.status if persisted else None,
"interrupted": (interrupted.id, interrupted.status),
"follow_up": (follow_up.status, follow_up.final_response),
"request_count": len(requests),
} == {
"interrupt": {},
"goal_status": ThreadGoalStatus.paused,
"interrupted": (turn.id, TurnStatus.interrupted),
"follow_up": (TurnStatus.completed, "Ordinary follow-up complete."),
"request_count": 3,
}
def test_async_goal_steer_retries_the_server_reported_rollover_turn(tmp_path) -> None:
"""Async steering should recover when routed state trails the continuation."""
async def scenario() -> None:
with AppServerHarness(tmp_path) as harness:
continuation_gate = _enqueue_steerable_goal(
harness,
"async-steer",
initial_text="Async initial work complete.",
continuation_chunks=["async continuation ", "work"],
final_text="Async steered goal complete.",
)
async with AsyncCodex(config=harness.app_server_config()) as codex:
try:
thread = await codex.thread_start()
turn = await thread.start_goal("Start an async goal that needs refinement")
await asyncio.to_thread(continuation_gate.wait_until_ready)
await asyncio.to_thread(_stale_routed_turn_id, turn)
steer = await turn.steer("Prioritize async edge-case coverage.")
finally:
continuation_gate.release.set()
result = await turn.run()
requests = await asyncio.to_thread(harness.responses.wait_for_requests, 4)
assert {
"steer_id": steer.turn_id,
"result": (result.id, result.status, result.final_response),
"messages": agent_message_texts_from_items(result.items),
"steering_input": requests[2].message_input_texts("user")[-1:],
} == {
"steer_id": turn.id,
"result": (turn.id, TurnStatus.completed, "Async steered goal complete."),
"messages": [
"Async initial work complete.",
"async continuation work",
"Async steered goal complete.",
],
"steering_input": ["Prioritize async edge-case coverage."],
}
asyncio.run(scenario())
def test_async_goal_interrupt_retries_the_server_reported_rollover_turn(tmp_path) -> None:
"""Async interruption should survive notification lag during rollover."""
async def scenario() -> None:
with AppServerHarness(tmp_path) as harness:
continuation_gate = _enqueue_interruptible_goal(
harness,
"async-interrupt",
initial_text="Async initial work complete.",
continuation_chunks=["async still ", "working"],
follow_up_text="Async ordinary follow-up complete.",
)
async with AsyncCodex(config=harness.app_server_config()) as codex:
try:
thread = await codex.thread_start()
turn = await thread.start_goal("Start async interruptible goal work")
await asyncio.to_thread(continuation_gate.wait_until_ready)
await asyncio.to_thread(_stale_routed_turn_id, turn)
interrupt = await turn.interrupt()
finally:
continuation_gate.release.set()
interrupted = await turn.run()
follow_up = await thread.run("Continue with an async ordinary turn")
await asyncio.to_thread(harness.responses.wait_for_requests, 3)
requests = harness.responses.requests()
assert {
"interrupt": interrupt.model_dump(by_alias=True, mode="json"),
"interrupted": (interrupted.id, interrupted.status),
"follow_up": (follow_up.status, follow_up.final_response),
"request_count": len(requests),
"follow_up_input": requests[2].message_input_texts("user")[-1:],
} == {
"interrupt": {},
"interrupted": (turn.id, TurnStatus.interrupted),
"follow_up": (TurnStatus.completed, "Async ordinary follow-up complete."),
"request_count": 3,
"follow_up_input": ["Continue with an async ordinary turn"],
}
asyncio.run(scenario())
@@ -0,0 +1,389 @@
import asyncio
import pytest
from app_server_harness import (
AppServerHarness,
ev_assistant_message,
ev_completed_with_usage,
ev_function_call,
ev_response_created,
sse,
)
from app_server_helpers import (
agent_message_texts,
agent_message_texts_from_items,
streaming_response,
)
from openai_codex import AsyncCodex, Codex
from openai_codex.api import _MAX_THREAD_GOAL_OBJECTIVE_CHARS
from openai_codex.errors import InvalidRequestError
from openai_codex.generated.notification_registry import notification_turn_id
from openai_codex.generated.v2_all import (
AgentMessageDeltaNotification,
ThreadGoalGetResponse,
ThreadGoalStatus,
TurnCompletedNotification,
TurnStatus,
)
def _enqueue_completed_goal(
harness: AppServerHarness,
prefix: str,
*,
initial_text: str,
final_text: str,
) -> None:
harness.responses.enqueue_sse(
sse(
[
ev_response_created(f"{prefix}-initial"),
ev_assistant_message(f"msg-{prefix}-initial", initial_text),
ev_completed_with_usage(
f"{prefix}-initial",
input_tokens=3,
cached_input_tokens=1,
output_tokens=2,
reasoning_output_tokens=1,
total_tokens=5,
),
]
)
)
harness.responses.enqueue_sse(
sse(
[
ev_response_created(f"{prefix}-complete-tool"),
ev_function_call(
f"call-{prefix}-complete",
"update_goal",
'{"status":"complete"}',
),
ev_completed_with_usage(
f"{prefix}-complete-tool",
input_tokens=4,
cached_input_tokens=1,
output_tokens=1,
reasoning_output_tokens=1,
total_tokens=5,
),
]
)
)
harness.responses.enqueue_sse(
sse(
[
ev_response_created(f"{prefix}-final"),
ev_assistant_message(f"msg-{prefix}-final", final_text),
ev_completed_with_usage(
f"{prefix}-final",
input_tokens=5,
cached_input_tokens=0,
output_tokens=3,
reasoning_output_tokens=0,
total_tokens=8,
),
]
)
)
def _continuation_text(request) -> str:
return "\n".join(request.message_input_texts("user"))
def test_sync_goal_run_aggregates_automatic_continuation(tmp_path) -> None:
"""The public result should cover the initial and automatic continuation turns."""
with AppServerHarness(tmp_path) as harness:
_enqueue_completed_goal(
harness,
"sync-run",
initial_text="Initial pass complete.",
final_text="Goal complete.",
)
with Codex(config=harness.app_server_config()) as codex:
thread = codex.thread_start()
result = thread.run_goal(" Improve benchmark coverage ")
requests = harness.responses.wait_for_requests(3)
registered_goals = dict(codex._client._router._goal_operations)
usage = result.usage.model_dump(by_alias=True, mode="json") if result.usage else None
assert {
"id_is_present": bool(result.id),
"status": result.status,
"messages": agent_message_texts_from_items(result.items),
"final_response": result.final_response,
"usage": usage,
"timing": (
result.started_at is not None,
result.completed_at is not None,
result.duration_ms == max(0, result.completed_at - result.started_at) * 1000
if result.started_at is not None and result.completed_at is not None
else False,
),
"continuation_has_objective": "<objective>\nImprove benchmark coverage\n</objective>"
in _continuation_text(requests[0]),
"registered_goals": registered_goals,
} == {
"id_is_present": True,
"status": TurnStatus.completed,
"messages": ["Initial pass complete.", "Goal complete."],
"final_response": "Goal complete.",
"usage": {
"last": {
"cachedInputTokens": 0,
"inputTokens": 5,
"outputTokens": 3,
"reasoningOutputTokens": 0,
"totalTokens": 8,
},
"modelContextWindow": 258_400,
"total": {
"cachedInputTokens": 2,
"inputTokens": 12,
"outputTokens": 6,
"reasoningOutputTokens": 2,
"totalTokens": 18,
},
},
"timing": (True, True, True),
"continuation_has_objective": True,
"registered_goals": {},
}
def test_goal_stream_exposes_one_logical_lifecycle(tmp_path) -> None:
"""Continuation boundaries should not leak through the public stream."""
with AppServerHarness(tmp_path) as harness:
harness.responses.enqueue_sse(
streaming_response(
"stream-initial",
"msg-stream-initial",
["initial ", "pass"],
)
)
harness.responses.enqueue_sse(
sse(
[
ev_response_created("stream-complete-tool"),
ev_function_call(
"call-stream-complete",
"update_goal",
'{"status":"complete"}',
),
ev_completed_with_usage(
"stream-complete-tool",
input_tokens=1,
cached_input_tokens=0,
output_tokens=1,
reasoning_output_tokens=0,
total_tokens=2,
),
]
)
)
harness.responses.enqueue_sse(
streaming_response(
"stream-final",
"msg-stream-final",
["goal ", "complete"],
)
)
with Codex(config=harness.app_server_config()) as codex:
turn = codex.thread_start().start_goal("Finish the integration suite")
events = list(turn.stream())
lifecycle = [event for event in events if event.method in {"turn/started", "turn/completed"}]
routed_ids = [
turn_id for event in events if (turn_id := notification_turn_id(event.payload)) is not None
]
assert {
"lifecycle": [event.method for event in lifecycle],
"routed_ids": sorted(set(routed_ids)),
"deltas": [
event.payload.delta
for event in events
if isinstance(event.payload, AgentMessageDeltaNotification)
],
"messages": agent_message_texts(events),
"completion_statuses": [
event.payload.turn.status
for event in events
if isinstance(event.payload, TurnCompletedNotification)
],
} == {
"lifecycle": ["turn/started", "turn/completed"],
"routed_ids": [turn.id],
"deltas": ["initial ", "pass", "goal ", "complete"],
"messages": ["initial pass", "goal complete"],
"completion_statuses": [TurnStatus.completed],
}
def test_goal_can_complete_within_the_initial_server_turn(tmp_path) -> None:
"""Completing the goal before turn end should not create a continuation turn."""
with AppServerHarness(tmp_path) as harness:
harness.responses.enqueue_sse(
sse(
[
ev_response_created("single-turn-complete-tool"),
ev_function_call(
"call-single-turn-complete",
"update_goal",
'{"status":"complete"}',
),
ev_completed_with_usage(
"single-turn-complete-tool",
input_tokens=1,
cached_input_tokens=0,
output_tokens=1,
reasoning_output_tokens=0,
total_tokens=2,
),
]
)
)
harness.responses.enqueue_assistant_message(
"Completed without a continuation.",
response_id="single-turn-final",
)
with Codex(config=harness.app_server_config()) as codex:
turn = codex.thread_start().start_goal("Finish in the initial turn")
result = turn.run()
requests = harness.responses.wait_for_requests(2)
with pytest.raises(InvalidRequestError) as steer_error:
turn.steer("Keep working")
with pytest.raises(InvalidRequestError) as interrupt_error:
turn.interrupt()
assert {
"result": (result.id, result.status, result.final_response),
"messages": agent_message_texts_from_items(result.items),
"request_count": len(requests),
"inactive_errors": [steer_error.value.message, interrupt_error.value.message],
} == {
"result": (turn.id, TurnStatus.completed, "Completed without a continuation."),
"messages": ["Completed without a continuation."],
"request_count": 2,
"inactive_errors": ["no active turn to steer", "no active turn to interrupt"],
}
def test_goal_replaces_an_existing_persisted_goal(tmp_path) -> None:
"""Goal mode should replace a resumable persisted goal before model work begins."""
with AppServerHarness(tmp_path) as harness:
_enqueue_completed_goal(
harness,
"replacement",
initial_text="Replacement started.",
final_text="Replacement complete.",
)
with Codex(config=harness.app_server_config()) as codex:
thread = codex.thread_start()
previous = codex._client.thread_goal_set(
thread.id,
objective="Keep the old benchmark objective",
status=ThreadGoalStatus.paused,
).goal
result = thread.run_goal("Publish the replacement objective")
persisted = codex._client.request(
"thread/goal/get",
{"threadId": thread.id},
response_model=ThreadGoalGetResponse,
).goal
requests = harness.responses.wait_for_requests(3)
assert {
"previous": (previous.objective, previous.status),
"result": (result.status, result.final_response),
"persisted": (
persisted.objective if persisted else None,
persisted.status if persisted else None,
persisted.token_budget if persisted else None,
),
"continuation_has_replacement": (
"Publish the replacement objective" in _continuation_text(requests[0])
),
"continuation_has_previous": (
"Keep the old benchmark objective" in _continuation_text(requests[0])
),
} == {
"previous": ("Keep the old benchmark objective", ThreadGoalStatus.paused),
"result": (TurnStatus.completed, "Replacement complete."),
"persisted": (
"Publish the replacement objective",
ThreadGoalStatus.complete,
None,
),
"continuation_has_replacement": True,
"continuation_has_previous": False,
}
def test_goal_length_validation_preserves_an_existing_goal(tmp_path) -> None:
"""An invalid replacement should fail before clearing the stored goal."""
with AppServerHarness(tmp_path) as harness:
with Codex(config=harness.app_server_config()) as codex:
thread = codex.thread_start()
previous = codex._client.thread_goal_set(
thread.id,
objective="Keep the existing objective",
status=ThreadGoalStatus.paused,
).goal
with pytest.raises(ValueError) as error:
thread.start_goal("x" * (_MAX_THREAD_GOAL_OBJECTIVE_CHARS + 1))
persisted = codex._client.request(
"thread/goal/get",
{"threadId": thread.id},
response_model=ThreadGoalGetResponse,
).goal
requests = harness.responses.requests()
assert {
"error": str(error.value),
"persisted": persisted,
"model_requests": requests,
} == {
"error": "goal objective must be at most 4000 characters",
"persisted": previous,
"model_requests": [],
}
def test_async_goal_run_matches_sync_logical_result(tmp_path) -> None:
"""The async public API should aggregate the same real continuation lifecycle."""
async def scenario() -> None:
with AppServerHarness(tmp_path) as harness:
_enqueue_completed_goal(
harness,
"async-run",
initial_text="Async initial pass.",
final_text="Async goal complete.",
)
async with AsyncCodex(config=harness.app_server_config()) as codex:
thread = await codex.thread_start()
result = await thread.run_goal("Finish the async goal")
requests = harness.responses.wait_for_requests(3)
assert {
"status": result.status,
"messages": agent_message_texts_from_items(result.items),
"final_response": result.final_response,
"continuation_has_objective": (
"Finish the async goal" in _continuation_text(requests[0])
),
} == {
"status": TurnStatus.completed,
"messages": ["Async initial pass.", "Async goal complete."],
"final_response": "Async goal complete.",
"continuation_has_objective": True,
}
asyncio.run(scenario())
@@ -185,6 +185,45 @@ def test_turn_input_methods_accept_string_shortcut() -> None:
)
def test_dedicated_goal_operations_have_pythonic_signatures() -> None:
"""Goal operations should accept only an objective and return existing turn types."""
goal_methods = {
Thread.run_goal: "TurnResult",
Thread.start_goal: "TurnHandle",
AsyncThread.run_goal: "TurnResult",
AsyncThread.start_goal: "AsyncTurnHandle",
}
ordinary_methods = [Thread.run, Thread.turn, AsyncThread.run, AsyncThread.turn]
assert {
"goal_methods": {
fn: (
list(inspect.signature(fn).parameters),
inspect.signature(fn).parameters["objective"].annotation,
inspect.signature(fn).return_annotation,
)
for fn in goal_methods
},
"ordinary_goal_parameter": {
fn: "goal" in inspect.signature(fn).parameters for fn in ordinary_methods
},
"handle_constructors": {
handle: list(inspect.signature(handle).parameters)
for handle in (TurnHandle, AsyncTurnHandle)
},
} == {
"goal_methods": {
fn: (["self", "objective"], "str", return_type)
for fn, return_type in goal_methods.items()
},
"ordinary_goal_parameter": dict.fromkeys(ordinary_methods, False),
"handle_constructors": {
TurnHandle: ["_client", "thread_id", "id"],
AsyncTurnHandle: ["_codex", "thread_id", "id"],
},
}
def test_root_exports_approval_mode() -> None:
"""The root package should expose the high-level approval mode enum."""
assert [(mode.name, mode.value) for mode in ApprovalMode] == [
@@ -228,6 +267,10 @@ def test_curated_public_api_has_builtin_help_documentation() -> None:
"thread_resume": Codex.thread_resume,
"thread_run": Thread.run,
"thread_turn": Thread.turn,
"thread_run_goal": Thread.run_goal,
"thread_start_goal": Thread.start_goal,
"async_thread_run_goal": AsyncThread.run_goal,
"async_thread_start_goal": AsyncThread.start_goal,
}
assert {name: inspect.getdoc(value) is not None for name, value in documented.items()} == (