circle-codex 0.154.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
openai_codex/_login.py ADDED
@@ -0,0 +1,172 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass
4
+ from typing import Protocol
5
+
6
+ from .async_client import AsyncCodexClient
7
+ from .client import CodexClient
8
+ from .generated.v2_all import (
9
+ AccountLoginCompletedNotification,
10
+ CancelLoginAccountResponse,
11
+ ChatgptDeviceCodeLoginAccountParams,
12
+ ChatgptDeviceCodeLoginAccountResponse,
13
+ ChatgptLoginAccountParams,
14
+ ChatgptLoginAccountResponse,
15
+ LoginAccountParams,
16
+ )
17
+
18
+
19
+ class _AsyncLoginOwner(Protocol):
20
+ """Subset of AsyncCodex needed by async login handles."""
21
+
22
+ _client: AsyncCodexClient
23
+
24
+ async def _ensure_initialized(self) -> None:
25
+ """Ensure the owning SDK client has a live Codex connection."""
26
+ ...
27
+
28
+
29
+ def start_chatgpt_login(client: CodexClient) -> ChatgptLoginHandle:
30
+ """Start browser ChatGPT login and return the handle for that attempt."""
31
+ response = client.account_login_start(
32
+ LoginAccountParams(
33
+ root=ChatgptLoginAccountParams(type="chatgpt"),
34
+ )
35
+ )
36
+ response_root = response.root
37
+ if not isinstance(response_root, ChatgptLoginAccountResponse):
38
+ raise RuntimeError(f"unexpected ChatGPT login response: {response_root!r}")
39
+ return ChatgptLoginHandle(
40
+ client,
41
+ response_root.login_id,
42
+ response_root.auth_url,
43
+ )
44
+
45
+
46
+ async def async_start_chatgpt_login(owner: _AsyncLoginOwner) -> AsyncChatgptLoginHandle:
47
+ """Start async browser ChatGPT login and return that attempt's handle."""
48
+ response = await owner._client.account_login_start(
49
+ LoginAccountParams(
50
+ root=ChatgptLoginAccountParams(type="chatgpt"),
51
+ )
52
+ )
53
+ response_root = response.root
54
+ if not isinstance(response_root, ChatgptLoginAccountResponse):
55
+ raise RuntimeError(f"unexpected ChatGPT login response: {response_root!r}")
56
+ return AsyncChatgptLoginHandle(
57
+ owner,
58
+ response_root.login_id,
59
+ response_root.auth_url,
60
+ )
61
+
62
+
63
+ def start_device_code_login(client: CodexClient) -> DeviceCodeLoginHandle:
64
+ """Start device-code ChatGPT login and return the handle for that attempt."""
65
+ response = client.account_login_start(
66
+ LoginAccountParams(
67
+ root=ChatgptDeviceCodeLoginAccountParams(type="chatgptDeviceCode"),
68
+ )
69
+ )
70
+ response_root = response.root
71
+ if not isinstance(response_root, ChatgptDeviceCodeLoginAccountResponse):
72
+ raise RuntimeError(f"unexpected device-code login response: {response_root!r}")
73
+ return DeviceCodeLoginHandle(
74
+ client,
75
+ response_root.login_id,
76
+ response_root.verification_url,
77
+ response_root.user_code,
78
+ )
79
+
80
+
81
+ async def async_start_device_code_login(
82
+ owner: _AsyncLoginOwner,
83
+ ) -> AsyncDeviceCodeLoginHandle:
84
+ """Start async device-code ChatGPT login and return that attempt's handle."""
85
+ response = await owner._client.account_login_start(
86
+ LoginAccountParams(
87
+ root=ChatgptDeviceCodeLoginAccountParams(type="chatgptDeviceCode"),
88
+ )
89
+ )
90
+ response_root = response.root
91
+ if not isinstance(response_root, ChatgptDeviceCodeLoginAccountResponse):
92
+ raise RuntimeError(f"unexpected device-code login response: {response_root!r}")
93
+ return AsyncDeviceCodeLoginHandle(
94
+ owner,
95
+ response_root.login_id,
96
+ response_root.verification_url,
97
+ response_root.user_code,
98
+ )
99
+
100
+
101
+ @dataclass(slots=True)
102
+ class ChatgptLoginHandle:
103
+ """Live browser-login attempt returned by `Codex.login_chatgpt()`."""
104
+
105
+ _client: CodexClient
106
+ login_id: str
107
+ auth_url: str
108
+
109
+ def wait(self) -> AccountLoginCompletedNotification:
110
+ """Wait for this browser login attempt's completion notification."""
111
+ return self._client.wait_for_login_completed(self.login_id)
112
+
113
+ def cancel(self) -> CancelLoginAccountResponse:
114
+ """Cancel this browser login attempt."""
115
+ return self._client.account_login_cancel(self.login_id)
116
+
117
+
118
+ @dataclass(slots=True)
119
+ class DeviceCodeLoginHandle:
120
+ """Live device-code login attempt returned by `Codex.login_chatgpt_device_code()`."""
121
+
122
+ _client: CodexClient
123
+ login_id: str
124
+ verification_url: str
125
+ user_code: str
126
+
127
+ def wait(self) -> AccountLoginCompletedNotification:
128
+ """Wait for this device-code login attempt's completion notification."""
129
+ return self._client.wait_for_login_completed(self.login_id)
130
+
131
+ def cancel(self) -> CancelLoginAccountResponse:
132
+ """Cancel this device-code login attempt."""
133
+ return self._client.account_login_cancel(self.login_id)
134
+
135
+
136
+ @dataclass(slots=True)
137
+ class AsyncChatgptLoginHandle:
138
+ """Live browser-login attempt returned by `AsyncCodex.login_chatgpt()`."""
139
+
140
+ _codex: _AsyncLoginOwner
141
+ login_id: str
142
+ auth_url: str
143
+
144
+ async def wait(self) -> AccountLoginCompletedNotification:
145
+ """Wait for this browser login attempt's completion notification."""
146
+ await self._codex._ensure_initialized()
147
+ return await self._codex._client.wait_for_login_completed(self.login_id)
148
+
149
+ async def cancel(self) -> CancelLoginAccountResponse:
150
+ """Cancel this browser login attempt."""
151
+ await self._codex._ensure_initialized()
152
+ return await self._codex._client.account_login_cancel(self.login_id)
153
+
154
+
155
+ @dataclass(slots=True)
156
+ class AsyncDeviceCodeLoginHandle:
157
+ """Live device-code attempt returned by `AsyncCodex.login_chatgpt_device_code()`."""
158
+
159
+ _codex: _AsyncLoginOwner
160
+ login_id: str
161
+ verification_url: str
162
+ user_code: str
163
+
164
+ async def wait(self) -> AccountLoginCompletedNotification:
165
+ """Wait for this device-code login attempt's completion notification."""
166
+ await self._codex._ensure_initialized()
167
+ return await self._codex._client.wait_for_login_completed(self.login_id)
168
+
169
+ async def cancel(self) -> CancelLoginAccountResponse:
170
+ """Cancel this device-code login attempt."""
171
+ await self._codex._ensure_initialized()
172
+ return await self._codex._client.account_login_cancel(self.login_id)
@@ -0,0 +1,389 @@
1
+ from __future__ import annotations
2
+
3
+ import queue
4
+ import threading
5
+ import weakref
6
+ from collections import deque
7
+ from contextlib import contextmanager
8
+ from dataclasses import dataclass, field
9
+ from typing import Iterator
10
+
11
+ from ._goal import _GoalOperationState
12
+ from .errors import CodexError, TransportClosedError, map_jsonrpc_error
13
+ from .generated.notification_registry import notification_turn_id
14
+ from .generated.v2_all import AccountLoginCompletedNotification
15
+ from .models import JsonValue, Notification, UnknownNotification
16
+
17
+ ResponseQueueItem = JsonValue | BaseException
18
+ NotificationQueueItem = Notification | BaseException
19
+
20
+
21
+ @dataclass
22
+ class _TurnState:
23
+ id: str
24
+ thread_id: str | None = None
25
+ events: dict[int, NotificationQueueItem] = field(default_factory=dict)
26
+ first_event: int = 0
27
+ next_event: int = 0
28
+ subscribers: dict[object, int] = field(default_factory=dict)
29
+ completed: bool = False
30
+
31
+
32
+ class _TurnSubscription:
33
+ """One consumer's cursor over shared unread events."""
34
+
35
+ def __init__(self, router: MessageRouter, state: _TurnState, cursor: int) -> None:
36
+ self._router = router
37
+ self._state = state
38
+ self._cursor = cursor
39
+ self._token = object()
40
+ state.subscribers[self._token] = self._cursor
41
+ self._closed = False
42
+ self._release = weakref.finalize(
43
+ self, router._release_turn, weakref.ref(router), state, self._token
44
+ )
45
+
46
+ def next(self) -> Notification:
47
+ with self._router._turn_condition:
48
+ while self._cursor == self._state.next_event and not self._closed:
49
+ if self._state.completed:
50
+ raise TransportClosedError("Turn is no longer streaming")
51
+ self._router._turn_condition.wait()
52
+ if self._closed:
53
+ raise TransportClosedError("Turn subscription closed")
54
+ item = self._state.events[self._cursor]
55
+ self._cursor += 1
56
+ self._state.subscribers[self._token] = self._cursor
57
+ self._router._prune_turn_events(self._state)
58
+ if isinstance(item, BaseException):
59
+ raise item
60
+ return item
61
+
62
+ def close(self) -> None:
63
+ with self._router._turn_condition:
64
+ self._closed = True
65
+ self._router._turn_condition.notify_all()
66
+ self._release()
67
+
68
+
69
+ class MessageRouter:
70
+ """Route reader-thread messages to the SDK operation waiting for them.
71
+
72
+ The app-server stdio transport is a single ordered stream, so only the
73
+ reader thread should consume stdout. This router keeps the rest of the SDK
74
+ from competing for that stream by giving each in-flight JSON-RPC request
75
+ its own queue and each turn consumer its own event cursor.
76
+ """
77
+
78
+ def __init__(self) -> None:
79
+ """Create empty response, turn, and global notification queues."""
80
+ # GC can release abandoned subscriptions during another routing operation.
81
+ self._lock = threading.RLock()
82
+ self._response_waiters: dict[str, queue.Queue[ResponseQueueItem]] = {}
83
+ self._login_notifications: dict[str, queue.Queue[NotificationQueueItem]] = {}
84
+ self._pending_login_notifications: dict[str, deque[Notification]] = {}
85
+ self._turn_condition = threading.Condition(self._lock)
86
+ self._turn_states: dict[str, _TurnState] = {}
87
+ self._turn_notifications: dict[str, _TurnSubscription] = {}
88
+ self._pending_turn_requests: dict[str, BaseException | None] = {}
89
+ self._goal_operations: dict[str, _GoalOperationState] = {}
90
+ self._global_notifications: queue.Queue[NotificationQueueItem] = queue.Queue()
91
+
92
+ def create_response_waiter(self, request_id: str) -> queue.Queue[ResponseQueueItem]:
93
+ """Register a one-shot queue for a JSON-RPC response id."""
94
+
95
+ waiter: queue.Queue[ResponseQueueItem] = queue.Queue(maxsize=1)
96
+ with self._lock:
97
+ self._response_waiters[request_id] = waiter
98
+ return waiter
99
+
100
+ def discard_response_waiter(self, request_id: str) -> None:
101
+ """Remove a response waiter when the request could not be written."""
102
+
103
+ with self._lock:
104
+ self._response_waiters.pop(request_id, None)
105
+
106
+ def next_global_notification(self) -> Notification:
107
+ """Block until the next notification that is not scoped to a turn."""
108
+
109
+ item = self._global_notifications.get()
110
+ if isinstance(item, BaseException):
111
+ raise item
112
+ return item
113
+
114
+ def register_login(self, login_id: str) -> None:
115
+ """Register a queue for one interactive login attempt."""
116
+
117
+ login_queue: queue.Queue[NotificationQueueItem] = queue.Queue()
118
+ with self._lock:
119
+ if login_id in self._login_notifications:
120
+ return
121
+ pending = self._pending_login_notifications.pop(login_id, deque())
122
+ self._login_notifications[login_id] = login_queue
123
+ for notification in pending:
124
+ login_queue.put(notification)
125
+
126
+ def unregister_login(self, login_id: str) -> None:
127
+ """Stop routing future notifications for one login attempt."""
128
+
129
+ with self._lock:
130
+ self._login_notifications.pop(login_id, None)
131
+
132
+ def next_login_notification(self, login_id: str) -> Notification:
133
+ """Block until the next notification for a registered login attempt."""
134
+
135
+ with self._lock:
136
+ login_queue = self._login_notifications.get(login_id)
137
+ if login_queue is None:
138
+ raise RuntimeError(f"login {login_id!r} is not registered for waiting")
139
+ item = login_queue.get()
140
+ if isinstance(item, BaseException):
141
+ raise item
142
+ return item
143
+
144
+ @contextmanager
145
+ def pending_turn(self, thread_id: str) -> Iterator[dict[str, int]]:
146
+ """Buffer events from the point a turn/start request is sent."""
147
+ with self._lock:
148
+ cursors = {turn_id: state.next_event for turn_id, state in self._turn_states.items()}
149
+ self._pending_turn_requests[thread_id] = None
150
+ try:
151
+ yield cursors
152
+ finally:
153
+ with self._lock:
154
+ del self._pending_turn_requests[thread_id]
155
+ for state in list(self._turn_states.values()):
156
+ if state.thread_id in (None, thread_id):
157
+ self._prune_turn_events(state)
158
+
159
+ def prepare_turn(
160
+ self, turn_id: str, thread_id: str, cursors: dict[str, int], *, for_handle: bool
161
+ ) -> _TurnSubscription | None:
162
+ """Attach the requesting handle or the single low-level consumer."""
163
+ with self._lock:
164
+ state = self._turn_states.setdefault(turn_id, _TurnState(turn_id, thread_id))
165
+ state.thread_id = thread_id
166
+ if not for_handle and turn_id in self._turn_notifications:
167
+ return None
168
+ if not state.completed and (err := self._pending_turn_requests[thread_id]) is not None:
169
+ state.events[state.next_event] = err
170
+ state.next_event += 1
171
+ state.completed = True
172
+ subscription = _TurnSubscription(self, state, cursors.get(turn_id, 0))
173
+ if not for_handle:
174
+ self._turn_notifications[turn_id] = subscription
175
+ return subscription
176
+
177
+ def subscribe_turn(self, turn_id: str) -> _TurnSubscription:
178
+ """Attach a consumer starting at the next event for this turn."""
179
+ with self._lock:
180
+ state = self._turn_states.setdefault(turn_id, _TurnState(turn_id))
181
+ return _TurnSubscription(self, state, state.next_event)
182
+
183
+ @staticmethod
184
+ def _release_turn(
185
+ router_ref: weakref.ReferenceType[MessageRouter], state: _TurnState, token: object
186
+ ) -> None:
187
+ router = router_ref()
188
+ if router is not None:
189
+ with router._lock:
190
+ default = router._turn_notifications.get(state.id)
191
+ if default is not None and default._token is token:
192
+ del router._turn_notifications[state.id]
193
+ state.subscribers.pop(token, None)
194
+ router._prune_turn_events(state)
195
+
196
+ def _prune_turn_events(self, state: _TurnState) -> None:
197
+ if state.thread_id in self._pending_turn_requests or (
198
+ state.thread_id is None and self._pending_turn_requests
199
+ ):
200
+ return
201
+ consumed = min(state.subscribers.values(), default=state.next_event)
202
+ while state.first_event < consumed:
203
+ del state.events[state.first_event]
204
+ state.first_event += 1
205
+ if not state.subscribers and self._turn_states.get(state.id) is state:
206
+ del self._turn_states[state.id]
207
+
208
+ def register_turn(self, turn_id: str) -> None:
209
+ """Register the default consumer used by the low-level client API."""
210
+ with self._lock:
211
+ if turn_id not in self._turn_notifications:
212
+ self._turn_notifications[turn_id] = self.subscribe_turn(turn_id)
213
+
214
+ def unregister_turn(self, turn_id: str) -> None:
215
+ """Close only the low-level consumer, leaving other handles subscribed."""
216
+ with self._lock:
217
+ if subscription := self._turn_notifications.get(turn_id):
218
+ subscription.close()
219
+
220
+ def next_turn_notification(self, turn_id: str) -> Notification:
221
+ """Block until the next event for the default low-level consumer."""
222
+ with self._lock:
223
+ subscription = self._turn_notifications.get(turn_id)
224
+ if subscription is None:
225
+ raise RuntimeError(f"turn {turn_id!r} is not registered for streaming")
226
+ return subscription.next()
227
+
228
+ def register_goal(self, thread_id: str) -> _GoalOperationState:
229
+ """Register one thread-scoped logical goal operation before it starts."""
230
+ state = _GoalOperationState(thread_id=thread_id)
231
+ state.activate_turn_routing()
232
+ return self._register_goal(state)
233
+
234
+ def reserve_goal(self, thread_id: str) -> _GoalOperationState:
235
+ """Reserve a thread route without accepting physical turns yet."""
236
+ return self._register_goal(_GoalOperationState(thread_id=thread_id))
237
+
238
+ def _register_goal(self, state: _GoalOperationState) -> _GoalOperationState:
239
+ with self._lock:
240
+ if state.thread_id in self._goal_operations:
241
+ raise RuntimeError(
242
+ f"thread {state.thread_id!r} already has an active goal operation"
243
+ )
244
+ self._goal_operations[state.thread_id] = state
245
+ return state
246
+
247
+ def unregister_goal(self, state: _GoalOperationState) -> None:
248
+ """Stop routing notifications to a completed logical goal operation."""
249
+ with self._lock:
250
+ if self._goal_operations.get(state.thread_id) is state:
251
+ self._goal_operations.pop(state.thread_id)
252
+
253
+ def has_goal(self, thread_id: str) -> bool:
254
+ """Return whether a logical goal operation owns this thread route."""
255
+ with self._lock:
256
+ return thread_id in self._goal_operations
257
+
258
+ def route_response(self, msg: dict[str, JsonValue]) -> None:
259
+ """Deliver a JSON-RPC response or error to its request waiter."""
260
+
261
+ request_id = msg.get("id")
262
+ with self._lock:
263
+ waiter = self._response_waiters.pop(str(request_id), None)
264
+ if waiter is None:
265
+ return
266
+
267
+ if "error" in msg:
268
+ err = msg["error"]
269
+ if isinstance(err, dict):
270
+ waiter.put(
271
+ map_jsonrpc_error(
272
+ int(err.get("code", -32000)),
273
+ str(err.get("message", "unknown")),
274
+ err.get("data"),
275
+ )
276
+ )
277
+ else:
278
+ waiter.put(CodexError("Malformed JSON-RPC error response"))
279
+ return
280
+
281
+ waiter.put(msg.get("result"))
282
+
283
+ def route_notification(self, notification: Notification) -> None:
284
+ """Deliver a notification to a turn queue or the global queue."""
285
+
286
+ login_id = self._notification_login_id(notification)
287
+ if login_id is not None:
288
+ with self._lock:
289
+ login_queue = self._login_notifications.get(login_id)
290
+ if login_queue is None:
291
+ self._pending_login_notifications.setdefault(login_id, deque()).append(
292
+ notification
293
+ )
294
+ return
295
+ login_queue.put(notification)
296
+ return
297
+
298
+ turn_id = self._notification_turn_id(notification)
299
+ thread_id = self._notification_thread_id(notification)
300
+ if thread_id is not None:
301
+ with self._lock:
302
+ goal_state = self._goal_operations.get(thread_id)
303
+ if goal_state is not None and (
304
+ turn_id is not None or notification.method.startswith("thread/goal/")
305
+ ):
306
+ if goal_state.observe(notification):
307
+ if goal_state.is_finished():
308
+ self.unregister_goal(goal_state)
309
+ return
310
+ if turn_id is None:
311
+ self._global_notifications.put(notification)
312
+ return
313
+
314
+ with self._turn_condition:
315
+ state = self._turn_states.setdefault(turn_id, _TurnState(turn_id, thread_id))
316
+ state.thread_id = thread_id or state.thread_id
317
+ state.events[state.next_event] = notification
318
+ state.next_event += 1
319
+ if notification.method == "turn/completed":
320
+ state.completed = True
321
+ self._prune_turn_events(state)
322
+ self._turn_condition.notify_all()
323
+
324
+ def fail_all(self, exc: BaseException) -> None:
325
+ """Wake every blocked waiter when the reader thread exits."""
326
+
327
+ with self._lock:
328
+ response_waiters = list(self._response_waiters.values())
329
+ self._response_waiters.clear()
330
+ login_queues = list(self._login_notifications.values())
331
+ self._login_notifications.clear()
332
+ self._pending_login_notifications.clear()
333
+ for thread_id in self._pending_turn_requests:
334
+ self._pending_turn_requests[thread_id] = exc
335
+ for state in list(self._turn_states.values()):
336
+ state.events[state.next_event] = exc
337
+ state.next_event += 1
338
+ state.completed = True
339
+ self._prune_turn_events(state)
340
+ self._turn_condition.notify_all()
341
+ goal_operations = list(self._goal_operations.values())
342
+ self._goal_operations.clear()
343
+ # Put the same transport failure into every queue so no SDK call blocks
344
+ # forever waiting for a response that cannot arrive.
345
+ for waiter in response_waiters:
346
+ waiter.put(exc)
347
+ for login_queue in login_queues:
348
+ login_queue.put(exc)
349
+ for goal_operation in goal_operations:
350
+ goal_operation.fail(exc)
351
+ self._global_notifications.put(exc)
352
+
353
+ def _notification_turn_id(self, notification: Notification) -> str | None:
354
+ """Extract routing ids from generated metadata or raw unknown payloads."""
355
+ payload = notification.payload
356
+ if isinstance(payload, UnknownNotification):
357
+ raw_turn_id = payload.params.get("turnId")
358
+ if isinstance(raw_turn_id, str):
359
+ return raw_turn_id
360
+ raw_turn = payload.params.get("turn")
361
+ if isinstance(raw_turn, dict):
362
+ raw_nested_turn_id = raw_turn.get("id")
363
+ if isinstance(raw_nested_turn_id, str):
364
+ return raw_nested_turn_id
365
+ return None
366
+ return notification_turn_id(payload)
367
+
368
+ def _notification_thread_id(self, notification: Notification) -> str | None:
369
+ """Extract thread ids from typed payloads or raw unknown payloads."""
370
+ payload = notification.payload
371
+ if isinstance(payload, UnknownNotification):
372
+ raw_thread_id = payload.params.get("threadId")
373
+ return raw_thread_id if isinstance(raw_thread_id, str) else None
374
+ thread_id = getattr(payload, "thread_id", None)
375
+ return thread_id if isinstance(thread_id, str) else None
376
+
377
+ def _notification_login_id(self, notification: Notification) -> str | None:
378
+ """Extract the login attempt id from completion notifications."""
379
+ if notification.method != "account/login/completed":
380
+ return None
381
+
382
+ payload = notification.payload
383
+ if isinstance(payload, AccountLoginCompletedNotification):
384
+ return payload.login_id
385
+ if isinstance(payload, UnknownNotification):
386
+ raw_login_id = payload.params.get("loginId")
387
+ if isinstance(raw_login_id, str):
388
+ return raw_login_id
389
+ return None
openai_codex/_run.py ADDED
@@ -0,0 +1,135 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass
4
+ from typing import AsyncIterator, Iterator
5
+
6
+ from .generated.v2_all import (
7
+ AgentMessageThreadItem,
8
+ ItemCompletedNotification,
9
+ MessagePhase,
10
+ ThreadItem,
11
+ ThreadTokenUsage,
12
+ ThreadTokenUsageUpdatedNotification,
13
+ Turn,
14
+ TurnCompletedNotification,
15
+ TurnError,
16
+ TurnStatus,
17
+ )
18
+ from .models import Notification
19
+
20
+
21
+ @dataclass(slots=True)
22
+ class TurnResult:
23
+ """Collected result returned after a turn completes."""
24
+
25
+ id: str
26
+ status: TurnStatus
27
+ error: TurnError | None
28
+ started_at: int | None
29
+ completed_at: int | None
30
+ duration_ms: int | None
31
+ final_response: str | None
32
+ items: list[ThreadItem]
33
+ usage: ThreadTokenUsage | None
34
+
35
+
36
+ def _agent_message_item_from_thread_item(
37
+ item: ThreadItem,
38
+ ) -> AgentMessageThreadItem | None:
39
+ thread_item = item.root if hasattr(item, "root") else item
40
+ if isinstance(thread_item, AgentMessageThreadItem):
41
+ return thread_item
42
+ return None
43
+
44
+
45
+ def _final_assistant_response_from_items(items: list[ThreadItem]) -> str | None:
46
+ last_unknown_phase_response: str | None = None
47
+
48
+ for item in reversed(items):
49
+ agent_message = _agent_message_item_from_thread_item(item)
50
+ if agent_message is None:
51
+ continue
52
+ if agent_message.phase == MessagePhase.final_answer:
53
+ return agent_message.text
54
+ if agent_message.phase is None and last_unknown_phase_response is None:
55
+ last_unknown_phase_response = agent_message.text
56
+
57
+ return last_unknown_phase_response
58
+
59
+
60
+ def _raise_for_failed_turn(turn: Turn) -> None:
61
+ if turn.status != TurnStatus.failed:
62
+ return
63
+ if turn.error is not None and turn.error.message:
64
+ raise RuntimeError(turn.error.message)
65
+ raise RuntimeError(f"turn failed with status {turn.status.value}")
66
+
67
+
68
+ def _collect_turn_result(stream: Iterator[Notification], *, turn_id: str) -> TurnResult:
69
+ completed: TurnCompletedNotification | None = None
70
+ items: list[ThreadItem] = []
71
+ usage: ThreadTokenUsage | None = None
72
+
73
+ for event in stream:
74
+ payload = event.payload
75
+ if isinstance(payload, ItemCompletedNotification) and payload.turn_id == turn_id:
76
+ items.append(payload.item)
77
+ continue
78
+ if isinstance(payload, ThreadTokenUsageUpdatedNotification) and payload.turn_id == turn_id:
79
+ usage = payload.token_usage
80
+ continue
81
+ if isinstance(payload, TurnCompletedNotification) and payload.turn.id == turn_id:
82
+ completed = payload
83
+
84
+ if completed is None:
85
+ raise RuntimeError("turn completed event not received")
86
+
87
+ _raise_for_failed_turn(completed.turn)
88
+ turn = completed.turn
89
+ return TurnResult(
90
+ id=turn.id,
91
+ status=turn.status,
92
+ error=turn.error,
93
+ started_at=turn.started_at,
94
+ completed_at=turn.completed_at,
95
+ duration_ms=turn.duration_ms,
96
+ final_response=_final_assistant_response_from_items(items),
97
+ items=items,
98
+ usage=usage,
99
+ )
100
+
101
+
102
+ async def _collect_async_turn_result(
103
+ stream: AsyncIterator[Notification], *, turn_id: str
104
+ ) -> TurnResult:
105
+ completed: TurnCompletedNotification | None = None
106
+ items: list[ThreadItem] = []
107
+ usage: ThreadTokenUsage | None = None
108
+
109
+ async for event in stream:
110
+ payload = event.payload
111
+ if isinstance(payload, ItemCompletedNotification) and payload.turn_id == turn_id:
112
+ items.append(payload.item)
113
+ continue
114
+ if isinstance(payload, ThreadTokenUsageUpdatedNotification) and payload.turn_id == turn_id:
115
+ usage = payload.token_usage
116
+ continue
117
+ if isinstance(payload, TurnCompletedNotification) and payload.turn.id == turn_id:
118
+ completed = payload
119
+
120
+ if completed is None:
121
+ raise RuntimeError("turn completed event not received")
122
+
123
+ _raise_for_failed_turn(completed.turn)
124
+ turn = completed.turn
125
+ return TurnResult(
126
+ id=turn.id,
127
+ status=turn.status,
128
+ error=turn.error,
129
+ started_at=turn.started_at,
130
+ completed_at=turn.completed_at,
131
+ duration_ms=turn.duration_ms,
132
+ final_response=_final_assistant_response_from_items(items),
133
+ items=items,
134
+ usage=usage,
135
+ )