codexed 0.1.1__tar.gz → 0.1.2__tar.gz

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.
Files changed (34) hide show
  1. {codexed-0.1.1 → codexed-0.1.2}/PKG-INFO +1 -1
  2. {codexed-0.1.1 → codexed-0.1.2}/pyproject.toml +1 -1
  3. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/__init__.py +6 -13
  4. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/client.py +35 -277
  5. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/models/__init__.py +2 -4
  6. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/models/misc.py +1 -23
  7. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/models/responses.py +6 -6
  8. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/models/tool_config.py +33 -30
  9. codexed-0.1.2/src/codexed/session.py +234 -0
  10. {codexed-0.1.1 → codexed-0.1.2}/LICENSE +0 -0
  11. {codexed-0.1.1 → codexed-0.1.2}/README.md +0 -0
  12. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/README.md +0 -0
  13. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/exceptions.py +0 -0
  14. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/helpers.py +0 -0
  15. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/log.py +0 -0
  16. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/models/base.py +0 -0
  17. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/models/codex_types.py +0 -0
  18. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/models/command_action.py +0 -0
  19. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/models/event_data.py +0 -0
  20. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/models/events.py +0 -0
  21. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/models/fuzzy_search.py +0 -0
  22. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/models/hooks.py +0 -0
  23. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/models/mcp_server.py +0 -0
  24. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/models/realtime.py +0 -0
  25. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/models/request_params.py +0 -0
  26. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/models/response_item.py +0 -0
  27. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/models/terminal.py +0 -0
  28. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/models/thread_item.py +0 -0
  29. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/models/thread_status.py +0 -0
  30. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/models/token_usage.py +0 -0
  31. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/models/user_input.py +0 -0
  32. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/models/web_search.py +0 -0
  33. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/py.typed +0 -0
  34. {codexed-0.1.1 → codexed-0.1.2}/src/codexed/request_handlers.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: codexed
3
- Version: 0.1.1
3
+ Version: 0.1.2
4
4
  Summary: Alternative codex app-server client
5
5
  Keywords:
6
6
  Author: Philipp Temminghoff
@@ -2,7 +2,7 @@
2
2
 
3
3
  [project]
4
4
  name = "codexed"
5
- version = "0.1.1"
5
+ version = "0.1.2"
6
6
  description = "Alternative codex app-server client"
7
7
  readme = "README.md"
8
8
  requires-python = ">=3.13"
@@ -21,7 +21,8 @@ __all__ = [
21
21
  ]
22
22
 
23
23
 
24
- from codexed.client import CodexClient, Session
24
+ from codexed.client import CodexClient
25
+ from codexed.session import Session
25
26
  from codexed.exceptions import (
26
27
  CodexError,
27
28
  CodexProcessError,
@@ -54,7 +55,7 @@ from codexed.models import (
54
55
  ReviewStartResponse,
55
56
  SkillData,
56
57
  ThreadArchivedData,
57
- ThreadData,
58
+ Thread,
58
59
  ThreadListResponse,
59
60
  ThreadNameUpdatedData,
60
61
  ThreadReadResponse,
@@ -142,16 +143,8 @@ from codexed.models.events import (
142
143
  TurnPlanUpdatedEvent,
143
144
  TurnStartedEvent,
144
145
  )
145
- from codexed.models.mcp_server import (
146
- HttpMcpServer,
147
- McpServerConfig,
148
- StdioMcpServer,
149
- )
150
- from codexed.models.tool_config import (
151
- BuiltinToolsConfig,
152
- ToolConfig,
153
- tools_to_config_dict,
154
- )
146
+ from codexed.models.mcp_server import HttpMcpServer, McpServerConfig, StdioMcpServer
147
+ from codexed.models.tool_config import BuiltinToolsConfig, ToolConfig, tools_to_config_dict
155
148
  from codexed.request_handlers import (
156
149
  ApprovalHandler,
157
150
  ApprovalParams,
@@ -242,11 +235,11 @@ __all__ = [
242
235
  "SkillData",
243
236
  "SkillScope",
244
237
  "StdioMcpServer",
238
+ "Thread",
245
239
  "ThreadActiveFlag",
246
240
  "ThreadArchivedData",
247
241
  "ThreadArchivedEvent",
248
242
  "ThreadCompactedEvent",
249
- "ThreadData",
250
243
  "ThreadListResponse",
251
244
  "ThreadNameUpdatedData",
252
245
  "ThreadNameUpdatedEvent",
@@ -89,8 +89,6 @@ from codexed.models import (
89
89
  ThreadRollbackResponse,
90
90
  ThreadSetNameParams,
91
91
  ThreadStartParams,
92
- ThreadTokenUsageUpdatedData,
93
- ThreadTokenUsageUpdatedEvent,
94
92
  ThreadUnarchiveParams,
95
93
  ThreadUnarchiveResponse,
96
94
  ThreadUnsubscribeParams,
@@ -107,6 +105,7 @@ from codexed.models import (
107
105
  UserInputText,
108
106
  codex_event_adapter,
109
107
  )
108
+ from codexed.models.tool_config import tools_to_config_dict
110
109
  from codexed.request_handlers import (
111
110
  SERVER_REQUEST_COMMAND_APPROVAL,
112
111
  SERVER_REQUEST_DYNAMIC_TOOL_CALL,
@@ -145,7 +144,6 @@ if TYPE_CHECKING:
145
144
  SkillData,
146
145
  ThreadSortKey,
147
146
  ThreadSourceKind,
148
- ThreadTokenUsage,
149
147
  ToolConfig,
150
148
  Turn,
151
149
  UserInput,
@@ -159,206 +157,11 @@ if TYPE_CHECKING:
159
157
  ServerRequestHandler,
160
158
  UserInputHandler,
161
159
  )
160
+ from codexed.session import Session
162
161
 
163
162
  logger = logging.getLogger(__name__)
164
163
 
165
164
 
166
- class Session:
167
- """Runtime handle for an active Codex thread.
168
-
169
- Wraps a :class:`CodexClient` and a ``thread_id`` so that every
170
- thread-scoped operation can be called without passing the ID again.
171
-
172
- Returned by :meth:`CodexClient.thread_start`,
173
- :meth:`CodexClient.thread_resume`, and :meth:`CodexClient.thread_fork`.
174
-
175
- Example::
176
-
177
- session = await client.thread_start(cwd="/my/project")
178
- async for event in session.turn_stream("Explain this repo"):
179
- ...
180
- await session.set_name("exploration")
181
- """
182
-
183
- def __init__(self, client: CodexClient, response: ThreadResponse) -> None:
184
- self._client = client
185
- self.response = response
186
- self.usage: ThreadTokenUsage | None = None
187
-
188
- @property
189
- def thread_id(self) -> str:
190
- """The underlying thread ID."""
191
- return self.response.thread.id
192
-
193
- # -- Turn operations -----------------------------------------------------
194
-
195
- async def turn_stream(
196
- self,
197
- user_input: str | list[UserInput],
198
- *,
199
- model: str | None = None,
200
- effort: ReasoningEffort | None = None,
201
- approval_policy: ApprovalPolicy | None = None,
202
- cwd: str | None = None,
203
- sandbox_policy: SandboxMode | dict[str, Any] | None = None,
204
- output_schema: dict[str, Any] | type[Any] | None = None,
205
- personality: Personality | None = None,
206
- summary: ReasoningSummary | None = None,
207
- collaboration_mode: CollaborationMode | None = None,
208
- ) -> AsyncIterator[CodexEvent]:
209
- """Start a turn and stream events. See :meth:`CodexClient.turn_stream`."""
210
- async for event in self._client.turn_stream(
211
- self.thread_id,
212
- user_input,
213
- model=model,
214
- effort=effort,
215
- approval_policy=approval_policy,
216
- cwd=cwd,
217
- sandbox_policy=sandbox_policy,
218
- output_schema=output_schema,
219
- personality=personality,
220
- summary=summary,
221
- collaboration_mode=collaboration_mode,
222
- ):
223
- match event:
224
- case ThreadTokenUsageUpdatedEvent(
225
- data=ThreadTokenUsageUpdatedData(token_usage=usage)
226
- ):
227
- self.usage = usage
228
- yield event
229
-
230
- async def turn_steer(
231
- self,
232
- user_input: str | list[UserInput],
233
- *,
234
- expected_turn_id: str,
235
- ) -> TurnSteerResponse:
236
- """Steer a running turn. See :meth:`CodexClient.turn_steer`."""
237
- return await self._client.turn_steer(
238
- self.thread_id,
239
- user_input,
240
- expected_turn_id=expected_turn_id,
241
- )
242
-
243
- async def turn_interrupt(self, turn_id: str) -> None:
244
- """Interrupt a running turn. See :meth:`CodexClient.turn_interrupt`."""
245
- await self._client.turn_interrupt(self.thread_id, turn_id)
246
-
247
- async def turn_stream_structured[ResultType: BaseModel](
248
- self,
249
- user_input: str | list[UserInput],
250
- result_type: type[ResultType],
251
- *,
252
- model: str | None = None,
253
- effort: ReasoningEffort | None = None,
254
- approval_policy: ApprovalPolicy | None = None,
255
- cwd: str | None = None,
256
- sandbox_policy: SandboxMode | dict[str, Any] | None = None,
257
- personality: Personality | None = None,
258
- summary: ReasoningSummary | None = None,
259
- collaboration_mode: CollaborationMode | None = None,
260
- ) -> ResultType:
261
- """Structured-output turn. See :meth:`CodexClient.turn_stream_structured`."""
262
- return await self._client.turn_stream_structured(
263
- self.thread_id,
264
- user_input,
265
- result_type,
266
- model=model,
267
- effort=effort,
268
- approval_policy=approval_policy,
269
- cwd=cwd,
270
- sandbox_policy=sandbox_policy,
271
- personality=personality,
272
- summary=summary,
273
- collaboration_mode=collaboration_mode,
274
- )
275
-
276
- # -- Thread operations ---------------------------------------------------
277
-
278
- async def read(self, *, include_turns: bool = False) -> ThreadReadResponse:
279
- """Read thread data. See :meth:`CodexClient.thread_read`."""
280
- return await self._client.thread_read(self.thread_id, include_turns=include_turns)
281
-
282
- async def unsubscribe(self) -> ThreadUnsubscribeResponse:
283
- """Unsubscribe from thread events. See :meth:`CodexClient.thread_unsubscribe`."""
284
- return await self._client.thread_unsubscribe(self.thread_id)
285
-
286
- async def archive(self) -> None:
287
- """Archive this thread. See :meth:`CodexClient.thread_archive`."""
288
- await self._client.thread_archive(self.thread_id)
289
-
290
- async def unarchive(self) -> ThreadUnarchiveResponse:
291
- """Unarchive this thread. See :meth:`CodexClient.thread_unarchive`."""
292
- return await self._client.thread_unarchive(self.thread_id)
293
-
294
- async def set_name(self, name: str) -> None:
295
- """Set thread name. See :meth:`CodexClient.thread_set_name`."""
296
- await self._client.thread_set_name(self.thread_id, name)
297
-
298
- async def compact_start(self) -> None:
299
- """Trigger context compaction. See :meth:`CodexClient.thread_compact_start`."""
300
- await self._client.thread_compact_start(self.thread_id)
301
-
302
- async def rollback(self, turns: int) -> ThreadRollbackResponse:
303
- """Rollback last N turns. See :meth:`CodexClient.thread_rollback`."""
304
- return await self._client.thread_rollback(self.thread_id, turns)
305
-
306
- async def rollback_to_turn(self, turn_id: str) -> ThreadRollbackResponse:
307
- """Rollback to a specific turn. See :meth:`CodexClient.thread_rollback_to_turn`."""
308
- return await self._client.thread_rollback_to_turn(self.thread_id, turn_id)
309
-
310
- # -- Review --------------------------------------------------------------
311
-
312
- async def review_start(
313
- self,
314
- target: ReviewTarget,
315
- *,
316
- delivery: ReviewDelivery | None = None,
317
- ) -> ReviewStartResponse:
318
- """Start a code review. See :meth:`CodexClient.review_start`."""
319
- return await self._client.review_start(self.thread_id, target, delivery=delivery)
320
-
321
- # -- Fork ----------------------------------------------------------------
322
-
323
- async def fork(
324
- self,
325
- *,
326
- path: str | None = None,
327
- cwd: str | None = None,
328
- model: str | None = None,
329
- model_provider: str | None = None,
330
- base_instructions: str | None = None,
331
- developer_instructions: str | None = None,
332
- approval_policy: ApprovalPolicy | None = None,
333
- sandbox: SandboxMode | None = None,
334
- config: dict[str, Any] | None = None,
335
- tools: list[ToolConfig] | None = None,
336
- code_mode: bool | None = None,
337
- personality: Personality | None = None,
338
- turn_id: str | None = None,
339
- ) -> Session:
340
- """Fork this thread. See :meth:`CodexClient.thread_fork`."""
341
- return await self._client.thread_fork(
342
- self.thread_id,
343
- path=path,
344
- cwd=cwd,
345
- model=model,
346
- model_provider=model_provider,
347
- base_instructions=base_instructions,
348
- developer_instructions=developer_instructions,
349
- approval_policy=approval_policy,
350
- sandbox=sandbox,
351
- config=config,
352
- tools=tools,
353
- code_mode=code_mode,
354
- personality=personality,
355
- turn_id=turn_id,
356
- )
357
-
358
- def __repr__(self) -> str:
359
- return f"Session(thread_id={self.thread_id!r})"
360
-
361
-
362
165
  class CodexClient:
363
166
  """Client for the Codex app-server JSON-RPC protocol.
364
167
 
@@ -523,8 +326,6 @@ class CodexClient:
523
326
  if mcp_elicitation_for_approvals:
524
327
  merged.setdefault("features", {})["tool_call_mcp_elicitation"] = True
525
328
  if tools is not None:
526
- from codexed.models.tool_config import tools_to_config_dict
527
-
528
329
  tool_config = tools_to_config_dict(tools)
529
330
  for key, value in tool_config.items():
530
331
  if key not in merged:
@@ -579,6 +380,8 @@ class CodexClient:
579
380
  Returns:
580
381
  Session wrapping the new thread
581
382
  """
383
+ from codexed.session import Session
384
+
582
385
  params = ThreadStartParams(
583
386
  cwd=cwd,
584
387
  model=model,
@@ -642,6 +445,15 @@ class CodexClient:
642
445
  Returns:
643
446
  Session wrapping the resumed thread
644
447
  """
448
+ from codexed.session import Session
449
+
450
+ cfg = self._merge_config(
451
+ config,
452
+ tools,
453
+ code_mode,
454
+ mcp_servers,
455
+ mcp_elicitation_for_approvals=self._mcp_elicitation_for_approvals,
456
+ )
645
457
  params = ThreadResumeParams(
646
458
  thread_id=thread_id,
647
459
  path=path,
@@ -652,13 +464,7 @@ class CodexClient:
652
464
  developer_instructions=developer_instructions,
653
465
  approval_policy=approval_policy,
654
466
  sandbox=sandbox,
655
- config=self._merge_config(
656
- config,
657
- tools,
658
- code_mode,
659
- mcp_servers,
660
- mcp_elicitation_for_approvals=self._mcp_elicitation_for_approvals,
661
- ),
467
+ config=cfg,
662
468
  personality=personality,
663
469
  )
664
470
  result = await self._send_request("thread/resume", params)
@@ -707,6 +513,15 @@ class CodexClient:
707
513
  Returns:
708
514
  Session wrapping the new forked thread
709
515
  """
516
+ from codexed.session import Session
517
+
518
+ cfg = self._merge_config(
519
+ config,
520
+ tools,
521
+ code_mode,
522
+ mcp_servers,
523
+ mcp_elicitation_for_approvals=self._mcp_elicitation_for_approvals,
524
+ )
710
525
  params = ThreadForkParams(
711
526
  thread_id=thread_id,
712
527
  path=path,
@@ -717,13 +532,7 @@ class CodexClient:
717
532
  developer_instructions=developer_instructions,
718
533
  approval_policy=approval_policy,
719
534
  sandbox=sandbox,
720
- config=self._merge_config(
721
- config,
722
- tools,
723
- code_mode,
724
- mcp_servers,
725
- mcp_elicitation_for_approvals=self._mcp_elicitation_for_approvals,
726
- ),
535
+ config=cfg,
727
536
  personality=personality,
728
537
  )
729
538
  result = await self._send_request("thread/fork", params)
@@ -855,18 +664,12 @@ class CodexClient:
855
664
  """
856
665
  thread_response = await self.thread_read(thread_id, include_turns=True)
857
666
  turns = thread_response.thread.turns
858
- turn_index: int | None = None
859
- for i, turn in enumerate(turns):
860
- if turn.id == turn_id:
861
- turn_index = i
862
- break
667
+ turn_index = next((i for i, turn in enumerate(turns) if turn.id == turn_id), None)
863
668
  if turn_index is None:
864
- msg = f"Turn {turn_id!r} not found in thread {thread_id!r}"
865
- raise ValueError(msg)
669
+ raise ValueError(f"Turn {turn_id!r} not found in thread {thread_id!r}")
866
670
  num_turns_to_drop = len(turns) - turn_index - 1
867
671
  if num_turns_to_drop < 1:
868
- msg = f"Turn {turn_id!r} is already the last turn in thread {thread_id!r}"
869
- raise ValueError(msg)
672
+ raise ValueError(f"Turn {turn_id!r} is already the last turn in thread {thread_id!r}")
870
673
  return await self.thread_rollback(thread_id, num_turns_to_drop)
871
674
 
872
675
  # ========================================================================
@@ -1039,22 +842,6 @@ class CodexClient:
1039
842
  Raises:
1040
843
  ValidationError: If the agent's response doesn't match the schema
1041
844
  CodexRequestError: If the turn fails
1042
-
1043
- Example:
1044
- class FileInfo(BaseModel):
1045
- name: str
1046
- type: str
1047
-
1048
- class FileList(BaseModel):
1049
- files: list[FileInfo]
1050
- total: int
1051
-
1052
- result = await client.turn_stream_structured(
1053
- thread.id,
1054
- "List Python files in current directory",
1055
- FileList, # Must be a Pydantic type, not a dict
1056
- )
1057
- print(f"Found {result.total} files: {result.files}")
1058
845
  """
1059
846
  turn: Turn | None = None
1060
847
  async for event in self.turn_stream(
@@ -1077,12 +864,10 @@ class CodexClient:
1077
864
  raise TurnFailedError(error, turn_id="unknown")
1078
865
 
1079
866
  if turn is None:
1080
- msg = "Turn completed without a TurnCompletedEvent"
1081
- raise CodexRequestError(code=-1, message=msg)
867
+ raise CodexRequestError(code=-1, message="Turn completed without a TurnCompletedEvent")
1082
868
  response_text = turn.final_response
1083
869
  if response_text is None:
1084
- msg = "Turn completed without a final response"
1085
- raise CodexRequestError(code=-1, message=msg)
870
+ raise CodexRequestError(code=-1, message="Turn completed without a final response")
1086
871
  return result_type.model_validate_json(response_text)
1087
872
 
1088
873
  # ========================================================================
@@ -1341,25 +1126,15 @@ class CodexClient:
1341
1126
  params = FsRemoveParams(path=path, recursive=recursive, force=force)
1342
1127
  await self._send_request("fs/remove", params)
1343
1128
 
1344
- async def fs_copy(
1345
- self,
1346
- source_path: str,
1347
- destination_path: str,
1348
- *,
1349
- recursive: bool = False,
1350
- ) -> None:
1129
+ async def fs_copy(self, source: str, destination: str, *, recursive: bool = False) -> None:
1351
1130
  """Copy a file or directory tree on the host filesystem.
1352
1131
 
1353
1132
  Args:
1354
- source_path: Absolute source path.
1355
- destination_path: Absolute destination path.
1133
+ source: Absolute source path.
1134
+ destination: Absolute destination path.
1356
1135
  recursive: Required for directory copies; ignored for file copies.
1357
1136
  """
1358
- params = FsCopyParams(
1359
- source_path=source_path,
1360
- destination_path=destination_path,
1361
- recursive=recursive,
1362
- )
1137
+ params = FsCopyParams(source_path=source, destination_path=destination, recursive=recursive)
1363
1138
  await self._send_request("fs/copy", params)
1364
1139
 
1365
1140
  # ========================================================================
@@ -1760,10 +1535,7 @@ class CodexClient:
1760
1535
  message: Raw JSON-RPC message
1761
1536
  """
1762
1537
  match message:
1763
- case {
1764
- "method": _,
1765
- "id": _,
1766
- }: # Server request - the server is asking us to do something
1538
+ case {"method": _, "id": _}: # Server request - the server is asking us to do something
1767
1539
  await self._handle_server_request(message)
1768
1540
  case {"id": _}: # Response to one of our requests
1769
1541
  self._handle_response(message)
@@ -1834,13 +1606,8 @@ class CodexClient:
1834
1606
 
1835
1607
  params_type, _ = type_entry
1836
1608
  handler = self._server_request_handlers.get(method)
1837
-
1838
1609
  if handler is None:
1839
- logger.warning(
1840
- "No handler registered for server request: %s (id=%s)",
1841
- method,
1842
- request_id,
1843
- )
1610
+ logger.warning("No handler registered for request: %s (id=%s)", method, request_id)
1844
1611
  await self._send_server_request_error(request_id, -32603, f"No handler for: {method}")
1845
1612
  return
1846
1613
 
@@ -1893,15 +1660,6 @@ class CodexClient:
1893
1660
  Args:
1894
1661
  method: Server request method name (use SERVER_REQUEST_* constants)
1895
1662
  handler: Async callback that processes the request and returns a response
1896
-
1897
- Example::
1898
-
1899
- async def handle_approval(
1900
- params: CommandExecutionRequestApprovalParams,
1901
- ) -> CommandExecutionRequestApprovalResponse:
1902
- return CommandExecutionRequestApprovalResponse(decision="allow")
1903
-
1904
- client.register_handler(SERVER_REQUEST_COMMAND_APPROVAL, handle_approval)
1905
1663
  """
1906
1664
  if method not in SERVER_REQUEST_TYPES:
1907
1665
  msg = (
@@ -262,7 +262,6 @@ from codexed.models.misc import (
262
262
  SkillsContainer,
263
263
  SkillToolDependency,
264
264
  Thread,
265
- ThreadData,
266
265
  ToolRequestUserInputAnswer,
267
266
  ToolRequestUserInputOption,
268
267
  ToolRequestUserInputQuestion,
@@ -453,7 +452,7 @@ from codexed.models.tool_config import (
453
452
  ToolSearchToolConfig,
454
453
  ToolSuggestToolConfig,
455
454
  ViewImageToolConfig,
456
- WebSearchLocationConfig,
455
+ WebSearchLocation,
457
456
  WebSearchToolConfig,
458
457
  tools_to_config_dict,
459
458
  )
@@ -807,7 +806,6 @@ __all__ = [
807
806
  "ThreadCompactStartParams",
808
807
  "ThreadCompactedData",
809
808
  "ThreadCompactedEvent",
810
- "ThreadData",
811
809
  "ThreadForkParams",
812
810
  "ThreadItem",
813
811
  "ThreadItemAgentMessage",
@@ -904,7 +902,7 @@ __all__ = [
904
902
  "WebSearchActionOther",
905
903
  "WebSearchActionSearch",
906
904
  "WebSearchCallResponseItem",
907
- "WebSearchLocationConfig",
905
+ "WebSearchLocation",
908
906
  "WebSearchToolConfig",
909
907
  "WindowsWorldWritableWarningData",
910
908
  "WindowsWorldWritableWarningEvent",
@@ -13,7 +13,6 @@ from codexed.models.codex_types import ( # noqa: TC001
13
13
  InputModality,
14
14
  McpAuthStatusValue,
15
15
  MergeStrategy,
16
- ModelProvider,
17
16
  NetworkApprovalProtocol,
18
17
  NetworkPolicyRuleAction,
19
18
  PlanType,
@@ -209,7 +208,7 @@ class Turn(CodexBaseModel):
209
208
 
210
209
 
211
210
  class Thread(CodexBaseModel):
212
- """Thread data structure."""
211
+ """Thread data structure (matches upstream Codex Thread type)."""
213
212
 
214
213
  id: str
215
214
  preview: str = ""
@@ -229,27 +228,6 @@ class Thread(CodexBaseModel):
229
228
  turns: list[Turn] = Field(default_factory=list)
230
229
 
231
230
 
232
- class ThreadData(CodexBaseModel):
233
- """Thread data in responses."""
234
-
235
- id: str
236
- preview: str = ""
237
- ephemeral: bool = False
238
- model_provider: ModelProvider = "openai"
239
- created_at: int = 0
240
- updated_at: int = 0
241
- status: ThreadStatusValue | None = None
242
- path: str | None = None
243
- cwd: str | None = None
244
- cli_version: str | None = None
245
- source: str | None = None
246
- agent_nickname: str | None = None
247
- agent_role: str | None = None
248
- git_info: GitInfo | None = None
249
- name: str | None = None
250
- turns: list[Turn] = Field(default_factory=list)
251
-
252
-
253
231
  class TurnData(CodexBaseModel):
254
232
  """Turn data in responses."""
255
233
 
@@ -23,7 +23,7 @@ from codexed.models.misc import ( # noqa: TC001
23
23
  McpServerStatusEntry,
24
24
  ModelData,
25
25
  SkillsContainer,
26
- ThreadData,
26
+ Thread,
27
27
  ToolRequestUserInputAnswer,
28
28
  Turn,
29
29
  TurnData,
@@ -83,13 +83,13 @@ class McpServerElicitationResponse(CodexBaseModel):
83
83
  class ThreadReadResponse(CodexBaseModel):
84
84
  """Response for thread/read request."""
85
85
 
86
- thread: ThreadData
86
+ thread: Thread
87
87
 
88
88
 
89
89
  class ThreadResponse(CodexBaseModel):
90
90
  """Response for thread/start, thread/resume, and thread/fork."""
91
91
 
92
- thread: ThreadData
92
+ thread: Thread
93
93
  model: str
94
94
  model_provider: str
95
95
  cwd: str
@@ -121,7 +121,7 @@ class ReviewStartResponse(CodexBaseModel):
121
121
  class ThreadListResponse(CodexBaseModel):
122
122
  """Response for thread/list request."""
123
123
 
124
- data: list[ThreadData]
124
+ data: list[Thread]
125
125
  next_cursor: str | None = None
126
126
 
127
127
 
@@ -134,14 +134,14 @@ class ThreadLoadedListResponse(CodexBaseModel):
134
134
  class ThreadRollbackResponse(CodexBaseModel):
135
135
  """Response for thread/rollback request."""
136
136
 
137
- thread: ThreadData
137
+ thread: Thread
138
138
  turns: list[Turn]
139
139
 
140
140
 
141
141
  class ThreadUnarchiveResponse(CodexBaseModel):
142
142
  """Response for thread/unarchive request."""
143
143
 
144
- thread: ThreadData
144
+ thread: Thread
145
145
 
146
146
 
147
147
  class SkillsListResponse(CodexBaseModel):
@@ -11,9 +11,9 @@ into the ``config`` dict accepted by ``ThreadStartParams``.
11
11
 
12
12
  from __future__ import annotations
13
13
 
14
- from typing import Annotated, Any, Literal
14
+ from typing import Annotated, Any, Literal, assert_never
15
15
 
16
- from pydantic import BaseModel, ConfigDict, Discriminator, Tag
16
+ from pydantic import BaseModel, ConfigDict, Discriminator
17
17
 
18
18
 
19
19
  class _ToolConfigBase(BaseModel):
@@ -55,7 +55,7 @@ class ApplyPatchToolConfig(_ToolConfigBase):
55
55
  # ---------------------------------------------------------------------------
56
56
 
57
57
 
58
- class WebSearchLocationConfig(_ToolConfigBase):
58
+ class WebSearchLocation(_ToolConfigBase):
59
59
  """Location hints for web search results."""
60
60
 
61
61
  country: str | None = None
@@ -78,7 +78,7 @@ class WebSearchToolConfig(_ToolConfigBase):
78
78
  allowed_domains: list[str] | None = None
79
79
  """Restrict search to these domains only."""
80
80
 
81
- location: WebSearchLocationConfig | None = None
81
+ location: WebSearchLocation | None = None
82
82
  """Approximate user location for localised results."""
83
83
 
84
84
 
@@ -259,24 +259,24 @@ class McpResourceToolsConfig(_ToolConfigBase):
259
259
  # ===========================================================================
260
260
 
261
261
  ToolConfig = Annotated[
262
- Annotated[ShellToolConfig, Tag("shell")]
263
- | Annotated[ApplyPatchToolConfig, Tag("apply_patch")]
264
- | Annotated[WebSearchToolConfig, Tag("web_search")]
265
- | Annotated[ImageGenerationToolConfig, Tag("image_generation")]
266
- | Annotated[ViewImageToolConfig, Tag("view_image")]
267
- | Annotated[PlanToolConfig, Tag("plan")]
268
- | Annotated[JsReplToolConfig, Tag("js_repl")]
269
- | Annotated[CollabToolsConfig, Tag("collab")]
270
- | Annotated[AgentJobsToolsConfig, Tag("agent_jobs")]
271
- | Annotated[RequestUserInputToolConfig, Tag("request_user_input")]
272
- | Annotated[RequestPermissionsToolConfig, Tag("request_permissions")]
273
- | Annotated[ArtifactsToolConfig, Tag("artifacts")]
274
- | Annotated[GrepFilesToolConfig, Tag("grep_files")]
275
- | Annotated[ReadFileToolConfig, Tag("read_file")]
276
- | Annotated[ListDirToolConfig, Tag("list_dir")]
277
- | Annotated[ToolSearchToolConfig, Tag("tool_search")]
278
- | Annotated[ToolSuggestToolConfig, Tag("tool_suggest")]
279
- | Annotated[McpResourceToolsConfig, Tag("mcp_resources")],
262
+ ShellToolConfig
263
+ | ApplyPatchToolConfig
264
+ | WebSearchToolConfig
265
+ | ImageGenerationToolConfig
266
+ | ViewImageToolConfig
267
+ | PlanToolConfig
268
+ | JsReplToolConfig
269
+ | CollabToolsConfig
270
+ | AgentJobsToolsConfig
271
+ | RequestUserInputToolConfig
272
+ | RequestPermissionsToolConfig
273
+ | ArtifactsToolConfig
274
+ | GrepFilesToolConfig
275
+ | ReadFileToolConfig
276
+ | ListDirToolConfig
277
+ | ToolSearchToolConfig
278
+ | ToolSuggestToolConfig
279
+ | McpResourceToolsConfig,
280
280
  Discriminator("type"),
281
281
  ]
282
282
  """Discriminated union of all builtin tool configurations."""
@@ -340,10 +340,15 @@ def tools_to_config_dict(tools: list[ToolConfig]) -> dict[str, Any]:
340
340
 
341
341
  case ApplyPatchToolConfig(variant=variant):
342
342
  config["include_apply_patch_tool"] = True
343
- if variant == "freeform":
344
- features["apply_patch_freeform"] = True
345
- elif variant == "function":
346
- features["apply_patch_freeform"] = False
343
+ match variant:
344
+ case "freeform":
345
+ features["apply_patch_freeform"] = True
346
+ case "function":
347
+ features["apply_patch_freeform"] = False
348
+ case None:
349
+ pass
350
+ case _ as unreachable:
351
+ assert_never(unreachable)
347
352
 
348
353
  case WebSearchToolConfig(
349
354
  mode=mode,
@@ -358,10 +363,8 @@ def tools_to_config_dict(tools: list[ToolConfig]) -> dict[str, Any]:
358
363
  ws_config["context_size"] = context_size
359
364
  if allowed_domains is not None:
360
365
  ws_config["allowed_domains"] = allowed_domains
361
- if location is not None:
362
- loc = location.model_dump(exclude_none=True)
363
- if loc:
364
- ws_config["location"] = loc
366
+ if location is not None and (loc := location.model_dump(exclude_none=True)):
367
+ ws_config["location"] = loc
365
368
  if ws_config:
366
369
  tools_section["web_search"] = ws_config
367
370
 
@@ -0,0 +1,234 @@
1
+ """Codex app-server client."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import AsyncIterator # noqa: TC003
6
+ import logging
7
+ from typing import TYPE_CHECKING, Any
8
+
9
+ from pydantic import BaseModel
10
+
11
+ from codexed.models import ThreadTokenUsageUpdatedData, ThreadTokenUsageUpdatedEvent
12
+
13
+
14
+ if TYPE_CHECKING:
15
+ from codexed.client import CodexClient
16
+ from codexed.models import (
17
+ ApprovalPolicy,
18
+ CodexEvent,
19
+ CollaborationMode,
20
+ Personality,
21
+ ReasoningEffort,
22
+ ReasoningSummary,
23
+ ReviewDelivery,
24
+ ReviewStartResponse,
25
+ ReviewTarget,
26
+ SandboxMode,
27
+ ThreadReadResponse,
28
+ ThreadResponse,
29
+ ThreadRollbackResponse,
30
+ ThreadTokenUsage,
31
+ ThreadUnarchiveResponse,
32
+ ThreadUnsubscribeResponse,
33
+ ToolConfig,
34
+ TurnSteerResponse,
35
+ UserInput,
36
+ )
37
+
38
+ logger = logging.getLogger(__name__)
39
+
40
+
41
+ class Session:
42
+ """Runtime handle for an active Codex thread.
43
+
44
+ Wraps a :class:`CodexClient` and a ``thread_id`` so that every
45
+ thread-scoped operation can be called without passing the ID again.
46
+
47
+ Returned by :meth:`CodexClient.thread_start`,
48
+ :meth:`CodexClient.thread_resume`, and :meth:`CodexClient.thread_fork`.
49
+
50
+ Example::
51
+
52
+ session = await client.thread_start(cwd="/my/project")
53
+ async for event in session.turn_stream("Explain this repo"):
54
+ ...
55
+ await session.set_name("exploration")
56
+ """
57
+
58
+ def __init__(self, client: CodexClient, response: ThreadResponse) -> None:
59
+ self._client = client
60
+ self.response = response
61
+ self.usage: ThreadTokenUsage | None = None
62
+
63
+ @property
64
+ def thread_id(self) -> str:
65
+ """The underlying thread ID."""
66
+ return self.response.thread.id
67
+
68
+ # -- Turn operations -----------------------------------------------------
69
+
70
+ async def turn_stream(
71
+ self,
72
+ user_input: str | list[UserInput],
73
+ *,
74
+ model: str | None = None,
75
+ effort: ReasoningEffort | None = None,
76
+ approval_policy: ApprovalPolicy | None = None,
77
+ cwd: str | None = None,
78
+ sandbox_policy: SandboxMode | dict[str, Any] | None = None,
79
+ output_schema: dict[str, Any] | type[Any] | None = None,
80
+ personality: Personality | None = None,
81
+ summary: ReasoningSummary | None = None,
82
+ collaboration_mode: CollaborationMode | None = None,
83
+ ) -> AsyncIterator[CodexEvent]:
84
+ """Start a turn and stream events. See :meth:`CodexClient.turn_stream`."""
85
+ async for event in self._client.turn_stream(
86
+ self.thread_id,
87
+ user_input,
88
+ model=model,
89
+ effort=effort,
90
+ approval_policy=approval_policy,
91
+ cwd=cwd,
92
+ sandbox_policy=sandbox_policy,
93
+ output_schema=output_schema,
94
+ personality=personality,
95
+ summary=summary,
96
+ collaboration_mode=collaboration_mode,
97
+ ):
98
+ match event:
99
+ case ThreadTokenUsageUpdatedEvent(
100
+ data=ThreadTokenUsageUpdatedData(token_usage=usage)
101
+ ):
102
+ self.usage = usage
103
+ yield event
104
+
105
+ async def turn_steer(
106
+ self,
107
+ user_input: str | list[UserInput],
108
+ *,
109
+ expected_turn_id: str,
110
+ ) -> TurnSteerResponse:
111
+ """Steer a running turn. See :meth:`CodexClient.turn_steer`."""
112
+ return await self._client.turn_steer(
113
+ self.thread_id,
114
+ user_input,
115
+ expected_turn_id=expected_turn_id,
116
+ )
117
+
118
+ async def turn_interrupt(self, turn_id: str) -> None:
119
+ """Interrupt a running turn. See :meth:`CodexClient.turn_interrupt`."""
120
+ await self._client.turn_interrupt(self.thread_id, turn_id)
121
+
122
+ async def turn_stream_structured[ResultType: BaseModel](
123
+ self,
124
+ user_input: str | list[UserInput],
125
+ result_type: type[ResultType],
126
+ *,
127
+ model: str | None = None,
128
+ effort: ReasoningEffort | None = None,
129
+ approval_policy: ApprovalPolicy | None = None,
130
+ cwd: str | None = None,
131
+ sandbox_policy: SandboxMode | dict[str, Any] | None = None,
132
+ personality: Personality | None = None,
133
+ summary: ReasoningSummary | None = None,
134
+ collaboration_mode: CollaborationMode | None = None,
135
+ ) -> ResultType:
136
+ """Structured-output turn. See :meth:`CodexClient.turn_stream_structured`."""
137
+ return await self._client.turn_stream_structured(
138
+ self.thread_id,
139
+ user_input,
140
+ result_type,
141
+ model=model,
142
+ effort=effort,
143
+ approval_policy=approval_policy,
144
+ cwd=cwd,
145
+ sandbox_policy=sandbox_policy,
146
+ personality=personality,
147
+ summary=summary,
148
+ collaboration_mode=collaboration_mode,
149
+ )
150
+
151
+ # -- Thread operations ---------------------------------------------------
152
+
153
+ async def read(self, *, include_turns: bool = False) -> ThreadReadResponse:
154
+ """Read thread data. See :meth:`CodexClient.thread_read`."""
155
+ return await self._client.thread_read(self.thread_id, include_turns=include_turns)
156
+
157
+ async def unsubscribe(self) -> ThreadUnsubscribeResponse:
158
+ """Unsubscribe from thread events. See :meth:`CodexClient.thread_unsubscribe`."""
159
+ return await self._client.thread_unsubscribe(self.thread_id)
160
+
161
+ async def archive(self) -> None:
162
+ """Archive this thread. See :meth:`CodexClient.thread_archive`."""
163
+ await self._client.thread_archive(self.thread_id)
164
+
165
+ async def unarchive(self) -> ThreadUnarchiveResponse:
166
+ """Unarchive this thread. See :meth:`CodexClient.thread_unarchive`."""
167
+ return await self._client.thread_unarchive(self.thread_id)
168
+
169
+ async def set_name(self, name: str) -> None:
170
+ """Set thread name. See :meth:`CodexClient.thread_set_name`."""
171
+ await self._client.thread_set_name(self.thread_id, name)
172
+
173
+ async def compact_start(self) -> None:
174
+ """Trigger context compaction. See :meth:`CodexClient.thread_compact_start`."""
175
+ await self._client.thread_compact_start(self.thread_id)
176
+
177
+ async def rollback(self, turns: int) -> ThreadRollbackResponse:
178
+ """Rollback last N turns. See :meth:`CodexClient.thread_rollback`."""
179
+ return await self._client.thread_rollback(self.thread_id, turns)
180
+
181
+ async def rollback_to_turn(self, turn_id: str) -> ThreadRollbackResponse:
182
+ """Rollback to a specific turn. See :meth:`CodexClient.thread_rollback_to_turn`."""
183
+ return await self._client.thread_rollback_to_turn(self.thread_id, turn_id)
184
+
185
+ # -- Review --------------------------------------------------------------
186
+
187
+ async def review_start(
188
+ self,
189
+ target: ReviewTarget,
190
+ *,
191
+ delivery: ReviewDelivery | None = None,
192
+ ) -> ReviewStartResponse:
193
+ """Start a code review. See :meth:`CodexClient.review_start`."""
194
+ return await self._client.review_start(self.thread_id, target, delivery=delivery)
195
+
196
+ # -- Fork ----------------------------------------------------------------
197
+
198
+ async def fork(
199
+ self,
200
+ *,
201
+ path: str | None = None,
202
+ cwd: str | None = None,
203
+ model: str | None = None,
204
+ model_provider: str | None = None,
205
+ base_instructions: str | None = None,
206
+ developer_instructions: str | None = None,
207
+ approval_policy: ApprovalPolicy | None = None,
208
+ sandbox: SandboxMode | None = None,
209
+ config: dict[str, Any] | None = None,
210
+ tools: list[ToolConfig] | None = None,
211
+ code_mode: bool | None = None,
212
+ personality: Personality | None = None,
213
+ turn_id: str | None = None,
214
+ ) -> Session:
215
+ """Fork this thread. See :meth:`CodexClient.thread_fork`."""
216
+ return await self._client.thread_fork(
217
+ self.thread_id,
218
+ path=path,
219
+ cwd=cwd,
220
+ model=model,
221
+ model_provider=model_provider,
222
+ base_instructions=base_instructions,
223
+ developer_instructions=developer_instructions,
224
+ approval_policy=approval_policy,
225
+ sandbox=sandbox,
226
+ config=config,
227
+ tools=tools,
228
+ code_mode=code_mode,
229
+ personality=personality,
230
+ turn_id=turn_id,
231
+ )
232
+
233
+ def __repr__(self) -> str:
234
+ return f"Session(thread_id={self.thread_id!r})"
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes