im_wower
·
2026-03-22
contracts.ts
1export type JsonPrimitive = boolean | number | string | null;
2export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue | undefined };
3
4export type CodexAppServerRequestId = number | string;
5export type CodexAppServerThreadId = string;
6export type CodexAppServerTurnId = string;
7export type CodexAppServerItemId = string;
8export type CodexAppServerProcessId = string;
9
10export const CODEX_APP_SERVER_REQUEST_METHODS = [
11 "initialize",
12 "thread/start",
13 "thread/resume",
14 "turn/start",
15 "turn/steer",
16 "turn/interrupt"
17] as const;
18
19export const CODEX_APP_SERVER_NOTIFICATION_METHODS = [
20 "error",
21 "thread/started",
22 "thread/status/changed",
23 "turn/started",
24 "turn/completed",
25 "turn/diff/updated",
26 "turn/plan/updated",
27 "item/agentMessage/delta",
28 "item/plan/delta",
29 "command/exec/outputDelta"
30] as const;
31
32export type CodexAppServerRequestMethod = (typeof CODEX_APP_SERVER_REQUEST_METHODS)[number];
33export type CodexAppServerNotificationMethod =
34 (typeof CODEX_APP_SERVER_NOTIFICATION_METHODS)[number];
35
36export interface CodexAppServerRpcErrorPayload {
37 code: number;
38 message: string;
39 data?: JsonValue;
40}
41
42export interface CodexAppServerRpcRequest<TParams = unknown> {
43 id: CodexAppServerRequestId;
44 method: string;
45 params?: TParams;
46}
47
48export interface CodexAppServerRpcSuccess<TResult = unknown> {
49 id: CodexAppServerRequestId;
50 result: TResult;
51}
52
53export interface CodexAppServerRpcFailure {
54 id: CodexAppServerRequestId | null;
55 error: CodexAppServerRpcErrorPayload;
56}
57
58export interface CodexAppServerRpcNotification<TParams = unknown> {
59 method: string;
60 params?: TParams;
61}
62
63export type CodexAppServerRpcMessage =
64 | CodexAppServerRpcRequest
65 | CodexAppServerRpcSuccess
66 | CodexAppServerRpcFailure
67 | CodexAppServerRpcNotification;
68
69export interface CodexAppServerClientInfo {
70 name: string;
71 title: string | null;
72 version: string;
73}
74
75export interface CodexAppServerInitializeCapabilities {
76 experimentalApi: boolean;
77 optOutNotificationMethods?: string[] | null;
78}
79
80export interface CodexAppServerInitializeParams {
81 clientInfo: CodexAppServerClientInfo;
82 capabilities: CodexAppServerInitializeCapabilities | null;
83}
84
85export interface CodexAppServerInitializeResult {
86 userAgent: string;
87 platformFamily: string;
88 platformOs: string;
89}
90
91export interface CodexAppServerApprovalPolicyGranular {
92 sandboxApproval: boolean;
93 rules: boolean;
94 skillApproval: boolean;
95 requestPermissions: boolean;
96 mcpElicitations: boolean;
97}
98
99export type CodexAppServerApprovalPolicy =
100 | "untrusted"
101 | "on-failure"
102 | "on-request"
103 | "never"
104 | { granular: CodexAppServerApprovalPolicyGranular };
105
106export type CodexAppServerSandboxMode =
107 | "read-only"
108 | "workspace-write"
109 | "danger-full-access";
110
111export type CodexAppServerThreadActiveFlag = "waitingOnApproval" | "waitingOnUserInput";
112export type CodexAppServerTurnStatus = "completed" | "interrupted" | "failed" | "inProgress";
113export type CodexAppServerPlanStepStatus = "pending" | "inProgress" | "completed";
114export type CodexAppServerCommandOutputStream = "stdout" | "stderr";
115
116export type CodexAppServerReadOnlyAccess =
117 | {
118 type: "restricted";
119 includePlatformDefaults: boolean;
120 readableRoots: string[];
121 }
122 | { type: "fullAccess" };
123
124export type CodexAppServerSandboxPolicy =
125 | {
126 type: "dangerFullAccess";
127 }
128 | {
129 type: "readOnly";
130 access: CodexAppServerReadOnlyAccess;
131 networkAccess: boolean;
132 }
133 | {
134 type: "externalSandbox";
135 networkAccess: "restricted" | "enabled";
136 }
137 | {
138 type: "workspaceWrite";
139 writableRoots: string[];
140 readOnlyAccess: CodexAppServerReadOnlyAccess;
141 networkAccess: boolean;
142 excludeTmpdirEnvVar: boolean;
143 excludeSlashTmp: boolean;
144 };
145
146export type CodexAppServerThreadStatus =
147 | { type: "notLoaded" }
148 | { type: "idle" }
149 | { type: "systemError" }
150 | { type: "active"; activeFlags: CodexAppServerThreadActiveFlag[] };
151
152export interface CodexAppServerTurnError {
153 message: string;
154 codexErrorInfo: JsonValue | null;
155 additionalDetails: string | null;
156}
157
158export interface CodexAppServerPlanStep {
159 step: string;
160 status: CodexAppServerPlanStepStatus;
161}
162
163export interface CodexAppServerTurn {
164 id: CodexAppServerTurnId;
165 status: CodexAppServerTurnStatus;
166 error: CodexAppServerTurnError | null;
167}
168
169export type CodexAppServerThreadSource =
170 | "cli"
171 | "vscode"
172 | "exec"
173 | "mcp"
174 | "unknown"
175 | { custom: string }
176 | { subagent: string };
177
178export interface CodexAppServerThread {
179 id: CodexAppServerThreadId;
180 preview: string;
181 ephemeral: boolean;
182 modelProvider: string;
183 createdAt: number;
184 updatedAt: number;
185 status: CodexAppServerThreadStatus;
186 cwd: string;
187 cliVersion: string;
188 source: CodexAppServerThreadSource;
189 agentNickname?: string | null;
190 agentRole?: string | null;
191 name: string | null;
192 turns?: CodexAppServerTurn[];
193}
194
195export interface CodexAppServerThreadSession {
196 thread: CodexAppServerThread;
197 model: string;
198 modelProvider: string;
199 serviceTier: string | null;
200 cwd: string;
201 approvalPolicy: CodexAppServerApprovalPolicy;
202 sandbox: CodexAppServerSandboxPolicy;
203 reasoningEffort: string | null;
204}
205
206export interface CodexAppServerByteRange {
207 start: number;
208 end: number;
209}
210
211export interface CodexAppServerTextElement {
212 byteRange: CodexAppServerByteRange;
213 placeholder: string | null;
214}
215
216export interface CodexAppServerTextUserInput {
217 type: "text";
218 text: string;
219 text_elements: CodexAppServerTextElement[];
220}
221
222export interface CodexAppServerImageUserInput {
223 type: "image";
224 url: string;
225}
226
227export interface CodexAppServerLocalImageUserInput {
228 type: "localImage";
229 path: string;
230}
231
232export interface CodexAppServerSkillUserInput {
233 type: "skill";
234 name: string;
235 path: string;
236}
237
238export interface CodexAppServerMentionUserInput {
239 type: "mention";
240 name: string;
241 path: string;
242}
243
244export type CodexAppServerUserInput =
245 | CodexAppServerTextUserInput
246 | CodexAppServerImageUserInput
247 | CodexAppServerLocalImageUserInput
248 | CodexAppServerSkillUserInput
249 | CodexAppServerMentionUserInput;
250
251export interface CodexAppServerThreadStartParams {
252 model?: string | null;
253 modelProvider?: string | null;
254 serviceTier?: string | null;
255 cwd?: string | null;
256 approvalPolicy?: CodexAppServerApprovalPolicy | null;
257 sandbox?: CodexAppServerSandboxMode | null;
258 config?: Record<string, JsonValue | undefined> | null;
259 serviceName?: string | null;
260 baseInstructions?: string | null;
261 developerInstructions?: string | null;
262 personality?: string | null;
263 ephemeral?: boolean | null;
264 experimentalRawEvents?: boolean;
265 persistExtendedHistory?: boolean;
266}
267
268export interface CodexAppServerThreadResumeParams {
269 threadId: CodexAppServerThreadId;
270 model?: string | null;
271 modelProvider?: string | null;
272 serviceTier?: string | null;
273 cwd?: string | null;
274 approvalPolicy?: CodexAppServerApprovalPolicy | null;
275 sandbox?: CodexAppServerSandboxMode | null;
276 config?: Record<string, JsonValue | undefined> | null;
277 baseInstructions?: string | null;
278 developerInstructions?: string | null;
279 personality?: string | null;
280 persistExtendedHistory?: boolean;
281}
282
283export interface CodexAppServerTurnStartParams {
284 threadId: CodexAppServerThreadId;
285 input: CodexAppServerUserInput[];
286 cwd?: string | null;
287 approvalPolicy?: CodexAppServerApprovalPolicy | null;
288 sandboxPolicy?: CodexAppServerSandboxPolicy | null;
289 model?: string | null;
290 serviceTier?: string | null;
291 effort?: string | null;
292 summary?: JsonValue | null;
293 personality?: string | null;
294 outputSchema?: JsonValue | null;
295 collaborationMode?: JsonValue | null;
296}
297
298export interface CodexAppServerTurnStartResult {
299 turn: CodexAppServerTurn;
300}
301
302export interface CodexAppServerTurnSteerParams {
303 threadId: CodexAppServerThreadId;
304 input: CodexAppServerUserInput[];
305 expectedTurnId: CodexAppServerTurnId;
306}
307
308export interface CodexAppServerTurnSteerResult {
309 turnId: CodexAppServerTurnId;
310}
311
312export interface CodexAppServerTurnInterruptParams {
313 threadId: CodexAppServerThreadId;
314 turnId: CodexAppServerTurnId;
315}
316
317export interface CodexAppServerNotificationEnvelope {
318 method: string;
319 params?: unknown;
320}
321
322export type CodexAppServerEvent =
323 | {
324 type: "thread.started";
325 notificationMethod: "thread/started";
326 thread: CodexAppServerThread;
327 }
328 | {
329 type: "thread.status.changed";
330 notificationMethod: "thread/status/changed";
331 threadId: CodexAppServerThreadId;
332 status: CodexAppServerThreadStatus;
333 }
334 | {
335 type: "turn.started";
336 notificationMethod: "turn/started";
337 threadId: CodexAppServerThreadId;
338 turn: CodexAppServerTurn;
339 }
340 | {
341 type: "turn.completed";
342 notificationMethod: "turn/completed";
343 threadId: CodexAppServerThreadId;
344 turn: CodexAppServerTurn;
345 }
346 | {
347 type: "turn.diff.updated";
348 notificationMethod: "turn/diff/updated";
349 threadId: CodexAppServerThreadId;
350 turnId: CodexAppServerTurnId;
351 diff: string;
352 }
353 | {
354 type: "turn.plan.updated";
355 notificationMethod: "turn/plan/updated";
356 threadId: CodexAppServerThreadId;
357 turnId: CodexAppServerTurnId;
358 explanation: string | null;
359 plan: CodexAppServerPlanStep[];
360 }
361 | {
362 type: "turn.message.delta";
363 notificationMethod: "item/agentMessage/delta";
364 threadId: CodexAppServerThreadId;
365 turnId: CodexAppServerTurnId;
366 itemId: CodexAppServerItemId;
367 delta: string;
368 }
369 | {
370 type: "turn.plan.delta";
371 notificationMethod: "item/plan/delta";
372 threadId: CodexAppServerThreadId;
373 turnId: CodexAppServerTurnId;
374 itemId: CodexAppServerItemId;
375 delta: string;
376 }
377 | {
378 type: "turn.error";
379 notificationMethod: "error";
380 threadId: CodexAppServerThreadId;
381 turnId: CodexAppServerTurnId;
382 error: CodexAppServerTurnError;
383 willRetry: boolean;
384 }
385 | {
386 type: "command.output.delta";
387 notificationMethod: "command/exec/outputDelta";
388 processId: CodexAppServerProcessId;
389 stream: CodexAppServerCommandOutputStream;
390 deltaBase64: string;
391 capReached: boolean;
392 }
393 | {
394 type: "notification";
395 notificationMethod: string;
396 params?: unknown;
397 };
398
399export function createCodexAppServerTextInput(
400 text: string,
401 textElements: CodexAppServerTextElement[] = []
402): CodexAppServerTextUserInput {
403 return {
404 type: "text",
405 text,
406 text_elements: textElements
407 };
408}
409
410export function createCodexAppServerReadOnlySandboxPolicy(options?: {
411 includePlatformDefaults?: boolean;
412 networkAccess?: boolean;
413 readableRoots?: string[];
414}): CodexAppServerSandboxPolicy {
415 return {
416 type: "readOnly",
417 access: {
418 type: "restricted",
419 includePlatformDefaults: options?.includePlatformDefaults ?? true,
420 readableRoots: options?.readableRoots ?? []
421 },
422 networkAccess: options?.networkAccess ?? false
423 };
424}