The best way to control Claude Code, Codex and more from any computer or phone

main
ts 1,046 lines 39.5 KB
Raw
1 import * as Deferred from "effect/Deferred";
2 import * as Effect from "effect/Effect";
3 import * as Fiber from "effect/Fiber";
4 import * as Logger from "effect/Logger";
5 import * as PlatformError from "effect/PlatformError";
6 import * as Queue from "effect/Queue";
7 import * as References from "effect/References";
8 import * as Schema from "effect/Schema";
9 import * as Sink from "effect/Sink";
10 import * as Stdio from "effect/Stdio";
11 import * as Stream from "effect/Stream";
12 import * as Tracer from "effect/Tracer";
13 import * as TestClock from "effect/testing/TestClock";
14
15 import * as NodeServices from "@effect/platform-node/NodeServices";
16 import { assert, it } from "@effect/vitest";
17
18 import * as CodexError from "./errors.ts";
19 import * as CodexProtocol from "./protocol.ts";
20 import { makeInMemoryStdio } from "./_internal/stdio.ts";
21 const encodeUnknownJsonString = Schema.encodeUnknownSync(Schema.fromJsonString(Schema.Unknown));
22
23 const encoder = new TextEncoder();
24
25 const encodeJsonl = (value: unknown) => encoder.encode(`${encodeUnknownJsonString(value)}\n`);
26
27 const decodeJson = Schema.decodeEffect(Schema.fromJsonString(Schema.Unknown));
28
29 it.layer(NodeServices.layer)("effect-codex-app-server protocol", (it) => {
30 it.effect(
31 "encodes requests without a jsonrpc field and routes inbound requests and notifications",
32 () =>
33 Effect.gen(function* () {
34 const { stdio, input, output } = yield* makeInMemoryStdio();
35 const transport = yield* CodexProtocol.makeCodexAppServerPatchedProtocol({ stdio });
36
37 const notificationDeferred =
38 yield* Deferred.make<ReadonlyArray<CodexProtocol.CodexAppServerIncomingNotification>>();
39 const requestDeferred =
40 yield* Deferred.make<ReadonlyArray<CodexProtocol.CodexAppServerIncomingRequest>>();
41
42 yield* transport.incomingNotifications.pipe(
43 Stream.take(1),
44 Stream.runCollect,
45 Effect.flatMap((notifications) => Deferred.succeed(notificationDeferred, notifications)),
46 Effect.forkScoped,
47 );
48
49 yield* transport.incomingRequests.pipe(
50 Stream.take(1),
51 Stream.runCollect,
52 Effect.flatMap((requests) => Deferred.succeed(requestDeferred, requests)),
53 Effect.forkScoped,
54 );
55
56 yield* transport.notify("initialized");
57 assert.equal(yield* Queue.take(output), '{"method":"initialized"}\n');
58
59 const initializeParams = {
60 clientInfo: {
61 name: "effect-codex-app-server-test",
62 title: "Effect Codex App Server Test",
63 version: "0.0.0",
64 },
65 capabilities: {
66 experimentalApi: true,
67 optOutNotificationMethods: null,
68 },
69 };
70
71 const pendingInitialize = yield* transport
72 .request("initialize", initializeParams)
73 .pipe(Effect.forkScoped);
74 assert.deepEqual(yield* decodeJson(yield* Queue.take(output)), {
75 id: 1,
76 method: "initialize",
77 params: initializeParams,
78 });
79
80 yield* Queue.offer(
81 input,
82 encodeJsonl({
83 method: "item/agentMessage/delta",
84 params: {
85 delta: "Hello from the mock peer.",
86 itemId: "item-1",
87 threadId: "thread-1",
88 turnId: "turn-1",
89 },
90 }),
91 );
92 yield* Queue.offer(
93 input,
94 encodeJsonl({
95 id: 77,
96 method: "item/tool/requestUserInput",
97 params: {
98 itemId: "item-approval-1",
99 threadId: "thread-1",
100 turnId: "turn-1",
101 questions: [
102 {
103 id: "approved",
104 header: "Approve",
105 question: "Continue?",
106 },
107 ],
108 },
109 }),
110 );
111 yield* Queue.offer(
112 input,
113 encodeJsonl({
114 id: 1,
115 result: {
116 userAgent: "mock-codex-app-server",
117 codexHome: "/tmp/codex-home",
118 platformFamily: "unix",
119 platformOs: "macos",
120 },
121 }),
122 );
123
124 assert.deepEqual(yield* Fiber.join(pendingInitialize), {
125 userAgent: "mock-codex-app-server",
126 codexHome: "/tmp/codex-home",
127 platformFamily: "unix",
128 platformOs: "macos",
129 });
130 assert.deepEqual(yield* Deferred.await(notificationDeferred), [
131 {
132 method: "item/agentMessage/delta",
133 params: {
134 delta: "Hello from the mock peer.",
135 itemId: "item-1",
136 threadId: "thread-1",
137 turnId: "turn-1",
138 },
139 },
140 ]);
141 assert.deepEqual(yield* Deferred.await(requestDeferred), [
142 {
143 id: 77,
144 method: "item/tool/requestUserInput",
145 params: {
146 itemId: "item-approval-1",
147 threadId: "thread-1",
148 turnId: "turn-1",
149 questions: [
150 {
151 id: "approved",
152 header: "Approve",
153 question: "Continue?",
154 },
155 ],
156 },
157 },
158 ]);
159
160 yield* transport.respond(77, {
161 answers: {
162 approved: {
163 answers: ["yes"],
164 },
165 },
166 });
167 assert.deepEqual(yield* decodeJson(yield* Queue.take(output)), {
168 id: 77,
169 result: {
170 answers: {
171 approved: {
172 answers: ["yes"],
173 },
174 },
175 },
176 });
177
178 yield* transport.respondError(
179 78,
180 CodexError.CodexAppServerRequestError.methodNotFound("x/test"),
181 );
182 assert.deepEqual(yield* decodeJson(yield* Queue.take(output)), {
183 id: 78,
184 error: {
185 code: -32601,
186 message: "Method not found: x/test",
187 },
188 });
189 }),
190 );
191
192 it.effect(
193 "correlates concurrent request spans through responses, failures and interruption",
194 () => {
195 const spans: Array<Tracer.NativeSpan> = [];
196 const tracer = Tracer.make({
197 span: (options) => {
198 const span = new Tracer.NativeSpan(options);
199 spans.push(span);
200 return span;
201 },
202 });
203 return Effect.gen(function* () {
204 const { stdio, input, output } = yield* makeInMemoryStdio();
205 const transport = yield* CodexProtocol.makeCodexAppServerPatchedProtocol({ stdio });
206 const methods = ["model/list", "account/read", "skills/list"];
207 const requests = [];
208 for (const method of methods) {
209 requests.push(
210 yield* transport.request(method, { secret: "private-payload" }).pipe(Effect.forkScoped),
211 );
212 yield* Queue.take(output);
213 }
214 yield* Queue.offer(
215 input,
216 encodeJsonl({ id: 2, error: { code: -32602, message: "Invalid params" } }),
217 );
218 yield* Fiber.await(requests[1]!);
219 yield* Queue.offer(input, encodeJsonl({ id: 1, result: { secret: "private-result" } }));
220 yield* Fiber.join(requests[0]!);
221 yield* Fiber.interrupt(requests[2]!);
222 // A late response for an interrupted request must not affect the next request.
223 yield* Queue.offer(input, encodeJsonl({ id: 3, result: {} }));
224 const next = yield* transport.request("config/read").pipe(Effect.forkScoped);
225 yield* Queue.take(output);
226 yield* Queue.offer(input, encodeJsonl({ id: 4, result: {} }));
227 yield* Fiber.join(next);
228 for (const [index, method] of [...methods, "config/read"].entries()) {
229 const request = spans.find(
230 (span) =>
231 span.name === "CodexAppServerProtocol.request" &&
232 span.attributes.get("rpc.request_id") === index + 1,
233 );
234 assert.isDefined(request);
235 assert.equal(request!.attributes.get("rpc.method"), method);
236 assert.equal(request!.attributes.get("rpc.system"), "jsonrpc");
237 assert.equal(request!.status._tag, "Ended");
238 if (request!.status._tag === "Ended") {
239 assert.equal(
240 request!.status.exit._tag,
241 index === 1 || index === 2 ? "Failure" : "Success",
242 );
243 }
244 for (const phase of ["enqueue", "awaitResponse"]) {
245 const child: Tracer.NativeSpan | undefined = spans.find(
246 (span) =>
247 span.name === `CodexAppServerProtocol.request.${phase}` &&
248 span.parent?._tag === "Some" &&
249 span.parent.value.spanId === request!.spanId,
250 );
251 assert.isDefined(child);
252 assert.equal(child!.traceId, request!.traceId);
253 assert.equal(child!.attributes.get("rpc.method"), method);
254 assert.equal(child!.attributes.get("rpc.request_id"), index + 1);
255 assert.equal(child!.status._tag, "Ended");
256 }
257 }
258 const failedSend = yield* transport
259 .request("thread/start", { value: 1n })
260 .pipe(Effect.exit);
261 assert.equal(failedSend._tag, "Failure");
262 const sendSpans = spans.filter((span) => span.attributes.get("rpc.request_id") === 5);
263 assert.deepEqual(
264 sendSpans.map((span) => span.name),
265 ["CodexAppServerProtocol.request", "CodexAppServerProtocol.request.enqueue"],
266 );
267 for (const span of sendSpans) {
268 assert.equal(span.attributes.get("rpc.method"), "thread/start");
269 assert.equal(span.status._tag, "Ended");
270 if (span.status._tag === "Ended") assert.equal(span.status.exit._tag, "Failure");
271 }
272 for (const span of spans) {
273 const attrs = JSON.stringify([...span.attributes]);
274 assert.notInclude(attrs, "private-payload");
275 assert.notInclude(attrs, "private-result");
276 }
277 }).pipe(Effect.withTracer(tracer));
278 },
279 );
280
281 it.effect.each([1, 7, 1024])(
282 "preserves JSONL framing and UTF-8 across %i-byte input chunks",
283 (chunkSize) =>
284 Effect.gen(function* () {
285 const { stdio, input } = yield* makeInMemoryStdio();
286 const notifications: Array<CodexProtocol.CodexAppServerIncomingNotification> = [];
287 const rawLines: Array<unknown> = [];
288 const termination = yield* Deferred.make<CodexError.CodexAppServerError>();
289 yield* CodexProtocol.makeCodexAppServerPatchedProtocol({
290 stdio,
291 logIncoming: true,
292 logger: (event) =>
293 Effect.sync(() => {
294 if (event.stage === "raw") {
295 rawLines.push(event.payload);
296 }
297 }),
298 onNotification: (notification) =>
299 Effect.sync(() => {
300 notifications.push(notification);
301 }),
302 onTermination: (error) => Deferred.succeed(termination, error).pipe(Effect.asVoid),
303 });
304
305 const firstLine = '{"method":"x/first",\r"params":{"text":"hé🙂"}}';
306 const secondLine = '{"method":"x/second","params":{"value":2}}';
307 const finalLine = '{"method":"x/final","params":{"text":"最後"}}\r';
308 const bytes = encoder.encode(`\n \t\r\n${firstLine}\r\n\n${secondLine}\n${finalLine}`);
309 for (let offset = 0; offset < bytes.length; offset += chunkSize) {
310 yield* Queue.offer(input, bytes.subarray(offset, offset + chunkSize));
311 }
312 yield* Queue.end(input);
313
314 assert.instanceOf(
315 yield* Deferred.await(termination),
316 CodexError.CodexAppServerInputStreamEndedError,
317 );
318 assert.deepEqual(notifications, [
319 { method: "x/first", params: { text: "hé🙂" } },
320 { method: "x/second", params: { value: 2 } },
321 { method: "x/final", params: { text: "最後" } },
322 ]);
323 assert.deepEqual(rawLines, [firstLine, secondLine, finalLine]);
324 }),
325 );
326
327 it.effect.each(["newline-terminated", "unfinished"])(
328 "rejects an oversized %s message using UTF-8 bytes before logging or parsing",
329 (framing) =>
330 Effect.gen(function* () {
331 const { stdio, input, output } = yield* makeInMemoryStdio();
332 const notifications: Array<CodexProtocol.CodexAppServerIncomingNotification> = [];
333 const logged: Array<unknown> = [];
334 const termination = yield* Deferred.make<CodexError.CodexAppServerError>();
335 let reachedEnd = false;
336 const transport = yield* CodexProtocol.makeCodexAppServerPatchedProtocol({
337 stdio: Stdio.make({
338 ...stdio,
339 stdin: stdio.stdin.pipe(
340 Stream.concat(
341 Stream.suspend(() => {
342 reachedEnd = true;
343 return Stream.empty;
344 }),
345 ),
346 ),
347 }),
348 maxIncomingMessageBytes: 16,
349 logIncoming: true,
350 logger: (event) =>
351 Effect.sync(() => {
352 logged.push(event.payload);
353 }),
354 onNotification: (notification) =>
355 Effect.sync(() => {
356 notifications.push(notification);
357 }),
358 onTermination: (error) => Deferred.succeed(termination, error).pipe(Effect.asVoid),
359 });
360 const pending = yield* Effect.forEach(["thread/read", "thread/list"], (method) =>
361 transport.request(method, {}).pipe(Effect.forkScoped),
362 );
363 yield* Effect.forEach(pending, () => Queue.take(output));
364
365 // Two 16-byte lines must survive; the 17-byte line is only 15 UTF-16 code units.
366 const firstLine = '{"method":"xé"}';
367 const secondLine = '{"method":"x/a"}';
368 const bytes = encoder.encode(
369 `${firstLine}\n${secondLine}\n{"method":"éé"}${framing === "unfinished" ? "" : "\n"}`,
370 );
371 // Split a UTF-8 sequence on both sides of the byte limit.
372 const firstSplit = bytes.indexOf(0xc3) + 1;
373 yield* Queue.offer(input, bytes.subarray(0, firstSplit));
374 if (framing === "unfinished") {
375 const lastSplit = bytes.lastIndexOf(0xc3) + 1;
376 yield* Queue.offer(input, bytes.subarray(firstSplit, lastSplit));
377 yield* Queue.offer(input, bytes.subarray(lastSplit));
378 } else {
379 yield* Queue.offer(input, bytes.subarray(firstSplit));
380 }
381 yield* Queue.end(input);
382
383 const error = yield* Deferred.await(termination);
384 assert.instanceOf(error, CodexError.CodexAppServerTransportError);
385 assert.equal(error.operation, "read-input-stream");
386 assert.isFalse(reachedEnd, "Must reject the unfinished line before reading EOF");
387 for (const response of pending) {
388 const failure = yield* Fiber.join(response).pipe(
389 Effect.match({
390 onFailure: (error) => error,
391 onSuccess: () => assert.fail("Expected the oversized message to fail the request"),
392 }),
393 );
394 assert.strictEqual(failure, error);
395 }
396 assert.deepEqual(notifications, [{ method: "xé" }, { method: "x/a" }]);
397 assert.deepEqual(logged, [firstLine, { method: "xé" }, secondLine, { method: "x/a" }]);
398 }),
399 );
400
401 it.effect("reports a malformed fragmented final line before input stream termination", () =>
402 Effect.gen(function* () {
403 const { stdio, input, output } = yield* makeInMemoryStdio();
404 const termination = yield* Deferred.make<CodexError.CodexAppServerError>();
405 const transport = yield* CodexProtocol.makeCodexAppServerPatchedProtocol({
406 stdio,
407 onTermination: (error) => Deferred.succeed(termination, error).pipe(Effect.asVoid),
408 });
409 const response = yield* transport.request("thread/read", {}).pipe(Effect.forkScoped);
410 yield* Queue.take(output);
411
412 yield* Queue.offer(input, encoder.encode('{"id":1,'));
413 yield* Queue.offer(input, encoder.encode('"result":'));
414 yield* Queue.end(input);
415
416 const error = yield* Deferred.await(termination);
417 assert.instanceOf(error, CodexError.CodexAppServerProtocolParseError);
418 assert.equal(error.operation, "decode-wire-message");
419 const responseError = yield* Fiber.join(response).pipe(
420 Effect.match({
421 onFailure: (failure) => failure,
422 onSuccess: () => assert.fail("Expected the malformed response to fail the request"),
423 }),
424 );
425 assert.strictEqual(responseError, error);
426 }),
427 );
428
429 it.effect("keeps processing protocol messages while an approval is pending", () =>
430 Effect.gen(function* () {
431 const { stdio, input, output } = yield* makeInMemoryStdio();
432 const approvalStarted = yield* Deferred.make<void>();
433 const approvalDecision = yield* Deferred.make<{ readonly decision: string }>();
434 const notificationReceived = yield* Deferred.make<void>();
435 const transport = yield* CodexProtocol.makeCodexAppServerPatchedProtocol({
436 stdio,
437 onRequest: () =>
438 Deferred.succeed(approvalStarted, undefined).pipe(
439 Effect.andThen(Deferred.await(approvalDecision)),
440 ),
441 onNotification: () => Deferred.succeed(notificationReceived, undefined).pipe(Effect.asVoid),
442 });
443
444 const pendingRequest = yield* transport.request("thread/read", {}).pipe(Effect.forkScoped);
445 yield* Queue.take(output);
446 yield* Queue.offer(
447 input,
448 encoder.encode(
449 `${[
450 encodeUnknownJsonString({ id: 7, method: "item/tool/requestUserInput", params: {} }),
451 encodeUnknownJsonString({ method: "item/agentMessage/delta", params: { delta: "ok" } }),
452 encodeUnknownJsonString({ id: 1, result: { threadId: "thread-1" } }),
453 ].join("\n")}\n`,
454 ),
455 );
456
457 yield* Deferred.await(approvalStarted);
458 yield* Deferred.await(notificationReceived);
459 assert.deepEqual(yield* Fiber.join(pendingRequest), { threadId: "thread-1" });
460
461 yield* Deferred.succeed(approvalDecision, { decision: "accept" });
462 assert.deepEqual(yield* decodeJson(yield* Queue.take(output)), {
463 id: 7,
464 result: { decision: "accept" },
465 });
466 }),
467 );
468
469 it.effect("rejects incoming requests after the active handler limit is reached", () =>
470 Effect.gen(function* () {
471 const { stdio, input, output } = yield* makeInMemoryStdio();
472 const handlersStarted = yield* Deferred.make<void>();
473 const releaseHandlers = yield* Deferred.make<void>();
474 let activeHandlers = 0;
475 yield* CodexProtocol.makeCodexAppServerPatchedProtocol({
476 stdio,
477 onRequest: () =>
478 Effect.sync(() => ++activeHandlers).pipe(
479 Effect.flatMap((count) =>
480 count === 32
481 ? Deferred.succeed(handlersStarted, undefined).pipe(Effect.asVoid)
482 : Effect.void,
483 ),
484 Effect.andThen(Deferred.await(releaseHandlers)),
485 Effect.as({ decision: "accept" }),
486 ),
487 });
488
489 const requests = Array.from({ length: 33 }, (_, index) =>
490 encodeUnknownJsonString({
491 id: index + 1,
492 method: "item/tool/requestUserInput",
493 params: {},
494 }),
495 );
496 yield* Queue.offer(input, encoder.encode(`${requests.join("\n")}\n`));
497 yield* Deferred.await(handlersStarted);
498
499 assert.deepEqual(yield* decodeJson(yield* Queue.take(output)), {
500 id: 33,
501 error: {
502 code: -32001,
503 message: "Too many Codex requests are already active.",
504 },
505 });
506 assert.equal(activeHandlers, 32);
507
508 yield* Deferred.succeed(releaseHandlers, undefined);
509 yield* Effect.forEach(Array.from({ length: 32 }), () => Queue.take(output), {
510 discard: true,
511 });
512 }),
513 );
514
515 it.effect.each([
516 { outcome: "dies", method: "item/tool/requestUserInput", logged: "item/tool/requestUserInput" },
517 { outcome: "throws", method: "codex-handler-secret-sentinel", logged: "unknown" },
518 ] as const)(
519 "answers an incoming request whose handler $outcome, keeping its text out of logs",
520 ({ outcome, method, logged: loggedMethod }) =>
521 Effect.gen(function* () {
522 const secret = "codex-handler-secret-sentinel";
523 const defect = Object.assign(new Error(secret), { name: secret });
524 const { stdio, input, output } = yield* makeInMemoryStdio();
525 const logged: Array<string> = [];
526 yield* CodexProtocol.makeCodexAppServerPatchedProtocol({
527 stdio,
528 onRequest: () => {
529 if (outcome === "throws") throw defect;
530 return Effect.die(defect);
531 },
532 }).pipe(
533 Effect.provide(
534 Logger.layer([
535 Logger.make(({ logLevel, message, fiber }) => {
536 if (logLevel === "Error") {
537 logged.push(
538 String([message].flat()),
539 JSON.stringify(fiber.getRef(References.CurrentLogAnnotations)),
540 );
541 }
542 }),
543 ]),
544 ),
545 );
546
547 const request = encodeUnknownJsonString({ id: 1, method, params: {} });
548 yield* Queue.offer(
549 input,
550 encoder.encode(`${request}
551 `),
552 );
553
554 assert.deepEqual(yield* decodeJson(yield* Queue.take(output)), {
555 id: 1,
556 error: { code: -32603, message: "Internal error" },
557 });
558 assert.lengthOf(logged, 2);
559 assert.notInclude(logged.join(), secret);
560 assert.include(logged.join(), loggedMethod);
561 }),
562 );
563
564 it.effect("releases a waiting request handler when Codex resolves its request", () =>
565 Effect.gen(function* () {
566 const { stdio, input, output } = yield* makeInMemoryStdio();
567 yield* CodexProtocol.makeCodexAppServerPatchedProtocol({
568 stdio,
569 onRequest: (request) =>
570 request.id === 33 ? Effect.succeed({ decision: "accept" }) : Effect.never,
571 });
572
573 const messages = Array.from({ length: 32 }, (_, index) =>
574 encodeUnknownJsonString({
575 id: index + 1,
576 method: "item/commandExecution/requestApproval",
577 params: {},
578 }),
579 );
580 for (let requestId = 1; requestId <= 32; requestId++) {
581 messages.push(
582 encodeUnknownJsonString({
583 method: "serverRequest/resolved",
584 params: { threadId: "thread-1", requestId },
585 }),
586 );
587 }
588 messages.push(
589 encodeUnknownJsonString({
590 id: 33,
591 method: "item/commandExecution/requestApproval",
592 params: {},
593 }),
594 );
595 yield* Queue.offer(input, encoder.encode(`${messages.join("\n")}\n`));
596
597 assert.deepEqual(yield* decodeJson(yield* Queue.take(output)), {
598 id: 33,
599 result: { decision: "accept" },
600 });
601 }),
602 );
603
604 it.effect("keeps numeric and string request ids apart when Codex resolves one", () =>
605 Effect.gen(function* () {
606 const { stdio, input, output } = yield* makeInMemoryStdio();
607 const interrupted: Array<string | number> = [];
608 yield* CodexProtocol.makeCodexAppServerPatchedProtocol({
609 stdio,
610 onRequest: (request) =>
611 request.id === 2
612 ? Effect.sync(() => ({ interrupted }))
613 : Effect.never.pipe(
614 Effect.onInterrupt(() => Effect.sync(() => interrupted.push(request.id))),
615 ),
616 });
617
618 const messages = [
619 { id: 1, method: "item/commandExecution/requestApproval", params: {} },
620 { id: "1", method: "item/commandExecution/requestApproval", params: {} },
621 { method: "serverRequest/resolved", params: { threadId: "thread-1", requestId: "1" } },
622 { id: 2, method: "item/commandExecution/requestApproval", params: {} },
623 ].map((message) => encodeUnknownJsonString(message));
624 yield* Queue.offer(input, encoder.encode(`${messages.join("\n")}\n`));
625
626 assert.deepEqual(yield* decodeJson(yield* Queue.take(output)), {
627 id: 2,
628 result: { interrupted: ["1"] },
629 });
630 }),
631 );
632
633 it.effect("interrupts pending request handlers when the protocol terminates", () =>
634 Effect.gen(function* () {
635 const { stdio, input } = yield* makeInMemoryStdio();
636 const approvalStarted = yield* Deferred.make<void>();
637 const approvalInterrupted = yield* Deferred.make<void>();
638 const terminated = yield* Deferred.make<void>();
639 yield* CodexProtocol.makeCodexAppServerPatchedProtocol({
640 stdio,
641 onRequest: () =>
642 Deferred.succeed(approvalStarted, undefined).pipe(
643 Effect.andThen(Effect.never),
644 Effect.onInterrupt(() =>
645 Deferred.succeed(approvalInterrupted, undefined).pipe(Effect.asVoid),
646 ),
647 ),
648 onTermination: () => Deferred.succeed(terminated, undefined).pipe(Effect.asVoid),
649 });
650
651 yield* Queue.offer(
652 input,
653 encodeJsonl({ id: 7, method: "item/tool/requestUserInput", params: {} }),
654 );
655 yield* Deferred.await(approvalStarted);
656 yield* Queue.end(input);
657
658 yield* Deferred.await(approvalInterrupted);
659 yield* Deferred.await(terminated);
660 }),
661 );
662
663 it.effect("rejects outgoing messages after an approval response cannot be encoded", () =>
664 Effect.gen(function* () {
665 const { stdio: baseStdio, input } = yield* makeInMemoryStdio();
666 const terminated = yield* Deferred.make<CodexError.CodexAppServerError>();
667 const readerStopped = yield* Deferred.make<void>();
668 let notificationCount = 0;
669 let requestCount = 0;
670 const stdio = Stdio.make({
671 args: baseStdio.args,
672 stdin: baseStdio.stdin.pipe(
673 Stream.ensuring(Deferred.succeed(readerStopped, undefined).pipe(Effect.asVoid)),
674 ),
675 stdout: baseStdio.stdout,
676 stderr: baseStdio.stderr,
677 });
678 const transport = yield* CodexProtocol.makeCodexAppServerPatchedProtocol({
679 stdio,
680 onRequest: () =>
681 Effect.sync(() => ++requestCount).pipe(
682 Effect.map((count) => (count === 1 ? { invalid: 1n } : { ok: true })),
683 ),
684 onNotification: () => Effect.sync(() => notificationCount++).pipe(Effect.asVoid),
685 onTermination: (error) => Deferred.succeed(terminated, error).pipe(Effect.asVoid),
686 });
687
688 yield* Queue.offer(
689 input,
690 encodeJsonl({ id: 7, method: "item/tool/requestUserInput", params: {} }),
691 );
692
693 const failure = yield* Deferred.await(terminated);
694 assert.instanceOf(failure, CodexError.CodexAppServerProtocolParseError);
695 const requestFailure = yield* transport.request("thread/read", {}).pipe(
696 Effect.match({
697 onFailure: (error) => error,
698 onSuccess: () => assert.fail("Expected a terminated protocol request to fail"),
699 }),
700 );
701 const notificationFailure = yield* transport.notify("initialized").pipe(Effect.flip);
702 assert.strictEqual(requestFailure, failure);
703 assert.strictEqual(notificationFailure, failure);
704 yield* Deferred.await(readerStopped);
705
706 yield* Queue.offer(
707 input,
708 encoder.encode(
709 `${[
710 encodeUnknownJsonString({ method: "x/late-notification" }),
711 encodeUnknownJsonString({ id: 8, method: "x/late-request" }),
712 ].join("\n")}\n`,
713 ),
714 );
715
716 assert.equal(notificationCount, 0);
717 assert.equal(requestCount, 1);
718 assert.equal(yield* Queue.size(input), 1);
719 }),
720 );
721
722 it.effect("fails pending requests before interrupted handler cleanup completes", () =>
723 Effect.gen(function* () {
724 const { stdio, input, output } = yield* makeInMemoryStdio();
725 const handlerStarted = yield* Deferred.make<void>();
726 const finalizerStarted = yield* Deferred.make<void>();
727 const releaseFinalizer = yield* Deferred.make<void>();
728 const terminated = yield* Deferred.make<CodexError.CodexAppServerError>();
729 const transport = yield* CodexProtocol.makeCodexAppServerPatchedProtocol({
730 stdio,
731 onRequest: () =>
732 Deferred.succeed(handlerStarted, undefined).pipe(
733 Effect.andThen(Effect.never),
734 Effect.onInterrupt(() =>
735 Deferred.succeed(finalizerStarted, undefined).pipe(
736 Effect.andThen(Deferred.await(releaseFinalizer)),
737 ),
738 ),
739 ),
740 onTermination: (error) => Deferred.succeed(terminated, error).pipe(Effect.asVoid),
741 });
742 const pending = yield* transport.request("thread/read", {}).pipe(Effect.forkScoped);
743 yield* Queue.take(output);
744 yield* Queue.offer(input, encodeJsonl({ id: 7, method: "x/approval" }));
745 yield* Deferred.await(handlerStarted);
746 yield* Queue.end(input);
747
748 const failure = yield* Deferred.await(terminated);
749 yield* Deferred.await(finalizerStarted);
750 const pendingFailure = yield* Fiber.join(pending).pipe(
751 Effect.match({
752 onFailure: (error) => error,
753 onSuccess: () => assert.fail("Expected the pending request to fail"),
754 }),
755 );
756 assert.strictEqual(pendingFailure, failure);
757
758 yield* Deferred.succeed(releaseFinalizer, undefined);
759 }),
760 );
761
762 it.effect("correlates response errors with the originating request", () =>
763 Effect.gen(function* () {
764 const { stdio, input, output } = yield* makeInMemoryStdio();
765 const transport = yield* CodexProtocol.makeCodexAppServerPatchedProtocol({ stdio });
766
767 const response = yield* transport.request("thread/start", {}).pipe(Effect.forkScoped);
768 yield* Queue.take(output);
769 yield* Queue.offer(
770 input,
771 encodeJsonl({
772 id: 1,
773 error: {
774 code: -32602,
775 message: "Invalid params",
776 data: { field: "cwd" },
777 },
778 }),
779 );
780
781 const error = yield* Fiber.join(response).pipe(
782 Effect.match({
783 onFailure: (error) => error,
784 onSuccess: () => assert.fail("Expected Codex App Server request to fail"),
785 }),
786 );
787 assert.instanceOf(error, CodexError.CodexAppServerRequestError);
788 assert.deepInclude(error, {
789 code: -32602,
790 errorMessage: "Invalid params",
791 method: "thread/start",
792 requestId: "1",
793 operation: "receive-response",
794 });
795 }),
796 );
797
798 it.effect("logs decode failures without copying the cause or wire payload", () =>
799 Effect.gen(function* () {
800 const secret = "codex-wire-secret-sentinel";
801 const { stdio, input } = yield* makeInMemoryStdio();
802 const events: Array<CodexProtocol.CodexAppServerProtocolLogEvent> = [];
803 const termination = yield* Deferred.make<CodexError.CodexAppServerError>();
804 yield* CodexProtocol.makeCodexAppServerPatchedProtocol({
805 stdio,
806 logIncoming: true,
807 logger: (event) =>
808 Effect.sync(() => {
809 events.push(event);
810 }),
811 onTermination: (error) => Deferred.succeed(termination, error).pipe(Effect.asVoid),
812 });
813
814 yield* Queue.offer(input, encoder.encode(`{"secret":"${secret}"\n`));
815 yield* Deferred.await(termination);
816
817 const event = events.find(({ stage }) => stage === "decode_failed");
818 assert.exists(event);
819 assert.equal(event.direction, "incoming");
820 const payload = event.payload as Record<string, unknown>;
821 assert.equal(payload.operation, "decode-wire-message");
822 assert.isNumber(payload.issueCount);
823 assert.isArray(payload.issueKinds);
824 assert.isNumber(payload.maximumPathDepth);
825 assert.equal("cause" in payload, false);
826 assert.equal("detail" in payload, false);
827 assert.notInclude(encodeUnknownJsonString(event), secret);
828 }),
829 );
830
831 it.effect("describes unroutable messages with safe structural diagnostics", () =>
832 Effect.gen(function* () {
833 const secret = "codex-unroutable-secret-sentinel";
834 const { stdio, input } = yield* makeInMemoryStdio();
835 const termination = yield* Deferred.make<CodexError.CodexAppServerError>();
836 yield* CodexProtocol.makeCodexAppServerPatchedProtocol({
837 stdio,
838 onTermination: (error) => Deferred.succeed(termination, error).pipe(Effect.asVoid),
839 });
840
841 yield* Queue.offer(
842 input,
843 encodeJsonl({ id: true, method: "thread/start", params: { token: secret } }),
844 );
845
846 const error = yield* Deferred.await(termination);
847 assert.instanceOf(error, CodexError.CodexAppServerProtocolParseError);
848 assert.deepInclude(error, {
849 operation: "route-wire-message",
850 method: "thread/start",
851 payloadKind: "object",
852 presentFields: ["id", "method", "params"],
853 });
854 assert.isUndefined(error.requestId);
855 assert.notProperty(error, "detail");
856 assert.notProperty(error, "cause");
857 assert.notInclude(error.message, secret);
858 }),
859 );
860
861 it.effect("fails pending requests when input ends while the process is still running", () =>
862 Effect.gen(function* () {
863 const { stdio, input, output } = yield* makeInMemoryStdio();
864 const transport = yield* CodexProtocol.makeCodexAppServerPatchedProtocol({
865 stdio,
866 terminationError: Effect.never,
867 });
868 const pending = yield* transport.request("thread/read", {}).pipe(Effect.forkScoped);
869 yield* Queue.take(output);
870
871 yield* Queue.end(input);
872 yield* TestClock.adjust("249 millis");
873 assert.isUndefined(pending.pollUnsafe());
874 yield* TestClock.adjust("1 millis");
875
876 const failure = yield* Fiber.join(pending).pipe(
877 Effect.match({
878 onFailure: (error) => error,
879 onSuccess: () => assert.fail("Expected the pending request to fail"),
880 }),
881 );
882 assert.instanceOf(failure, CodexError.CodexAppServerInputStreamEndedError);
883 }),
884 );
885
886 it.effect("fails pending requests when the exit status lookup dies", () =>
887 Effect.gen(function* () {
888 const { stdio, input, output } = yield* makeInMemoryStdio();
889 const defect = new Error("Injected exit status defect");
890 const terminated = yield* Deferred.make<CodexError.CodexAppServerError>();
891 const transport = yield* CodexProtocol.makeCodexAppServerPatchedProtocol({
892 stdio,
893 terminationError: Effect.die(defect),
894 onTermination: (error) => Deferred.succeed(terminated, error).pipe(Effect.asVoid),
895 });
896 const pending = yield* transport.request("thread/read", {}).pipe(Effect.forkScoped);
897 yield* Queue.take(output);
898
899 yield* Queue.end(input);
900
901 const failure = yield* Fiber.join(pending).pipe(
902 Effect.match({
903 onFailure: (error) => error,
904 onSuccess: () => assert.fail("Expected the pending request to fail"),
905 }),
906 );
907 assert.instanceOf(failure, CodexError.CodexAppServerTransportError);
908 assert.strictEqual(failure.cause, defect);
909 assert.strictEqual(yield* Deferred.await(terminated), failure);
910 }),
911 );
912
913 it.effect("retires the transport after a defect in the writer", () =>
914 Effect.gen(function* () {
915 const { stdio: baseStdio } = yield* makeInMemoryStdio();
916 const defect = new Error("Injected transport defect");
917 const terminated = yield* Deferred.make<CodexError.CodexAppServerError>();
918 const transport = yield* CodexProtocol.makeCodexAppServerPatchedProtocol({
919 stdio: Stdio.make({
920 ...baseStdio,
921 stdout: () => Sink.forEach(() => Effect.die(defect)),
922 }),
923 onTermination: (error) => Deferred.succeed(terminated, error).pipe(Effect.asVoid),
924 });
925
926 const failure = yield* transport.request("thread/read", {}).pipe(
927 Effect.match({
928 onFailure: (error) => error,
929 onSuccess: () => assert.fail("Expected the dead writer to fail the request"),
930 }),
931 );
932 assert.instanceOf(failure, CodexError.CodexAppServerTransportError);
933 assert.equal(failure.operation, "write-output-stream");
934 assert.strictEqual(failure.cause, defect);
935 assert.strictEqual(yield* Deferred.await(terminated), failure);
936 }),
937 );
938
939 it.effect("does not report normal scope shutdown as a transport failure", () =>
940 Effect.gen(function* () {
941 let terminations = 0;
942 yield* Effect.gen(function* () {
943 const { stdio, output } = yield* makeInMemoryStdio();
944 const transport = yield* CodexProtocol.makeCodexAppServerPatchedProtocol({
945 stdio,
946 onTermination: () =>
947 Effect.sync(() => {
948 terminations++;
949 }),
950 });
951 yield* transport.request("thread/read", {}).pipe(Effect.forkScoped);
952 yield* Queue.take(output);
953 }).pipe(Effect.scoped);
954 assert.equal(terminations, 0);
955 }),
956 );
957
958 it.effect("fails pending requests when a write fails while input stays open", () =>
959 Effect.gen(function* () {
960 const { stdio: baseStdio } = yield* makeInMemoryStdio();
961 const writeFailure = PlatformError.systemError({
962 _tag: "Unknown",
963 module: "Stdio",
964 method: "stdout",
965 cause: new Error("EPIPE"),
966 });
967 const terminated = yield* Deferred.make<CodexError.CodexAppServerError>();
968 const transport = yield* CodexProtocol.makeCodexAppServerPatchedProtocol({
969 stdio: Stdio.make({
970 args: baseStdio.args,
971 stdin: baseStdio.stdin,
972 stdout: () => Sink.forEach(() => Effect.fail(writeFailure)),
973 stderr: baseStdio.stderr,
974 }),
975 onTermination: (error) => Deferred.succeed(terminated, error).pipe(Effect.asVoid),
976 });
977 const pending = yield* transport.request("thread/read", {}).pipe(Effect.forkScoped);
978
979 const failure = yield* Deferred.await(terminated);
980 assert.instanceOf(failure, CodexError.CodexAppServerTransportError);
981 assert.equal(failure.operation, "write-output-stream");
982 assert.strictEqual(failure.cause, writeFailure);
983 for (const request of [Fiber.join(pending), transport.request("thread/read", {})]) {
984 const requestFailure = yield* request.pipe(
985 Effect.match({
986 onFailure: (error) => error,
987 onSuccess: () => assert.fail("Expected the broken transport to reject the request"),
988 }),
989 );
990 assert.strictEqual(requestFailure, failure);
991 }
992 }),
993 );
994
995 it.effect("reports the process exit when a write fails because the process exited", () =>
996 Effect.gen(function* () {
997 const { stdio: baseStdio } = yield* makeInMemoryStdio();
998 const exitError = new CodexError.CodexAppServerProcessExitedError({ code: 1, pid: 123 });
999 const transport = yield* CodexProtocol.makeCodexAppServerPatchedProtocol({
1000 stdio: Stdio.make({
1001 ...baseStdio,
1002 stdout: () =>
1003 Sink.forEach(() =>
1004 Effect.fail(
1005 PlatformError.systemError({
1006 _tag: "Unknown",
1007 module: "Stdio",
1008 method: "stdout",
1009 cause: new Error("EPIPE"),
1010 }),
1011 ),
1012 ),
1013 }),
1014 terminationError: Effect.succeed(exitError),
1015 });
1016
1017 const failure = yield* transport.request("initialize", {}).pipe(
1018 Effect.match({
1019 onFailure: (error) => error,
1020 onSuccess: () => assert.fail("Expected the exited process to fail the request"),
1021 }),
1022 );
1023 assert.strictEqual(failure, exitError);
1024 }),
1025 );
1026
1027 it.effect("reports a process exit that follows input end", () =>
1028 Effect.gen(function* () {
1029 const { stdio, input } = yield* makeInMemoryStdio();
1030 const exitError = new CodexError.CodexAppServerProcessExitedError({ code: 1, pid: 123 });
1031 const exited = yield* Deferred.make<CodexError.CodexAppServerError>();
1032 const termination = yield* Deferred.make<CodexError.CodexAppServerError>();
1033 yield* CodexProtocol.makeCodexAppServerPatchedProtocol({
1034 stdio,
1035 terminationError: Deferred.await(exited),
1036 onTermination: (error) => Deferred.succeed(termination, error).pipe(Effect.asVoid),
1037 });
1038
1039 yield* Queue.end(input);
1040 yield* TestClock.adjust("100 millis");
1041 yield* Deferred.succeed(exited, exitError);
1042
1043 assert.strictEqual(yield* Deferred.await(termination), exitError);
1044 }),
1045 );
1046 });