codexed 0.0.9__tar.gz → 0.1.1__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 (33) hide show
  1. {codexed-0.0.9 → codexed-0.1.1}/PKG-INFO +1 -1
  2. {codexed-0.0.9 → codexed-0.1.1}/pyproject.toml +1 -1
  3. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/client.py +36 -3
  4. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/models/__init__.py +124 -0
  5. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/models/events.py +141 -0
  6. codexed-0.1.1/src/codexed/models/fuzzy_search.py +106 -0
  7. codexed-0.1.1/src/codexed/models/hooks.py +88 -0
  8. codexed-0.1.1/src/codexed/models/realtime.py +135 -0
  9. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/models/request_params.py +44 -4
  10. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/models/responses.py +8 -0
  11. codexed-0.1.1/src/codexed/models/terminal.py +84 -0
  12. {codexed-0.0.9 → codexed-0.1.1}/LICENSE +0 -0
  13. {codexed-0.0.9 → codexed-0.1.1}/README.md +0 -0
  14. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/README.md +0 -0
  15. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/__init__.py +0 -0
  16. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/exceptions.py +0 -0
  17. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/helpers.py +0 -0
  18. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/log.py +0 -0
  19. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/models/base.py +0 -0
  20. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/models/codex_types.py +0 -0
  21. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/models/command_action.py +0 -0
  22. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/models/event_data.py +0 -0
  23. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/models/mcp_server.py +0 -0
  24. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/models/misc.py +0 -0
  25. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/models/response_item.py +0 -0
  26. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/models/thread_item.py +0 -0
  27. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/models/thread_status.py +0 -0
  28. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/models/token_usage.py +0 -0
  29. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/models/tool_config.py +0 -0
  30. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/models/user_input.py +0 -0
  31. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/models/web_search.py +0 -0
  32. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/py.typed +0 -0
  33. {codexed-0.0.9 → codexed-0.1.1}/src/codexed/request_handlers.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: codexed
3
- Version: 0.0.9
3
+ Version: 0.1.1
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.0.9"
5
+ version = "0.1.1"
6
6
  description = "Alternative codex app-server client"
7
7
  readme = "README.md"
8
8
  requires-python = ">=3.13"
@@ -378,6 +378,7 @@ class CodexClient:
378
378
  on_user_input: UserInputHandler | None = None,
379
379
  on_dynamic_tool_call: DynamicToolCallHandler | None = None,
380
380
  on_mcp_elicitation: McpElicitationHandler | None = None,
381
+ mcp_elicitation_for_approvals: bool = False,
381
382
  ) -> None:
382
383
  """Initialize the Codex app-server client.
383
384
 
@@ -392,6 +393,13 @@ class CodexClient:
392
393
  on_user_input: Handler for tool user input requests.
393
394
  on_dynamic_tool_call: Handler for dynamic tool call requests.
394
395
  on_mcp_elicitation: Handler for MCP elicitation requests.
396
+ mcp_elicitation_for_approvals: If True, enables the Codex
397
+ ``tool_call_mcp_elicitation`` feature flag which routes MCP tool
398
+ approval prompts through ``mcpServer/elicitation/request`` instead
399
+ of ``item/tool/requestUserInput``. Requires *on_mcp_elicitation*
400
+ to handle approvals (the schema is empty; context is in ``_meta``).
401
+ Default is False because the default elicitation handler auto-declines,
402
+ which would break MCP tool approvals.
395
403
  """
396
404
  self._codex_command = codex_command
397
405
  self._profile = profile
@@ -405,6 +413,8 @@ class CodexClient:
405
413
  self._reader_task: asyncio.Task[None] | None = None
406
414
  self._writer_lock = asyncio.Lock()
407
415
  self._active_threads: set[str] = set()
416
+ self._mcp_elicitation_enabled = on_mcp_elicitation is not None
417
+ self._mcp_elicitation_for_approvals = mcp_elicitation_for_approvals
408
418
  self._server_request_handlers: dict[str, ServerRequestHandler] = {}
409
419
  if on_approval:
410
420
  self.register_handler(SERVER_REQUEST_COMMAND_APPROVAL, on_approval) # type: ignore[arg-type]
@@ -502,11 +512,16 @@ class CodexClient:
502
512
  tools: list[ToolConfig] | None,
503
513
  code_mode: bool | None,
504
514
  mcp_servers: Mapping[str, McpServerConfig] | None = None,
515
+ mcp_elicitation_for_approvals: bool = False,
505
516
  ) -> dict[str, Any] | None:
506
517
  """Merge tools, code_mode, and mcp_servers into a config dict."""
507
518
  merged = dict(config) if config else {}
508
519
  if code_mode is not None:
509
520
  merged.setdefault("features", {})["code_mode"] = code_mode
521
+ merged.setdefault("features", {})["codex_hooks"] = True
522
+ merged.setdefault("features", {})["realtime_conversation"] = True
523
+ if mcp_elicitation_for_approvals:
524
+ merged.setdefault("features", {})["tool_call_mcp_elicitation"] = True
510
525
  if tools is not None:
511
526
  from codexed.models.tool_config import tools_to_config_dict
512
527
 
@@ -572,7 +587,13 @@ class CodexClient:
572
587
  developer_instructions=developer_instructions,
573
588
  approval_policy=approval_policy,
574
589
  sandbox=sandbox,
575
- config=self._merge_config(config, tools, code_mode, mcp_servers),
590
+ config=self._merge_config(
591
+ config,
592
+ tools,
593
+ code_mode,
594
+ mcp_servers,
595
+ mcp_elicitation_for_approvals=self._mcp_elicitation_for_approvals,
596
+ ),
576
597
  service_name=service_name,
577
598
  personality=personality,
578
599
  ephemeral=ephemeral,
@@ -631,7 +652,13 @@ class CodexClient:
631
652
  developer_instructions=developer_instructions,
632
653
  approval_policy=approval_policy,
633
654
  sandbox=sandbox,
634
- config=self._merge_config(config, tools, code_mode, mcp_servers),
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
+ ),
635
662
  personality=personality,
636
663
  )
637
664
  result = await self._send_request("thread/resume", params)
@@ -690,7 +717,13 @@ class CodexClient:
690
717
  developer_instructions=developer_instructions,
691
718
  approval_policy=approval_policy,
692
719
  sandbox=sandbox,
693
- config=self._merge_config(config, tools, code_mode, mcp_servers),
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
+ ),
694
727
  personality=personality,
695
728
  )
696
729
  result = await self._send_request("thread/fork", params)
@@ -109,6 +109,61 @@ from codexed.models.event_data import (
109
109
  TurnStartedData,
110
110
  WindowsWorldWritableWarningData,
111
111
  )
112
+ from codexed.models.hooks import (
113
+ HookCompletedData,
114
+ HookEventName,
115
+ HookExecutionMode,
116
+ HookHandlerType,
117
+ HookOutputEntry,
118
+ HookOutputEntryKind,
119
+ HookRunStatus,
120
+ HookRunSummary,
121
+ HookScope,
122
+ HookStartedData,
123
+ )
124
+ from codexed.models.fuzzy_search import (
125
+ FuzzyFileSearchMatchType,
126
+ FuzzyFileSearchParams,
127
+ FuzzyFileSearchResponse,
128
+ FuzzyFileSearchResult,
129
+ FuzzyFileSearchSessionCompletedData,
130
+ FuzzyFileSearchSessionStartParams,
131
+ FuzzyFileSearchSessionStartResponse,
132
+ FuzzyFileSearchSessionStopParams,
133
+ FuzzyFileSearchSessionStopResponse,
134
+ FuzzyFileSearchSessionUpdateParams,
135
+ FuzzyFileSearchSessionUpdateResponse,
136
+ FuzzyFileSearchSessionUpdatedData,
137
+ )
138
+ from codexed.models.realtime import (
139
+ RealtimeAppendAudioParams,
140
+ RealtimeAppendAudioResponse,
141
+ RealtimeAppendTextParams,
142
+ RealtimeAppendTextResponse,
143
+ RealtimeAudioChunk,
144
+ RealtimeClosedData,
145
+ RealtimeConversationVersion,
146
+ RealtimeErrorData,
147
+ RealtimeItemAddedData,
148
+ RealtimeOutputAudioDeltaData,
149
+ RealtimeStartedData,
150
+ RealtimeStartParams,
151
+ RealtimeStartResponse,
152
+ RealtimeStopParams,
153
+ RealtimeStopResponse,
154
+ RealtimeTranscriptUpdatedData,
155
+ )
156
+ from codexed.models.terminal import (
157
+ CommandExecOutputStream,
158
+ CommandExecOutputDeltaData,
159
+ CommandExecResizeParams,
160
+ CommandExecResizeResponse,
161
+ CommandExecTerminalSize,
162
+ CommandExecTerminateParams,
163
+ CommandExecTerminateResponse,
164
+ CommandExecWriteParams,
165
+ CommandExecWriteResponse,
166
+ )
112
167
  from codexed.models.events import (
113
168
  AccountLoginCompletedEvent,
114
169
  AccountRateLimitsUpdatedEvent,
@@ -122,6 +177,17 @@ from codexed.models.events import (
122
177
  ConfigWarningEvent,
123
178
  ContextCompactedEvent,
124
179
  DeltaEvent,
180
+ HookCompletedEvent,
181
+ HookStartedEvent,
182
+ CommandExecOutputDeltaEvent,
183
+ FuzzyFileSearchSessionCompletedEvent,
184
+ FuzzyFileSearchSessionUpdatedEvent,
185
+ RealtimeClosedEvent,
186
+ RealtimeErrorEvent,
187
+ RealtimeItemAddedEvent,
188
+ RealtimeOutputAudioDeltaEvent,
189
+ RealtimeStartedEvent,
190
+ RealtimeTranscriptUpdatedEvent,
125
191
  DeprecationNoticeEvent,
126
192
  ErrorEvent,
127
193
  EventType,
@@ -457,8 +523,18 @@ __all__ = [
457
523
  "CommandActionRead",
458
524
  "CommandActionSearch",
459
525
  "CommandActionUnknown",
526
+ "CommandExecOutputDeltaData",
527
+ "CommandExecOutputDeltaEvent",
528
+ "CommandExecOutputStream",
460
529
  "CommandExecParams",
530
+ "CommandExecResizeParams",
531
+ "CommandExecResizeResponse",
461
532
  "CommandExecResponse",
533
+ "CommandExecTerminalSize",
534
+ "CommandExecTerminateParams",
535
+ "CommandExecTerminateResponse",
536
+ "CommandExecWriteParams",
537
+ "CommandExecWriteResponse",
462
538
  "CommandExecutionOutputDeltaData",
463
539
  "CommandExecutionOutputDeltaEvent",
464
540
  "CommandExecutionRequestApprovalParams",
@@ -536,6 +612,20 @@ __all__ = [
536
612
  "FunctionCallOutputPayload",
537
613
  "FunctionCallOutputResponseItem",
538
614
  "FunctionCallResponseItem",
615
+ "FuzzyFileSearchMatchType",
616
+ "FuzzyFileSearchParams",
617
+ "FuzzyFileSearchResponse",
618
+ "FuzzyFileSearchResult",
619
+ "FuzzyFileSearchSessionCompletedData",
620
+ "FuzzyFileSearchSessionCompletedEvent",
621
+ "FuzzyFileSearchSessionStartParams",
622
+ "FuzzyFileSearchSessionStartResponse",
623
+ "FuzzyFileSearchSessionStopParams",
624
+ "FuzzyFileSearchSessionStopResponse",
625
+ "FuzzyFileSearchSessionUpdateParams",
626
+ "FuzzyFileSearchSessionUpdateResponse",
627
+ "FuzzyFileSearchSessionUpdatedData",
628
+ "FuzzyFileSearchSessionUpdatedEvent",
539
629
  "GetAccountParams",
540
630
  "GetAccountRateLimitsResponse",
541
631
  "GetAccountResponse",
@@ -543,6 +633,18 @@ __all__ = [
543
633
  "GhostSnapshotResponseItem",
544
634
  "GitInfo",
545
635
  "GrepFilesToolConfig",
636
+ "HookCompletedData",
637
+ "HookCompletedEvent",
638
+ "HookEventName",
639
+ "HookExecutionMode",
640
+ "HookHandlerType",
641
+ "HookOutputEntry",
642
+ "HookOutputEntryKind",
643
+ "HookRunStatus",
644
+ "HookRunSummary",
645
+ "HookScope",
646
+ "HookStartedData",
647
+ "HookStartedEvent",
546
648
  "HttpMcpServer",
547
649
  "ImageGenerationCallResponseItem",
548
650
  "ImageGenerationToolConfig",
@@ -625,6 +727,28 @@ __all__ = [
625
727
  "ReadFileToolConfig",
626
728
  "ReadOnlyAccess",
627
729
  "ReadOnlySandboxPolicy",
730
+ "RealtimeAppendAudioParams",
731
+ "RealtimeAppendAudioResponse",
732
+ "RealtimeAppendTextParams",
733
+ "RealtimeAppendTextResponse",
734
+ "RealtimeAudioChunk",
735
+ "RealtimeClosedData",
736
+ "RealtimeClosedEvent",
737
+ "RealtimeConversationVersion",
738
+ "RealtimeErrorData",
739
+ "RealtimeErrorEvent",
740
+ "RealtimeItemAddedData",
741
+ "RealtimeItemAddedEvent",
742
+ "RealtimeOutputAudioDeltaData",
743
+ "RealtimeOutputAudioDeltaEvent",
744
+ "RealtimeStartParams",
745
+ "RealtimeStartResponse",
746
+ "RealtimeStartedData",
747
+ "RealtimeStartedEvent",
748
+ "RealtimeStopParams",
749
+ "RealtimeStopResponse",
750
+ "RealtimeTranscriptUpdatedData",
751
+ "RealtimeTranscriptUpdatedEvent",
628
752
  "ReasoningEffort",
629
753
  "ReasoningEffortOption",
630
754
  "ReasoningResponseItem",
@@ -52,6 +52,20 @@ from codexed.models.event_data import ( # noqa: TC001
52
52
  TurnStartedData,
53
53
  WindowsWorldWritableWarningData,
54
54
  )
55
+ from codexed.models.fuzzy_search import ( # noqa: TC001
56
+ FuzzyFileSearchSessionCompletedData,
57
+ FuzzyFileSearchSessionUpdatedData,
58
+ )
59
+ from codexed.models.hooks import HookCompletedData, HookStartedData # noqa: TC001
60
+ from codexed.models.realtime import ( # noqa: TC001
61
+ RealtimeClosedData,
62
+ RealtimeErrorData,
63
+ RealtimeItemAddedData,
64
+ RealtimeOutputAudioDeltaData,
65
+ RealtimeStartedData,
66
+ RealtimeTranscriptUpdatedData,
67
+ )
68
+ from codexed.models.terminal import CommandExecOutputDeltaData # noqa: TC001
55
69
 
56
70
 
57
71
  if TYPE_CHECKING:
@@ -174,6 +188,103 @@ class TurnPlanUpdatedEvent(CodexBaseModel):
174
188
  data: TurnPlanUpdatedData
175
189
 
176
190
 
191
+ # ============================================================================
192
+ # Hook events
193
+ # ============================================================================
194
+
195
+
196
+ class HookStartedEvent(CodexBaseModel):
197
+ """Hook started event."""
198
+
199
+ event_type: Literal["hook/started"] = "hook/started"
200
+ data: HookStartedData
201
+
202
+
203
+ class HookCompletedEvent(CodexBaseModel):
204
+ """Hook completed event."""
205
+
206
+ event_type: Literal["hook/completed"] = "hook/completed"
207
+ data: HookCompletedData
208
+
209
+
210
+ # ============================================================================
211
+ # Realtime voice events (EXPERIMENTAL)
212
+ # ============================================================================
213
+
214
+
215
+ class RealtimeStartedEvent(CodexBaseModel):
216
+ """Realtime session started event."""
217
+
218
+ event_type: Literal["thread/realtime/started"] = "thread/realtime/started"
219
+ data: RealtimeStartedData
220
+
221
+
222
+ class RealtimeItemAddedEvent(CodexBaseModel):
223
+ """Realtime item added event."""
224
+
225
+ event_type: Literal["thread/realtime/itemAdded"] = "thread/realtime/itemAdded"
226
+ data: RealtimeItemAddedData
227
+
228
+
229
+ class RealtimeTranscriptUpdatedEvent(CodexBaseModel):
230
+ """Realtime transcript updated event."""
231
+
232
+ event_type: Literal["thread/realtime/transcriptUpdated"] = "thread/realtime/transcriptUpdated"
233
+ data: RealtimeTranscriptUpdatedData
234
+
235
+
236
+ class RealtimeOutputAudioDeltaEvent(CodexBaseModel):
237
+ """Realtime output audio delta event."""
238
+
239
+ event_type: Literal["thread/realtime/outputAudio/delta"] = "thread/realtime/outputAudio/delta"
240
+ data: RealtimeOutputAudioDeltaData
241
+
242
+
243
+ class RealtimeErrorEvent(CodexBaseModel):
244
+ """Realtime error event."""
245
+
246
+ event_type: Literal["thread/realtime/error"] = "thread/realtime/error"
247
+ data: RealtimeErrorData
248
+
249
+
250
+ class RealtimeClosedEvent(CodexBaseModel):
251
+ """Realtime session closed event."""
252
+
253
+ event_type: Literal["thread/realtime/closed"] = "thread/realtime/closed"
254
+ data: RealtimeClosedData
255
+
256
+
257
+ # ============================================================================
258
+ # Terminal control events
259
+ # ============================================================================
260
+
261
+
262
+ class CommandExecOutputDeltaEvent(CodexBaseModel):
263
+ """Command exec output delta event (streaming stdout/stderr)."""
264
+
265
+ event_type: Literal["command/exec/outputDelta"] = "command/exec/outputDelta"
266
+ data: CommandExecOutputDeltaData
267
+
268
+
269
+ # ============================================================================
270
+ # Fuzzy file search events (EXPERIMENTAL)
271
+ # ============================================================================
272
+
273
+
274
+ class FuzzyFileSearchSessionUpdatedEvent(CodexBaseModel):
275
+ """Fuzzy file search session updated with results."""
276
+
277
+ event_type: Literal["fuzzyFileSearch/sessionUpdated"] = "fuzzyFileSearch/sessionUpdated"
278
+ data: FuzzyFileSearchSessionUpdatedData
279
+
280
+
281
+ class FuzzyFileSearchSessionCompletedEvent(CodexBaseModel):
282
+ """Fuzzy file search session completed."""
283
+
284
+ event_type: Literal["fuzzyFileSearch/sessionCompleted"] = "fuzzyFileSearch/sessionCompleted"
285
+ data: FuzzyFileSearchSessionCompletedData
286
+
287
+
177
288
  # ============================================================================
178
289
  # Item lifecycle events
179
290
  # ============================================================================
@@ -435,6 +546,21 @@ CodexEvent = Annotated[
435
546
  | TurnErrorEvent
436
547
  | TurnDiffUpdatedEvent
437
548
  | TurnPlanUpdatedEvent
549
+ # Hook events
550
+ | HookStartedEvent
551
+ | HookCompletedEvent
552
+ # Realtime voice events (EXPERIMENTAL)
553
+ | RealtimeStartedEvent
554
+ | RealtimeItemAddedEvent
555
+ | RealtimeTranscriptUpdatedEvent
556
+ | RealtimeOutputAudioDeltaEvent
557
+ | RealtimeErrorEvent
558
+ | RealtimeClosedEvent
559
+ # Terminal control events
560
+ | CommandExecOutputDeltaEvent
561
+ # Fuzzy file search events (EXPERIMENTAL)
562
+ | FuzzyFileSearchSessionUpdatedEvent
563
+ | FuzzyFileSearchSessionCompletedEvent
438
564
  # Item lifecycle
439
565
  | ItemStartedEvent
440
566
  | ItemCompletedEvent
@@ -502,6 +628,21 @@ EventType = Literal[
502
628
  "turn/error",
503
629
  "turn/diff/updated",
504
630
  "turn/plan/updated",
631
+ # Hook events
632
+ "hook/started",
633
+ "hook/completed",
634
+ # Realtime voice events (EXPERIMENTAL)
635
+ "thread/realtime/started",
636
+ "thread/realtime/itemAdded",
637
+ "thread/realtime/transcriptUpdated",
638
+ "thread/realtime/outputAudio/delta",
639
+ "thread/realtime/error",
640
+ "thread/realtime/closed",
641
+ # Terminal control events
642
+ "command/exec/outputDelta",
643
+ # Fuzzy file search events (EXPERIMENTAL)
644
+ "fuzzyFileSearch/sessionUpdated",
645
+ "fuzzyFileSearch/sessionCompleted",
505
646
  # Item lifecycle
506
647
  "item/started",
507
648
  "item/completed",
@@ -0,0 +1,106 @@
1
+ """Fuzzy file search models for the Codex app-server protocol.
2
+
3
+ EXPERIMENTAL — Session-based fuzzy file search. Start a session with roots,
4
+ update with queries, and receive incremental results via notifications.
5
+ Also includes the legacy one-shot search API.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from typing import Literal
11
+
12
+ from codexed.models.base import CodexBaseModel
13
+
14
+
15
+ # ============================================================================
16
+ # Supporting types
17
+ # ============================================================================
18
+
19
+ FuzzyFileSearchMatchType = Literal["file", "directory"]
20
+ """Whether the match is a file or directory."""
21
+
22
+
23
+ class FuzzyFileSearchResult(CodexBaseModel):
24
+ """A single fuzzy file search result."""
25
+
26
+ root: str
27
+ path: str
28
+ match_type: FuzzyFileSearchMatchType
29
+ file_name: str
30
+ score: int
31
+ indices: list[int] | None = None
32
+
33
+
34
+ # ============================================================================
35
+ # Legacy one-shot search
36
+ # ============================================================================
37
+
38
+
39
+ class FuzzyFileSearchParams(CodexBaseModel):
40
+ """Params for the legacy fuzzyFileSearch request."""
41
+
42
+ query: str
43
+ roots: list[str]
44
+ cancellation_token: str | None = None
45
+
46
+
47
+ class FuzzyFileSearchResponse(CodexBaseModel):
48
+ """Response for the legacy fuzzyFileSearch request."""
49
+
50
+ files: list[FuzzyFileSearchResult]
51
+
52
+
53
+ # ============================================================================
54
+ # Session-based search (EXPERIMENTAL)
55
+ # ============================================================================
56
+
57
+
58
+ class FuzzyFileSearchSessionStartParams(CodexBaseModel):
59
+ """Params for fuzzyFileSearch/sessionStart request."""
60
+
61
+ session_id: str
62
+ roots: list[str]
63
+
64
+
65
+ class FuzzyFileSearchSessionStartResponse(CodexBaseModel):
66
+ """Response for fuzzyFileSearch/sessionStart request."""
67
+
68
+
69
+ class FuzzyFileSearchSessionUpdateParams(CodexBaseModel):
70
+ """Params for fuzzyFileSearch/sessionUpdate request."""
71
+
72
+ session_id: str
73
+ query: str
74
+
75
+
76
+ class FuzzyFileSearchSessionUpdateResponse(CodexBaseModel):
77
+ """Response for fuzzyFileSearch/sessionUpdate request."""
78
+
79
+
80
+ class FuzzyFileSearchSessionStopParams(CodexBaseModel):
81
+ """Params for fuzzyFileSearch/sessionStop request."""
82
+
83
+ session_id: str
84
+
85
+
86
+ class FuzzyFileSearchSessionStopResponse(CodexBaseModel):
87
+ """Response for fuzzyFileSearch/sessionStop request."""
88
+
89
+
90
+ # ============================================================================
91
+ # Server notification data
92
+ # ============================================================================
93
+
94
+
95
+ class FuzzyFileSearchSessionUpdatedData(CodexBaseModel):
96
+ """Data for fuzzyFileSearch/sessionUpdated notification."""
97
+
98
+ session_id: str
99
+ query: str
100
+ files: list[FuzzyFileSearchResult]
101
+
102
+
103
+ class FuzzyFileSearchSessionCompletedData(CodexBaseModel):
104
+ """Data for fuzzyFileSearch/sessionCompleted notification."""
105
+
106
+ session_id: str
@@ -0,0 +1,88 @@
1
+ """Hook models for the Codex app-server protocol.
2
+
3
+ Hooks are user-defined commands that run at specific lifecycle events
4
+ (session start, user prompt submit, stop). They can inspect context,
5
+ inject system messages, or block operations.
6
+
7
+ See: https://github.com/openai/codex/tree/main/codex-rs/hooks
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from typing import Literal
13
+
14
+ from codexed.models.base import CodexBaseModel
15
+
16
+
17
+ # ============================================================================
18
+ # Enums / Literal types
19
+ # ============================================================================
20
+
21
+ HookEventName = Literal["sessionStart", "userPromptSubmit", "stop"]
22
+ """Lifecycle event that triggers hooks."""
23
+
24
+ HookHandlerType = Literal["command", "prompt", "agent"]
25
+ """How the hook is executed. Only 'command' is currently supported."""
26
+
27
+ HookExecutionMode = Literal["sync", "async"]
28
+ """Whether the hook blocks the operation or runs in the background."""
29
+
30
+ HookScope = Literal["thread", "turn"]
31
+ """Scope of the hook run."""
32
+
33
+ HookRunStatus = Literal["running", "completed", "failed", "blocked", "stopped"]
34
+ """Current execution status of a hook run."""
35
+
36
+ HookOutputEntryKind = Literal["warning", "stop", "feedback", "context", "error"]
37
+ """Kind of output entry produced by a hook."""
38
+
39
+
40
+ # ============================================================================
41
+ # Data models
42
+ # ============================================================================
43
+
44
+
45
+ class HookOutputEntry(CodexBaseModel):
46
+ """Single output entry from a hook run."""
47
+
48
+ kind: HookOutputEntryKind
49
+ text: str
50
+
51
+
52
+ class HookRunSummary(CodexBaseModel):
53
+ """Summary of a hook run, sent with started/completed notifications."""
54
+
55
+ id: str
56
+ event_name: HookEventName
57
+ handler_type: HookHandlerType
58
+ execution_mode: HookExecutionMode
59
+ scope: HookScope
60
+ source_path: str
61
+ display_order: int
62
+ status: HookRunStatus
63
+ status_message: str | None = None
64
+ started_at: int
65
+ completed_at: int | None = None
66
+ duration_ms: int | None = None
67
+ entries: list[HookOutputEntry]
68
+
69
+
70
+ # ============================================================================
71
+ # Notification data (params for hook/started and hook/completed)
72
+ # ============================================================================
73
+
74
+
75
+ class HookStartedData(CodexBaseModel):
76
+ """Data for hook/started notification."""
77
+
78
+ thread_id: str
79
+ turn_id: str | None = None
80
+ run: HookRunSummary
81
+
82
+
83
+ class HookCompletedData(CodexBaseModel):
84
+ """Data for hook/completed notification."""
85
+
86
+ thread_id: str
87
+ turn_id: str | None = None
88
+ run: HookRunSummary
@@ -0,0 +1,135 @@
1
+ """Realtime voice conversation models for the Codex app-server protocol.
2
+
3
+ EXPERIMENTAL - All realtime types are experimental and subject to change.
4
+ Realtime enables voice conversations with the Codex agent, supporting
5
+ bidirectional audio streaming, text input, and transcript updates.
6
+
7
+ See: https://github.com/openai/codex/tree/main/codex-rs/app-server-protocol
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from typing import Any, Literal
13
+
14
+ from codexed.models.base import CodexBaseModel
15
+
16
+
17
+ # ============================================================================
18
+ # Enums / Literal types
19
+ # ============================================================================
20
+
21
+ RealtimeConversationVersion = Literal["v1", "v2"]
22
+ """Realtime conversation protocol version."""
23
+
24
+
25
+ # ============================================================================
26
+ # Audio data
27
+ # ============================================================================
28
+
29
+
30
+ class RealtimeAudioChunk(CodexBaseModel):
31
+ """Audio chunk for realtime streaming (base64-encoded PCM data)."""
32
+
33
+ data: str
34
+ sample_rate: int
35
+ num_channels: int
36
+ samples_per_channel: int | None = None
37
+ item_id: str | None = None
38
+
39
+
40
+ # ============================================================================
41
+ # Client request params / responses
42
+ # ============================================================================
43
+
44
+
45
+ class RealtimeStartParams(CodexBaseModel):
46
+ """Params for thread/realtime/start request."""
47
+
48
+ thread_id: str
49
+ prompt: str
50
+ session_id: str | None = None
51
+
52
+
53
+ class RealtimeStartResponse(CodexBaseModel):
54
+ """Response for thread/realtime/start request."""
55
+
56
+
57
+ class RealtimeAppendAudioParams(CodexBaseModel):
58
+ """Params for thread/realtime/appendAudio request."""
59
+
60
+ thread_id: str
61
+ audio: RealtimeAudioChunk
62
+
63
+
64
+ class RealtimeAppendAudioResponse(CodexBaseModel):
65
+ """Response for thread/realtime/appendAudio request."""
66
+
67
+
68
+ class RealtimeAppendTextParams(CodexBaseModel):
69
+ """Params for thread/realtime/appendText request."""
70
+
71
+ thread_id: str
72
+ text: str
73
+
74
+
75
+ class RealtimeAppendTextResponse(CodexBaseModel):
76
+ """Response for thread/realtime/appendText request."""
77
+
78
+
79
+ class RealtimeStopParams(CodexBaseModel):
80
+ """Params for thread/realtime/stop request."""
81
+
82
+ thread_id: str
83
+
84
+
85
+ class RealtimeStopResponse(CodexBaseModel):
86
+ """Response for thread/realtime/stop request."""
87
+
88
+
89
+ # ============================================================================
90
+ # Server notification data
91
+ # ============================================================================
92
+
93
+
94
+ class RealtimeStartedData(CodexBaseModel):
95
+ """Data for thread/realtime/started notification."""
96
+
97
+ thread_id: str
98
+ session_id: str | None = None
99
+ version: RealtimeConversationVersion
100
+
101
+
102
+ class RealtimeItemAddedData(CodexBaseModel):
103
+ """Data for thread/realtime/itemAdded notification."""
104
+
105
+ thread_id: str
106
+ item: Any
107
+
108
+
109
+ class RealtimeTranscriptUpdatedData(CodexBaseModel):
110
+ """Data for thread/realtime/transcriptUpdated notification."""
111
+
112
+ thread_id: str
113
+ role: str
114
+ text: str
115
+
116
+
117
+ class RealtimeOutputAudioDeltaData(CodexBaseModel):
118
+ """Data for thread/realtime/outputAudio/delta notification."""
119
+
120
+ thread_id: str
121
+ audio: RealtimeAudioChunk
122
+
123
+
124
+ class RealtimeErrorData(CodexBaseModel):
125
+ """Data for thread/realtime/error notification."""
126
+
127
+ thread_id: str
128
+ message: str
129
+
130
+
131
+ class RealtimeClosedData(CodexBaseModel):
132
+ """Data for thread/realtime/closed notification."""
133
+
134
+ thread_id: str
135
+ reason: str | None = None
@@ -31,6 +31,7 @@ from codexed.models.misc import ( # noqa: TC001
31
31
  ToolRequestUserInputQuestion,
32
32
  )
33
33
  from codexed.models.response_item import ResponseItem # noqa: TC001
34
+ from codexed.models.terminal import CommandExecTerminalSize # noqa: TC001
34
35
  from codexed.models.user_input import UserInput # noqa: TC001
35
36
 
36
37
 
@@ -280,9 +281,18 @@ class CommandExecParams(CodexBaseModel):
280
281
  """Parameters for command/exec request."""
281
282
 
282
283
  command: list[str]
283
- cwd: str | None = None
284
- sandbox_policy: dict[str, Any] | None = None # Sandbox config - flexible structure
284
+ process_id: str | None = None
285
+ tty: bool = False
286
+ stream_stdin: bool = False
287
+ stream_stdout_stderr: bool = False
288
+ output_bytes_cap: int | None = None
289
+ disable_output_cap: bool = False
290
+ disable_timeout: bool = False
285
291
  timeout_ms: int | None = None
292
+ cwd: str | None = None
293
+ env: dict[str, str | None] | None = None
294
+ size: CommandExecTerminalSize | None = None
295
+ sandbox_policy: dict[str, Any] | None = None
286
296
 
287
297
 
288
298
  class ModelListParams(CodexBaseModel):
@@ -511,6 +521,26 @@ class _McpElicitationBase(CodexBaseModel):
511
521
  turn_id: str | None = None
512
522
  server_name: str
513
523
  meta: Any | None = None
524
+ """Optional metadata from the server.
525
+
526
+ For MCP tool approval requests (when ``tool_call_mcp_elicitation`` is enabled),
527
+ this contains:
528
+
529
+ - ``kind`` (str): Always ``"mcp_tool_call"`` for tool approvals.
530
+ - ``persist`` (str | list[str]): Allowed persistence options —
531
+ ``"session"`` (remember for this session) and/or ``"always"``
532
+ (remember permanently).
533
+ - ``tool_title`` (str, optional): Human-readable tool name.
534
+ - ``tool_description`` (str, optional): Tool description.
535
+ - ``tool_params`` (dict, optional): The tool call arguments.
536
+ - ``tool_params_display`` (list, optional): Rendered parameter display.
537
+ - ``source`` (str, optional): ``"connector"`` if from a ChatGPT App.
538
+ - ``connector_id``, ``connector_name``, ``connector_description``
539
+ (str, optional): Connector details when source is ``"connector"``.
540
+
541
+ For regular MCP server elicitations (auth flows etc.), the meta content
542
+ is defined by the MCP server itself.
543
+ """
514
544
  message: str
515
545
 
516
546
 
@@ -521,10 +551,13 @@ class McpElicitationFormParams(_McpElicitationBase):
521
551
  requested_schema: dict[str, Any]
522
552
 
523
553
  def to_mcp(self) -> mcp.types.ElicitRequestFormParams:
524
- return mcp.types.ElicitRequestFormParams(
554
+ params = mcp.types.ElicitRequestFormParams(
525
555
  message=self.message,
526
556
  requestedSchema=self.requested_schema,
527
557
  )
558
+ if self.meta is not None:
559
+ params.meta = mcp.types.RequestParams.Meta(**self.meta)
560
+ return params
528
561
 
529
562
  @classmethod
530
563
  def from_mcp(
@@ -535,9 +568,11 @@ class McpElicitationFormParams(_McpElicitationBase):
535
568
  turn_id: str | None = None,
536
569
  ) -> McpElicitationFormParams:
537
570
  """Create from MCP ElicitRequestFormParams."""
571
+ meta = params.meta.model_dump(exclude={"progressToken"}) if params.meta else None
538
572
  return cls(
539
573
  message=params.message,
540
574
  requested_schema=dict(params.requestedSchema),
575
+ meta=meta,
541
576
  thread_id=thread_id,
542
577
  server_name=server_name,
543
578
  turn_id=turn_id,
@@ -552,11 +587,14 @@ class McpElicitationUrlParams(_McpElicitationBase):
552
587
  elicitation_id: str
553
588
 
554
589
  def to_mcp(self) -> mcp.types.ElicitRequestURLParams:
555
- return mcp.types.ElicitRequestURLParams(
590
+ params = mcp.types.ElicitRequestURLParams(
556
591
  message=self.message,
557
592
  url=self.url,
558
593
  elicitationId=self.elicitation_id,
559
594
  )
595
+ if self.meta is not None:
596
+ params.meta = mcp.types.RequestParams.Meta(**self.meta)
597
+ return params
560
598
 
561
599
  @classmethod
562
600
  def from_mcp(
@@ -567,10 +605,12 @@ class McpElicitationUrlParams(_McpElicitationBase):
567
605
  turn_id: str | None = None,
568
606
  ) -> McpElicitationUrlParams:
569
607
  """Create from MCP ElicitRequestURLParams."""
608
+ meta = params.meta.model_dump(exclude={"progressToken"}) if params.meta else None
570
609
  return cls(
571
610
  message=params.message,
572
611
  url=params.url,
573
612
  elicitation_id=params.elicitationId,
613
+ meta=meta,
574
614
  thread_id=thread_id,
575
615
  server_name=server_name,
576
616
  turn_id=turn_id,
@@ -62,6 +62,14 @@ class McpServerElicitationResponse(CodexBaseModel):
62
62
  action: Literal["accept", "decline", "cancel"]
63
63
  content: Any | None = None
64
64
  meta: Any | None = None
65
+ """Optional metadata to include in the response.
66
+
67
+ For MCP tool approval responses, this can contain:
68
+
69
+ - ``persist`` (str): ``"session"`` to remember the approval for
70
+ the current session, or ``"always"`` to remember permanently.
71
+ Must be one of the options listed in the request's ``meta.persist``.
72
+ """
65
73
 
66
74
  def to_mcp(self) -> mcp.types.ElicitResult:
67
75
  return mcp.types.ElicitResult(action=self.action, content=self.content)
@@ -0,0 +1,84 @@
1
+ """Interactive terminal control models for the Codex app-server protocol.
2
+
3
+ These models support the interactive PTY/streaming mode of `command/exec`.
4
+ After starting a command with `stream_stdin=True` or `tty=True`, use
5
+ `command/exec/write` to send stdin, `command/exec/resize` to resize the PTY,
6
+ and `command/exec/terminate` to kill the process. Output arrives as
7
+ `command/exec/outputDelta` notifications.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from typing import Literal
13
+
14
+ from codexed.models.base import CodexBaseModel
15
+
16
+
17
+ # ============================================================================
18
+ # Supporting types
19
+ # ============================================================================
20
+
21
+ CommandExecOutputStream = Literal["stdout", "stderr"]
22
+ """Stream label for command/exec output delta notifications."""
23
+
24
+
25
+ class CommandExecTerminalSize(CodexBaseModel):
26
+ """PTY size in character cells."""
27
+
28
+ rows: int
29
+ cols: int
30
+
31
+
32
+ # ============================================================================
33
+ # Client request params / responses
34
+ # ============================================================================
35
+
36
+
37
+ class CommandExecWriteParams(CodexBaseModel):
38
+ """Params for command/exec/write request — write stdin to a running process."""
39
+
40
+ process_id: str
41
+ delta_base64: str | None = None
42
+ close_stdin: bool = False
43
+
44
+
45
+ class CommandExecWriteResponse(CodexBaseModel):
46
+ """Response for command/exec/write request."""
47
+
48
+
49
+ class CommandExecTerminateParams(CodexBaseModel):
50
+ """Params for command/exec/terminate request — kill a running process."""
51
+
52
+ process_id: str
53
+
54
+
55
+ class CommandExecTerminateResponse(CodexBaseModel):
56
+ """Response for command/exec/terminate request."""
57
+
58
+
59
+ class CommandExecResizeParams(CodexBaseModel):
60
+ """Params for command/exec/resize request — resize a PTY session."""
61
+
62
+ process_id: str
63
+ size: CommandExecTerminalSize
64
+
65
+
66
+ class CommandExecResizeResponse(CodexBaseModel):
67
+ """Response for command/exec/resize request."""
68
+
69
+
70
+ # ============================================================================
71
+ # Server notification data
72
+ # ============================================================================
73
+
74
+
75
+ class CommandExecOutputDeltaData(CodexBaseModel):
76
+ """Data for command/exec/outputDelta notification.
77
+
78
+ Base64-encoded output chunk emitted for a streaming command/exec request.
79
+ """
80
+
81
+ process_id: str
82
+ stream: CommandExecOutputStream
83
+ delta_base64: str
84
+ cap_reached: bool
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes