Open History to see the last commit
1import * as Schema from "effect/Schema";
2import type * as SchemaIssue from "effect/SchemaIssue";
3
4const CodexAppServerRequestOperation = Schema.Literals([
5 "decode-payload",
6 "encode-payload",
7 "handle-request",
8 "receive-response",
9]);
10type CodexAppServerRequestOperation = typeof CodexAppServerRequestOperation.Type;
11
12const CodexAppServerSchemaIssueKind = Schema.Literals([
13 "Filter",
14 "Encoding",
15 "Pointer",
16 "Composite",
17 "AnyOf",
18 "InvalidType",
19 "InvalidValue",
20 "MissingKey",
21 "UnexpectedKey",
22 "Forbidden",
23 "OneOf",
24]);
25type CodexAppServerSchemaIssueKind = typeof CodexAppServerSchemaIssueKind.Type;
26
27interface CodexAppServerSchemaIssueDiagnostics {
28 readonly issueCount: number;
29 readonly issueKinds: ReadonlyArray<CodexAppServerSchemaIssueKind>;
30 readonly maximumPathDepth: number;
31}
32
33const schemaIssueDiagnostics = (root: SchemaIssue.Issue): CodexAppServerSchemaIssueDiagnostics => {
34 let issueCount = 0;
35 let maximumPathDepth = 0;
36 const issueKinds = new Set<CodexAppServerSchemaIssueKind>();
37
38 const visit = (issue: SchemaIssue.Issue, pathDepth: number): void => {
39 issueCount += 1;
40 issueKinds.add(issue._tag);
41 maximumPathDepth = Math.max(maximumPathDepth, pathDepth);
42 switch (issue._tag) {
43 case "Filter":
44 case "Encoding":
45 visit(issue.issue, pathDepth);
46 break;
47 case "Pointer":
48 visit(issue.issue, pathDepth + issue.path.length);
49 break;
50 case "Composite":
51 case "AnyOf":
52 for (const child of issue.issues) visit(child, pathDepth);
53 break;
54 }
55 };
56
57 visit(root, 0);
58 return {
59 issueCount,
60 issueKinds: [...issueKinds],
61 maximumPathDepth,
62 };
63};
64
65const CodexAppServerPayloadKind = Schema.Literals([
66 "null",
67 "array",
68 "string",
69 "number",
70 "boolean",
71 "bigint",
72 "object",
73 "symbol",
74 "function",
75 "undefined",
76]);
77type CodexAppServerPayloadKind = typeof CodexAppServerPayloadKind.Type;
78
79const payloadKind = (payload: unknown): CodexAppServerPayloadKind => {
80 if (payload === null) return "null";
81 if (Array.isArray(payload)) return "array";
82 return typeof payload;
83};
84
85const protocolMessageFields = ["id", "method", "params", "result", "error"] as const;
86
87const CodexAppServerProtocolMessageField = Schema.Literals(protocolMessageFields);
88
89export interface CodexAppServerRequestDiagnostics {
90 readonly method?: string;
91 readonly requestId?: string;
92 readonly operation?: CodexAppServerRequestOperation;
93 readonly cause?: unknown;
94 readonly issueCount?: number;
95 readonly issueKinds?: ReadonlyArray<CodexAppServerSchemaIssueKind>;
96 readonly maximumPathDepth?: number;
97 readonly payloadKind?: CodexAppServerPayloadKind;
98}
99
100export const CodexAppServerProtocolParseOperation = Schema.Literals([
101 "encode-wire-message",
102 "decode-wire-message",
103 "route-wire-message",
104 "decode-notification-payload",
105 "decode-request-payload",
106 "decode-response-payload",
107]);
108export type CodexAppServerProtocolParseOperation = typeof CodexAppServerProtocolParseOperation.Type;
109
110export const CodexAppServerTransportOperation = Schema.Literals([
111 "read-input-stream",
112 "write-output-stream",
113 "read-process-exit-status",
114]);
115export type CodexAppServerTransportOperation = typeof CodexAppServerTransportOperation.Type;
116
117export interface CodexAppServerProtocolErrorShape {
118 readonly code: number;
119 readonly message: string;
120 readonly data?: unknown;
121}
122
123export class CodexAppServerSpawnError extends Schema.TaggedError<CodexAppServerSpawnError>()(
124 "CodexAppServerSpawnError",
125 {
126 command: Schema.optional(Schema.String),
127 cause: Schema.Defect(),
128 },
129) {
130 override get message() {
131 return this.command
132 ? `Failed to spawn Codex App Server process for command: ${this.command}`
133 : "Failed to spawn Codex App Server process";
134 }
135}
136
137export class CodexAppServerProcessExitedError extends Schema.TaggedError<CodexAppServerProcessExitedError>()(
138 "CodexAppServerProcessExitedError",
139 {
140 code: Schema.optional(Schema.Number),
141 pid: Schema.optionalKey(Schema.Int),
142 stderr: Schema.optionalKey(Schema.String),
143 cause: Schema.optional(Schema.Defect()),
144 },
145) {
146 override get message() {
147 const base =
148 this.code === undefined
149 ? "Codex App Server process exited"
150 : `Codex App Server process exited with code ${this.code}`;
151 return this.stderr ? `${base}: ${this.stderr}` : base;
152 }
153}
154
155export class CodexAppServerProtocolParseError extends Schema.TaggedError<CodexAppServerProtocolParseError>()(
156 "CodexAppServerProtocolParseError",
157 {
158 operation: CodexAppServerProtocolParseOperation,
159 method: Schema.optionalKey(Schema.String),
160 requestId: Schema.optionalKey(Schema.String),
161 payloadKind: Schema.optionalKey(CodexAppServerPayloadKind),
162 presentFields: Schema.optionalKey(Schema.Array(CodexAppServerProtocolMessageField)),
163 issueCount: Schema.optionalKey(Schema.Number),
164 issueKinds: Schema.optionalKey(Schema.Array(CodexAppServerSchemaIssueKind)),
165 maximumPathDepth: Schema.optionalKey(Schema.Number),
166 cause: Schema.optional(Schema.Defect()),
167 },
168) {
169 override get message() {
170 const method = this.method === undefined ? "" : ` for method '${this.method}'`;
171 return `Codex App Server protocol operation '${this.operation}' failed${method}.`;
172 }
173
174 static fromSchemaError(
175 operation: CodexAppServerProtocolParseOperation,
176 cause: Schema.SchemaError,
177 context: { readonly method?: string; readonly requestId?: string } = {},
178 ) {
179 return new CodexAppServerProtocolParseError({
180 operation,
181 ...context,
182 ...schemaIssueDiagnostics(cause.issue),
183 cause,
184 });
185 }
186
187 static fromRequestError(
188 operation: CodexAppServerProtocolParseOperation,
189 method: string,
190 cause: CodexAppServerRequestError,
191 ) {
192 return new CodexAppServerProtocolParseError({
193 operation,
194 method,
195 ...(cause.issueCount === undefined ? {} : { issueCount: cause.issueCount }),
196 ...(cause.issueKinds === undefined ? {} : { issueKinds: cause.issueKinds }),
197 ...(cause.maximumPathDepth === undefined ? {} : { maximumPathDepth: cause.maximumPathDepth }),
198 cause,
199 });
200 }
201
202 static fromUnroutableMessage(message: unknown) {
203 const diagnostics = { payloadKind: payloadKind(message) };
204 if (typeof message !== "object" || message === null || Array.isArray(message)) {
205 return new CodexAppServerProtocolParseError({
206 operation: "route-wire-message",
207 ...diagnostics,
208 });
209 }
210
211 const presentFields = protocolMessageFields.filter((field) => field in message);
212 const method =
213 "method" in message && typeof message.method === "string" ? message.method : undefined;
214 const requestId =
215 "id" in message && (typeof message.id === "string" || typeof message.id === "number")
216 ? String(message.id)
217 : undefined;
218 return new CodexAppServerProtocolParseError({
219 operation: "route-wire-message",
220 ...diagnostics,
221 presentFields,
222 ...(method === undefined ? {} : { method }),
223 ...(requestId === undefined ? {} : { requestId }),
224 });
225 }
226}
227
228export class CodexAppServerTransportError extends Schema.TaggedError<CodexAppServerTransportError>()(
229 "CodexAppServerTransportError",
230 {
231 operation: CodexAppServerTransportOperation,
232 pid: Schema.optionalKey(Schema.Int),
233 cause: Schema.Defect(),
234 },
235) {
236 override get message() {
237 return `Codex App Server transport operation '${this.operation}' failed.`;
238 }
239}
240
241export class CodexAppServerInputStreamEndedError extends Schema.TaggedError<CodexAppServerInputStreamEndedError>()(
242 "CodexAppServerInputStreamEndedError",
243 {},
244) {
245 override get message() {
246 return "Codex App Server input stream ended.";
247 }
248}
249
250export class CodexAppServerRequestError extends Schema.TaggedError<CodexAppServerRequestError>()(
251 "CodexAppServerRequestError",
252 {
253 code: Schema.Number,
254 errorMessage: Schema.String,
255 data: Schema.optional(Schema.Unknown),
256 method: Schema.optionalKey(Schema.String),
257 requestId: Schema.optionalKey(Schema.String),
258 operation: Schema.optionalKey(CodexAppServerRequestOperation),
259 issueCount: Schema.optionalKey(Schema.Number),
260 issueKinds: Schema.optionalKey(Schema.Array(CodexAppServerSchemaIssueKind)),
261 maximumPathDepth: Schema.optionalKey(Schema.Number),
262 payloadKind: Schema.optionalKey(CodexAppServerPayloadKind),
263 cause: Schema.optionalKey(Schema.Defect()),
264 },
265) {
266 override get message() {
267 return this.errorMessage;
268 }
269
270 static fromProtocolError(
271 error: CodexAppServerProtocolErrorShape,
272 method: string,
273 requestId: string,
274 ) {
275 return new CodexAppServerRequestError({
276 code: error.code,
277 errorMessage: error.message,
278 ...(error.data !== undefined ? { data: error.data } : {}),
279 method,
280 requestId,
281 operation: "receive-response",
282 cause: error,
283 });
284 }
285
286 static fromAppServerError(error: CodexAppServerError, method: string) {
287 if (error._tag === "CodexAppServerRequestError") {
288 return error;
289 }
290 return CodexAppServerRequestError.internalError(
291 `Codex App Server request handler failed for method '${method}'`,
292 undefined,
293 {
294 method,
295 operation: "handle-request",
296 cause: error,
297 },
298 );
299 }
300
301 static methodNotFound(method: string) {
302 return new CodexAppServerRequestError({
303 code: -32601,
304 errorMessage: `Method not found: ${method}`,
305 });
306 }
307
308 static invalidPayload(
309 method: string,
310 operation: "decode-payload" | "encode-payload",
311 cause: Schema.SchemaError,
312 ) {
313 const diagnostics = schemaIssueDiagnostics(cause.issue);
314 return new CodexAppServerRequestError({
315 code: -32602,
316 errorMessage: `Invalid payload for method '${method}' during '${operation}'`,
317 data: diagnostics,
318 method,
319 operation,
320 ...diagnostics,
321 cause,
322 });
323 }
324
325 static unexpectedPayload(
326 method: string,
327 operation: "decode-payload" | "encode-payload",
328 payload: unknown,
329 ) {
330 const diagnostics = { payloadKind: payloadKind(payload) };
331 return new CodexAppServerRequestError({
332 code: -32602,
333 errorMessage: `Method '${method}' does not accept a payload during '${operation}'`,
334 data: diagnostics,
335 method,
336 operation,
337 ...diagnostics,
338 });
339 }
340
341 static internalError(
342 message = "Internal error",
343 data?: unknown,
344 diagnostics: CodexAppServerRequestDiagnostics = {},
345 ) {
346 return new CodexAppServerRequestError({
347 code: -32603,
348 errorMessage: message,
349 ...(data !== undefined ? { data } : {}),
350 ...diagnostics,
351 });
352 }
353
354 static overloaded(message = "Server overloaded; retry later.", data?: unknown) {
355 return new CodexAppServerRequestError({
356 code: -32001,
357 errorMessage: message,
358 ...(data !== undefined ? { data } : {}),
359 });
360 }
361
362 toProtocolError(): CodexAppServerProtocolErrorShape {
363 return {
364 code: this.code,
365 message: this.errorMessage,
366 ...(this.data !== undefined ? { data: this.data } : {}),
367 };
368 }
369}
370
371export const CodexAppServerError = Schema.Union([
372 CodexAppServerRequestError,
373 CodexAppServerSpawnError,
374 CodexAppServerProcessExitedError,
375 CodexAppServerProtocolParseError,
376 CodexAppServerTransportError,
377 CodexAppServerInputStreamEndedError,
378]);
379
380export type CodexAppServerError = typeof CodexAppServerError.Type;