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

main
ts 586 lines 21.6 KB
Raw
1 import * as Cause from "effect/Cause";
2 import * as Deferred from "effect/Deferred";
3 import * as Effect from "effect/Effect";
4 import * as Exit from "effect/Exit";
5 import * as FiberMap from "effect/FiberMap";
6 import * as Option from "effect/Option";
7 import * as Queue from "effect/Queue";
8 import * as Ref from "effect/Ref";
9 import * as Scope from "effect/Scope";
10 import * as Schema from "effect/Schema";
11 import * as Stdio from "effect/Stdio";
12 import * as Stream from "effect/Stream";
13
14 import * as CodexRpc from "./_generated/meta.gen.ts";
15 import * as CodexError from "./errors.ts";
16 import { JsonRpcId, JsonRpcResponseEnvelope } from "./_internal/shared.ts";
17 const isJsonRpcId = Schema.is(JsonRpcId);
18 const isJsonRpcResponseEnvelope = Schema.is(JsonRpcResponseEnvelope);
19 const isCodexAppServerError = Schema.is(CodexError.CodexAppServerError);
20 const MAX_BUFFERED_RAW_MESSAGES = 32;
21 // Bound JSONL lines before joining and parsing; the LF delimiter is excluded.
22 const MAX_INCOMING_MESSAGE_BYTES = 128 * 1024 * 1024;
23 const EXIT_STATUS_GRACE = "250 millis";
24
25 export interface CodexAppServerProtocolLogEvent {
26 readonly direction: "incoming" | "outgoing";
27 readonly stage: "raw" | "decoded" | "decode_failed";
28 readonly payload: unknown;
29 }
30
31 export interface CodexAppServerIncomingNotification {
32 readonly method: string;
33 readonly params?: unknown;
34 }
35
36 export interface CodexAppServerIncomingRequest {
37 readonly id: string | number;
38 readonly method: string;
39 readonly params?: unknown;
40 }
41
42 export interface CodexAppServerPatchedProtocolOptions {
43 readonly stdio: Stdio.Stdio;
44 readonly terminationError?: Effect.Effect<CodexError.CodexAppServerError>;
45 readonly logIncoming?: boolean;
46 readonly logOutgoing?: boolean;
47 // Test override; production uses MAX_INCOMING_MESSAGE_BYTES.
48 readonly maxIncomingMessageBytes?: number;
49 readonly logger?: (event: CodexAppServerProtocolLogEvent) => Effect.Effect<void, never>;
50 readonly onNotification?: (
51 notification: CodexAppServerIncomingNotification,
52 ) => Effect.Effect<void, never>;
53 readonly onRequest?: (
54 request: CodexAppServerIncomingRequest,
55 ) => Effect.Effect<unknown, CodexError.CodexAppServerError>;
56 readonly onTermination?: (error: CodexError.CodexAppServerError) => Effect.Effect<void, never>;
57 }
58
59 export interface CodexAppServerPatchedProtocol {
60 readonly incomingNotifications: Stream.Stream<CodexAppServerIncomingNotification>;
61 readonly incomingRequests: Stream.Stream<CodexAppServerIncomingRequest>;
62 readonly request: (
63 method: string,
64 payload?: unknown,
65 ) => Effect.Effect<unknown, CodexError.CodexAppServerError>;
66 readonly notify: (
67 method: string,
68 payload?: unknown,
69 ) => Effect.Effect<void, CodexError.CodexAppServerError>;
70 readonly respond: (
71 requestId: string | number,
72 result: unknown,
73 ) => Effect.Effect<void, CodexError.CodexAppServerError>;
74 readonly respondError: (
75 requestId: string | number,
76 error: CodexError.CodexAppServerRequestError,
77 ) => Effect.Effect<void, CodexError.CodexAppServerError>;
78 }
79
80 interface CodexAppServerPendingRequest {
81 readonly deferred: Deferred.Deferred<unknown, CodexError.CodexAppServerError>;
82 readonly method: string;
83 }
84
85 function isObject(value: unknown): value is Record<string, unknown> {
86 return typeof value === "object" && value !== null;
87 }
88
89 function isIncomingRequest(value: unknown): value is CodexAppServerIncomingRequest {
90 if (!isObject(value) || typeof value.method !== "string") {
91 return false;
92 }
93 return isJsonRpcId(value.id);
94 }
95
96 function isIncomingNotification(value: unknown): value is CodexAppServerIncomingNotification {
97 return isObject(value) && typeof value.method === "string" && !("id" in value);
98 }
99
100 function isIncomingResponse(value: unknown): value is typeof JsonRpcResponseEnvelope.Type {
101 return isJsonRpcResponseEnvelope(value);
102 }
103
104 const encodeJsonString = Schema.encodeUnknownEffect(Schema.fromJsonString(Schema.Unknown));
105 const decodeJsonString = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown));
106
107 const encodeWireMessage = (
108 message: Record<string, unknown>,
109 ): Effect.Effect<string, CodexError.CodexAppServerProtocolParseError> =>
110 encodeJsonString(message).pipe(
111 Effect.map((encoded) => `${encoded}\n`),
112 Effect.mapError((cause) => {
113 const method = typeof message.method === "string" ? message.method : undefined;
114 const requestId =
115 typeof message.id === "string" || typeof message.id === "number"
116 ? String(message.id)
117 : undefined;
118 return CodexError.CodexAppServerProtocolParseError.fromSchemaError(
119 "encode-wire-message",
120 cause,
121 {
122 ...(method === undefined ? {} : { method }),
123 ...(requestId === undefined ? {} : { requestId }),
124 },
125 );
126 }),
127 );
128
129 const decodeWireMessage = (
130 line: string,
131 ): Effect.Effect<unknown, CodexError.CodexAppServerProtocolParseError> =>
132 decodeJsonString(line).pipe(
133 Effect.mapError((cause) =>
134 CodexError.CodexAppServerProtocolParseError.fromSchemaError("decode-wire-message", cause),
135 ),
136 );
137
138 const normalizeIncomingError = (
139 error: unknown,
140 operation: CodexError.CodexAppServerTransportOperation,
141 ): CodexError.CodexAppServerError =>
142 isCodexAppServerError(error)
143 ? error
144 : new CodexError.CodexAppServerTransportError({
145 operation,
146 cause: error,
147 });
148
149 const toProtocolMessage = (
150 requestId: string | number,
151 fields: {
152 readonly result?: unknown;
153 readonly error?: CodexError.CodexAppServerProtocolErrorShape;
154 },
155 ): { readonly [key: string]: unknown } => ({
156 id: requestId,
157 ...(fields.result !== undefined ? { result: fields.result } : {}),
158 ...(fields.error !== undefined ? { error: fields.error } : {}),
159 });
160
161 export const makeCodexAppServerPatchedProtocol = Effect.fn("makeCodexAppServerPatchedProtocol")(
162 function* (
163 options: CodexAppServerPatchedProtocolOptions,
164 ): Effect.fn.Return<CodexAppServerPatchedProtocol, never, Scope.Scope> {
165 const protocolScope = yield* Scope.Scope;
166 const requestHandlerScope = yield* Scope.fork(protocolScope, "parallel");
167 const outgoing = yield* Queue.unbounded<string, Cause.Done<void>>();
168 const incomingNotifications =
169 yield* Queue.sliding<CodexAppServerIncomingNotification>(MAX_BUFFERED_RAW_MESSAGES);
170 const incomingRequests =
171 yield* Queue.sliding<CodexAppServerIncomingRequest>(MAX_BUFFERED_RAW_MESSAGES);
172 const pending = yield* Ref.make(new Map<string, CodexAppServerPendingRequest>());
173 const nextRequestId = yield* Ref.make(1);
174 const maxIncomingMessageBytes = options.maxIncomingMessageBytes ?? MAX_INCOMING_MESSAGE_BYTES;
175 const remainder: Array<string> = [];
176 let remainderBytes = 0;
177 const terminationHandled = yield* Ref.make(false);
178 const terminationFailure = yield* Ref.make(Option.none<CodexError.CodexAppServerError>());
179 const terminationSignal = yield* Deferred.make<void>();
180 const activeRequestHandlers = yield* Ref.make(0);
181 const requestHandlers = yield* FiberMap.make<string | number>().pipe(
182 Scope.provide(requestHandlerScope),
183 );
184
185 const logProtocol = (event: CodexAppServerProtocolLogEvent) => {
186 if (event.direction === "incoming" && !options.logIncoming) {
187 return Effect.void;
188 }
189 if (event.direction === "outgoing" && !options.logOutgoing) {
190 return Effect.void;
191 }
192 return (
193 options.logger?.(event) ??
194 Effect.logDebug("Codex App Server protocol event").pipe(Effect.annotateLogs({ event }))
195 );
196 };
197
198 const failAllPending = (error: CodexError.CodexAppServerError) =>
199 Ref.get(pending).pipe(
200 Effect.flatMap((current) =>
201 Effect.forEach([...current.values()], ({ deferred }) => Deferred.fail(deferred, error), {
202 discard: true,
203 }),
204 ),
205 Effect.andThen(Ref.set(pending, new Map())),
206 );
207
208 const handleTermination = (classify: () => Effect.Effect<CodexError.CodexAppServerError>) =>
209 Ref.modify(terminationHandled, (handled) => {
210 if (handled) {
211 return [Effect.void, true] as const;
212 }
213 return [
214 Effect.gen(function* () {
215 const error = yield* classify();
216 yield* Ref.set(terminationFailure, Option.some(error));
217 yield* failAllPending(error);
218 yield* Queue.end(outgoing);
219 yield* Deferred.succeed(terminationSignal, undefined);
220 yield* Scope.close(requestHandlerScope, Exit.void).pipe(
221 Effect.forkIn(protocolScope, { startImmediately: true }),
222 Effect.asVoid,
223 );
224 if (options.onTermination) {
225 yield* options.onTermination(error);
226 }
227 }),
228 true,
229 ] as const;
230 }).pipe(Effect.flatten);
231
232 // Node ends stdout before it reports the exit of a crashed process, so wait briefly
233 // for the exit status. Pipes can also close while the process keeps running, so the
234 // wait must not hang pending requests.
235 const exitStatusOr = (
236 fallback: CodexError.CodexAppServerError,
237 operation: "read-input-stream" | "write-output-stream",
238 ) =>
239 options.terminationError === undefined
240 ? Effect.succeed(fallback)
241 : options.terminationError.pipe(
242 Effect.timeoutOrElse({
243 duration: EXIT_STATUS_GRACE,
244 orElse: () => Effect.succeed(fallback),
245 }),
246 // A defect here would leave termination marked handled but unfinished.
247 Effect.catchDefect((cause) =>
248 Effect.succeed(new CodexError.CodexAppServerTransportError({ operation, cause })),
249 ),
250 );
251
252 const offerOutgoing =
253 /* Every protocol write reaches this helper; request spans cover the operation. */
254 Effect.fnUntraced(function* (message: Record<string, unknown>) {
255 const failure = yield* Ref.get(terminationFailure);
256 if (Option.isSome(failure)) return yield* failure.value;
257
258 yield* logProtocol({
259 direction: "outgoing",
260 stage: "decoded",
261 payload: message,
262 });
263 const encoded = yield* encodeWireMessage(message);
264 yield* logProtocol({
265 direction: "outgoing",
266 stage: "raw",
267 payload: encoded,
268 });
269 const accepted = yield* Queue.offer(outgoing, encoded);
270 if (!accepted) {
271 const closed = yield* Ref.get(terminationFailure);
272 return yield* Option.getOrElse(
273 closed,
274 () => new CodexError.CodexAppServerInputStreamEndedError({}),
275 );
276 }
277 });
278
279 const removePending = (requestId: string) =>
280 Ref.update(pending, (current) => {
281 if (!current.has(requestId)) {
282 return current;
283 }
284 const next = new Map(current);
285 next.delete(requestId);
286 return next;
287 });
288
289 const resolvePending = (
290 requestId: string,
291 handler: (pendingRequest: CodexAppServerPendingRequest) => Effect.Effect<void>,
292 ) =>
293 Ref.modify(pending, (current) => {
294 const pendingRequest = current.get(requestId);
295 if (!pendingRequest) {
296 return [Effect.void, current] as const;
297 }
298 const next = new Map(current);
299 next.delete(requestId);
300 return [handler(pendingRequest), next] as const;
301 }).pipe(Effect.flatten);
302
303 const respond = (requestId: string | number, result: unknown) =>
304 offerOutgoing(toProtocolMessage(requestId, { result }));
305
306 const respondError = (
307 requestId: string | number,
308 error: CodexError.CodexAppServerRequestError,
309 ) => offerOutgoing(toProtocolMessage(requestId, { error: error.toProtocolError() }));
310
311 const handleResponse = (response: typeof JsonRpcResponseEnvelope.Type) => {
312 const requestId = String(response.id);
313 const protocolError = response.error;
314 if (protocolError !== undefined) {
315 return resolvePending(requestId, ({ deferred, method }) =>
316 Deferred.fail(
317 deferred,
318 CodexError.CodexAppServerRequestError.fromProtocolError(
319 protocolError,
320 method,
321 requestId,
322 ),
323 ),
324 );
325 }
326 return resolvePending(requestId, ({ deferred }) =>
327 Deferred.succeed(deferred, response.result),
328 );
329 };
330
331 const handleRequest = (request: CodexAppServerIncomingRequest) =>
332 Queue.offer(incomingRequests, request).pipe(
333 Effect.flatMap(() => {
334 const handler = options.onRequest;
335 if (!handler) return Effect.void;
336
337 return Ref.modify(activeRequestHandlers, (count) =>
338 count >= MAX_BUFFERED_RAW_MESSAGES ? [false, count] : [true, count + 1],
339 ).pipe(
340 Effect.flatMap((accepted) => {
341 if (!accepted) {
342 return respondError(
343 request.id,
344 CodexError.CodexAppServerRequestError.overloaded(
345 "Too many Codex requests are already active.",
346 ),
347 );
348 }
349
350 return Effect.suspend(() => handler(request)).pipe(
351 // Adapter handlers end in Effect.orDie; Codex waits for an answer regardless.
352 Effect.catchDefect(() =>
353 Effect.logError("Codex request handler failed").pipe(
354 Effect.annotateLogs({
355 method:
356 request.method in CodexRpc.SERVER_REQUEST_PARAMS
357 ? request.method
358 : "unknown",
359 }),
360 Effect.andThen(
361 Effect.fail(CodexError.CodexAppServerRequestError.internalError()),
362 ),
363 ),
364 ),
365 Effect.matchEffect({
366 onFailure: (error) =>
367 respondError(
368 request.id,
369 CodexError.CodexAppServerRequestError.fromAppServerError(
370 error,
371 request.method,
372 ),
373 ),
374 onSuccess: (result) => respond(request.id, result),
375 }),
376 Effect.ensuring(
377 Ref.update(activeRequestHandlers, (count) => Math.max(0, count - 1)),
378 ),
379 Effect.catch((error) =>
380 handleTermination(() => Effect.succeed(error)).pipe(
381 Effect.forkIn(protocolScope),
382 Effect.asVoid,
383 ),
384 ),
385 FiberMap.run(requestHandlers, request.id),
386 Effect.asVoid,
387 );
388 }),
389 );
390 }),
391 Effect.asVoid,
392 );
393
394 // Codex settles requests itself when their turn ends; a handler still waiting would hold its slot.
395 const releaseResolvedRequest = (notification: CodexAppServerIncomingNotification) =>
396 notification.method === "serverRequest/resolved" &&
397 isObject(notification.params) &&
398 isJsonRpcId(notification.params.requestId)
399 ? FiberMap.remove(requestHandlers, notification.params.requestId)
400 : Effect.void;
401
402 const handleNotification = (notification: CodexAppServerIncomingNotification) =>
403 releaseResolvedRequest(notification).pipe(
404 Effect.andThen(Queue.offer(incomingNotifications, notification)),
405 Effect.andThen(options.onNotification ? options.onNotification(notification) : Effect.void),
406 Effect.asVoid,
407 );
408
409 const routeMessage = Effect.fnUntraced(function* (message: unknown) {
410 if (Option.isSome(yield* Ref.get(terminationFailure))) return;
411 if (isIncomingRequest(message)) return yield* handleRequest(message);
412 if (isIncomingNotification(message)) return yield* handleNotification(message);
413 if (isIncomingResponse(message)) return yield* handleResponse(message);
414 return yield* CodexError.CodexAppServerProtocolParseError.fromUnroutableMessage(message);
415 });
416
417 const handleLine = (line: string): Effect.Effect<void, CodexError.CodexAppServerError> => {
418 if (line.trim().length === 0) {
419 return Effect.void;
420 }
421 return logProtocol({
422 direction: "incoming",
423 stage: "raw",
424 payload: line,
425 }).pipe(
426 Effect.flatMap(() => decodeWireMessage(line)),
427 Effect.tap((decoded) =>
428 logProtocol({
429 direction: "incoming",
430 stage: "decoded",
431 payload: decoded,
432 }),
433 ),
434 Effect.tapErrorTag("CodexAppServerProtocolParseError", (error) =>
435 logProtocol({
436 direction: "incoming",
437 stage: "decode_failed",
438 payload: {
439 operation: error.operation,
440 ...(error.method === undefined ? {} : { method: error.method }),
441 ...(error.requestId === undefined ? {} : { requestId: error.requestId }),
442 ...(error.issueCount === undefined ? {} : { issueCount: error.issueCount }),
443 ...(error.issueKinds === undefined ? {} : { issueKinds: error.issueKinds }),
444 ...(error.maximumPathDepth === undefined
445 ? {}
446 : { maximumPathDepth: error.maximumPathDepth }),
447 },
448 }),
449 ),
450 Effect.flatMap(routeMessage),
451 );
452 };
453
454 yield* options.stdio.stdin.pipe(
455 Stream.interruptWhen(Deferred.await(terminationSignal)),
456 Stream.decodeText(),
457 Stream.runForEach(
458 Effect.fnUntraced(function* (chunk) {
459 let start = 0;
460 while (start < chunk.length) {
461 const newline = chunk.indexOf("\n", start);
462 const fragment = chunk.slice(start, newline === -1 ? chunk.length : newline);
463 // decodeText holds back split UTF-8 sequences, so fragment byte sums are exact.
464 remainderBytes += Buffer.byteLength(fragment, "utf8");
465 if (remainderBytes > maxIncomingMessageBytes) {
466 remainder.length = 0;
467 return yield* new CodexError.CodexAppServerTransportError({
468 operation: "read-input-stream",
469 cause: new Error(`Incoming message exceeded ${maxIncomingMessageBytes} bytes.`),
470 });
471 }
472 remainder.push(fragment);
473 if (newline === -1) break;
474 const line = remainder.join("").replace(/\r$/, "");
475 remainder.length = 0;
476 remainderBytes = 0;
477 yield* handleLine(line);
478 start = newline + 1;
479 }
480 }),
481 ),
482 Effect.matchEffect({
483 onFailure: (error) =>
484 handleTermination(() =>
485 Effect.succeed(normalizeIncomingError(error, "read-input-stream")),
486 ),
487 onSuccess: () =>
488 Effect.sync(() => {
489 const line = remainder.join("");
490 remainder.length = 0;
491 return line;
492 }).pipe(
493 Effect.flatMap(handleLine),
494 Effect.matchEffect({
495 onFailure: (error) => handleTermination(() => Effect.succeed(error)),
496 onSuccess: () =>
497 handleTermination(() =>
498 exitStatusOr(
499 new CodexError.CodexAppServerInputStreamEndedError({}),
500 "read-input-stream",
501 ),
502 ),
503 }),
504 ),
505 }),
506 Effect.catchCause((cause) =>
507 handleTermination(() =>
508 Effect.succeed(
509 new CodexError.CodexAppServerTransportError({
510 operation: "read-input-stream",
511 cause: Cause.squash(cause),
512 }),
513 ),
514 ),
515 ),
516 Effect.forkScoped,
517 );
518
519 yield* Stream.fromQueue(outgoing).pipe(
520 Stream.run(options.stdio.stdout()),
521 Effect.catchCause((cause) =>
522 handleTermination(() =>
523 // Writing to a process that already exited fails with EPIPE; report the exit.
524 exitStatusOr(
525 new CodexError.CodexAppServerTransportError({
526 operation: "write-output-stream",
527 cause: Cause.squash(cause),
528 }),
529 "write-output-stream",
530 ),
531 ),
532 ),
533 Effect.forkScoped,
534 );
535
536 const request = Effect.fn("CodexAppServerProtocol.request")(function* (
537 method: string,
538 payload?: unknown,
539 ) {
540 const requestId = yield* Ref.modify(
541 nextRequestId,
542 (current) => [current, current + 1] as const,
543 );
544 const attributes = {
545 "rpc.system": "jsonrpc",
546 "rpc.method": method,
547 "rpc.request_id": requestId,
548 };
549 yield* Effect.annotateCurrentSpan(attributes);
550 const deferred = yield* Deferred.make<unknown, CodexError.CodexAppServerError>();
551 return yield* Effect.acquireUseRelease(
552 Ref.update(pending, (current) =>
553 new Map(current).set(String(requestId), { deferred, method }),
554 ),
555 () =>
556 Effect.gen(function* () {
557 yield* offerOutgoing({
558 id: requestId,
559 method,
560 ...(payload !== undefined ? { params: payload } : {}),
561 }).pipe(Effect.withSpan("CodexAppServerProtocol.request.enqueue", { attributes }));
562 // Includes queue/stdin delivery, Codex work and response routing, not just T3 CPU.
563 return yield* Deferred.await(deferred).pipe(
564 Effect.withSpan("CodexAppServerProtocol.request.awaitResponse", { attributes }),
565 );
566 }),
567 () => removePending(String(requestId)),
568 );
569 });
570
571 const notify = (method: string, payload?: unknown) =>
572 offerOutgoing({
573 method,
574 ...(payload !== undefined ? { params: payload } : {}),
575 });
576
577 return {
578 incomingNotifications: Stream.fromQueue(incomingNotifications),
579 incomingRequests: Stream.fromQueue(incomingRequests),
580 request,
581 notify,
582 respond,
583 respondError,
584 } satisfies CodexAppServerPatchedProtocol;
585 },
586 );