fix(codex): say why the Codex app-server exited

packages/effect-codex-app-server/src/_internal/stdio.test.ts

@@ -4,7 +4,7 @@ import * as PlatformError from "effect/PlatformError";
 import { ChildProcessSpawner } from "effect/process";
 
 import * as CodexError from "../errors.ts";
-import { makeTerminationError } from "./stdio.ts";
+import { appendStderrTail, makeTerminationError, stderrExcerpt } from "./stdio.ts";
 
 describe("Codex App Server child process termination", () => {
   it.effect("retains the process identifier and exact exit-status cause", () =>
@@ -16,10 +16,13 @@ describe("Codex App Server child process termination", () => {
         method: "exitCode",
         cause: rootCause,
       });
-      const error = yield* makeTerminationError({
-        pid: ChildProcessSpawner.ProcessId(52),
-        exitCode: Effect.fail(cause),
-      });
+      const error = yield* makeTerminationError(
+        {
+          pid: ChildProcessSpawner.ProcessId(52),
+          exitCode: Effect.fail(cause),
+        },
+        Effect.succeed(""),
+      );
 
       assert.instanceOf(error, CodexError.CodexAppServerTransportError);
       assert.equal(error.pid, 52);
@@ -31,4 +34,102 @@ describe("Codex App Server child process termination", () => {
       assert.notInclude(error.message, rootCause.message);
     }),
   );
+
+  it.effect("names the stderr error line when the process exits", () =>
+    Effect.gen(function* () {
+      const error = yield* makeTerminationError(
+        {
+          pid: ChildProcessSpawner.ProcessId(53),
+          exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(1)),
+        },
+        Effect.succeed("Error: Missing optional dependency @openai/codex-darwin-arm64.\n"),
+      );
+
+      assert.instanceOf(error, CodexError.CodexAppServerProcessExitedError);
+      assert.equal(error.stderr, "Error: Missing optional dependency @openai/codex-darwin-arm64.");
+      assert.equal(
+        error.message,
+        "Codex App Server process exited with code 1: Error: Missing optional dependency @openai/codex-darwin-arm64.",
+      );
+    }),
+  );
+
+  it.effect("keeps the bare exit message when stderr is empty", () =>
+    Effect.gen(function* () {
+      const error = yield* makeTerminationError(
+        {
+          pid: ChildProcessSpawner.ProcessId(54),
+          exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(1)),
+        },
+        Effect.succeed(" \n\n"),
+      );
+
+      assert.instanceOf(error, CodexError.CodexAppServerProcessExitedError);
+      assert.isUndefined(error.stderr);
+      assert.equal(error.message, "Codex App Server process exited with code 1");
+    }),
+  );
+});
+
+describe("Codex App Server stderr excerpt", () => {
+  it.each([
+    {
+      name: "Node launcher missing its platform package",
+      stderr: [
+        "file:///usr/local/lib/node_modules/@openai/codex/bin/codex.js:107",
+        "  throw new Error(",
+        "        ^",
+        "",
+        "Error: Missing optional dependency @openai/codex-darwin-arm64. Reinstall Codex: npm install -g @openai/codex@latest",
+        "    at findCodexExecutable (file:///usr/local/lib/node_modules/@openai/codex/bin/codex.js:107:9)",
+        "    at file:///usr/local/lib/node_modules/@openai/codex/bin/codex.js:112:20",
+        "",
+        "Node.js v26.8.2",
+        "",
+      ].join("\n"),
+      excerpt:
+        "Error: Missing optional dependency @openai/codex-darwin-arm64. Reinstall Codex: npm install -g @openai/codex@latest",
+    },
+    {
+      name: "Node error with a code",
+      stderr:
+        "node:internal/modules/esm/resolve:873\n  throw new ERR_MODULE_NOT_FOUND(\n\nError [ERR_MODULE_NOT_FOUND]: Cannot find package 'x'\n    at packageResolve (node:internal/modules/esm/resolve:873:9)\n",
+      excerpt: "Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'x'",
+    },
+    {
+      name: "Rust CLI error",
+      stderr: "error: unexpected argument 'app-server' found\n\nUsage: codex [OPTIONS]\n",
+      excerpt: "error: unexpected argument 'app-server' found",
+    },
+    {
+      name: "unlabelled message",
+      stderr: "WARNING: proceeding without PATH aliases\nMissing OpenAI API key.\n",
+      excerpt: "Missing OpenAI API key.",
+    },
+    {
+      name: "ANSI color, carriage returns and repeated whitespace",
+      stderr: "\u001b[31m  Error:\t  config.toml   is invalid \u001b[0m\r\n",
+      excerpt: "Error: config.toml is invalid",
+    },
+    {
+      name: "oversized line",
+      stderr: `Error: ${"x".repeat(1_000)}`,
+      excerpt: `Error: ${"x".repeat(504)}…`,
+    },
+  ])("$name", ({ stderr, excerpt }) => {
+    assert.equal(stderrExcerpt(stderr), excerpt);
+    assert.isAtMost(excerpt.length, 512);
+  });
+
+  it("returns nothing for blank stderr", () => {
+    assert.isUndefined(stderrExcerpt("\n \t\r\n\u001b[0m\n"));
+  });
+
+  it("keeps only the newest stderr", () => {
+    const tail = appendStderrTail("a".repeat(8_000), `${"b".repeat(400)}\nError: last`);
+
+    assert.equal(tail.length, 8_192);
+    assert.isTrue(tail.endsWith("Error: last"));
+    assert.equal(stderrExcerpt(tail), "Error: last");
+  });
 });

packages/effect-codex-app-server/src/_internal/stdio.ts

@@ -1,6 +1,8 @@
 import * as Cause from "effect/Cause";
+import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
 import * as Queue from "effect/Queue";
+import * as Ref from "effect/Ref";
 import * as Sink from "effect/Sink";
 import * as Stdio from "effect/Stdio";
 import * as Stream from "effect/Stream";
@@ -44,20 +46,82 @@ export const makeInMemoryStdio = Effect.fn("makeInMemoryStdio")(function* () {
   };
 });
 
+const STDERR_TAIL_MAX_CHARS = 8_192;
+const STDERR_EXCERPT_MAX_CHARS = 512;
+// eslint-disable-next-line no-control-regex -- ANSI escape sequences start with ESC.
+const TERMINAL_CONTROL_PATTERN = /\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g;
+// `Error: …`, `TypeError: …`, `Error [ERR_MODULE_NOT_FOUND]: …`, `error: …`
+const ERROR_LINE_PATTERN = /^(?:[A-Za-z]*Error|error|fatal)(?: ?\[[^\]]+\])?:\s*\S/;
+
+export const appendStderrTail = (current: string, chunk: string): string => {
+  const next = `${current}${chunk}`;
+  return next.length <= STDERR_TAIL_MAX_CHARS ? next : next.slice(-STDERR_TAIL_MAX_CHARS);
+};
+
+/**
+ * The stderr line that names the failure: the last error-labelled line, else the last line.
+ * A Node launcher prints its thrown error between a source excerpt and the stack frames.
+ */
+export const stderrExcerpt = (tail: string): string | undefined => {
+  const lines = tail
+    .replace(TERMINAL_CONTROL_PATTERN, "")
+    .split(/\r?\n/)
+    .map((line) => line.trim().replace(/\s+/g, " "))
+    .filter((line) => line.length > 0);
+  const line = lines.findLast((candidate) => ERROR_LINE_PATTERN.test(candidate)) ?? lines.at(-1);
+  if (line === undefined) {
+    return undefined;
+  }
+  return line.length <= STDERR_EXCERPT_MAX_CHARS
+    ? line
+    : `${line.slice(0, STDERR_EXCERPT_MAX_CHARS - 1)}…`;
+};
+
+export const makeStderrTail = Effect.fn("makeStderrTail")(function* (
+  stderr: ChildProcessSpawner.ChildProcessHandle["stderr"],
+) {
+  const tail = yield* Ref.make("");
+  const drained = yield* Deferred.make<void>();
+  yield* stderr.pipe(
+    Stream.decodeText(),
+    Stream.runForEach((chunk) => Ref.update(tail, (current) => appendStderrTail(current, chunk))),
+    Effect.ignore,
+    Effect.ensuring(Deferred.succeed(drained, undefined)),
+    Effect.forkScoped,
+  );
+  // The exit status can arrive before the last stderr chunk has been read.
+  return Deferred.await(drained).pipe(
+    Effect.timeout("250 millis"),
+    Effect.ignore,
+    Effect.andThen(Ref.get(tail)),
+  );
+});
+
 type ChildProcessTerminationHandle = Pick<
   ChildProcessSpawner.ChildProcessHandle,
   "exitCode" | "pid"
 >;
 
 export const makeTerminationError = (
   handle: ChildProcessTerminationHandle,
+  stderrTail: Effect.Effect<string>,
 ): Effect.Effect<CodexError.CodexAppServerError> =>
-  Effect.match(handle.exitCode, {
+  Effect.matchEffect(handle.exitCode, {
     onFailure: (cause) =>
-      new CodexError.CodexAppServerTransportError({
-        operation: "read-process-exit-status",
-        pid: handle.pid,
-        cause,
+      Effect.succeed(
+        new CodexError.CodexAppServerTransportError({
+          operation: "read-process-exit-status",
+          pid: handle.pid,
+          cause,
+        }),
+      ),
+    onSuccess: (code) =>
+      Effect.map(stderrTail, (tail) => {
+        const stderr = stderrExcerpt(tail);
+        return new CodexError.CodexAppServerProcessExitedError({
+          code,
+          pid: handle.pid,
+          ...(stderr ? { stderr } : {}),
+        });
       }),
-    onSuccess: (code) => new CodexError.CodexAppServerProcessExitedError({ code, pid: handle.pid }),
   });

packages/effect-codex-app-server/src/client.test.ts

@@ -10,6 +10,7 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, it } from "@effect/vitest";
 
 import * as CodexClient from "./client.ts";
+import * as CodexError from "./errors.ts";
 
 const mockPeerPath = Effect.map(Effect.service(Path.Path), (path) =>
   path.join(import.meta.dirname, "../test/fixtures/codex-app-server-mock-peer.ts"),
@@ -155,4 +156,44 @@ it.layer(NodeServices.layer)("effect-codex-app-server client", (it) => {
       assert.equal(initialized.userAgent, "mock-codex-app-server");
     }),
   );
+
+  it.effect("reports the stderr error when the process exits before initialize", () =>
+    Effect.gen(function* () {
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+      const handle = yield* spawner.spawn(
+        ChildProcess.make(process.execPath, [
+          "-e",
+          'throw new Error("Missing optional dependency @openai/codex-darwin-arm64. Reinstall Codex: npm install -g @openai/codex@latest")',
+        ]),
+      );
+      const scope = yield* Scope.make();
+      const context = yield* Layer.buildWithScope(CodexClient.layerChildProcess(handle), scope);
+
+      const error = yield* Effect.gen(function* () {
+        const client = yield* CodexClient.CodexAppServerClient;
+        return yield* client.request("initialize", {
+          clientInfo: {
+            name: "effect-codex-app-server-test",
+            title: "Effect Codex App Server Test",
+            version: "0.0.0",
+          },
+          capabilities: {
+            experimentalApi: true,
+            optOutNotificationMethods: null,
+          },
+        });
+      }).pipe(
+        Effect.flip,
+        Effect.timeout("5 seconds"),
+        Effect.provide(context),
+        Effect.ensuring(Scope.close(scope, Exit.void)),
+      );
+
+      assert.instanceOf(error, CodexError.CodexAppServerProcessExitedError);
+      assert.equal(
+        error.message,
+        "Codex App Server process exited with code 1: Error: Missing optional dependency @openai/codex-darwin-arm64. Reinstall Codex: npm install -g @openai/codex@latest",
+      );
+    }),
+  );
 });

packages/effect-codex-app-server/src/client.ts

@@ -4,7 +4,6 @@ import * as Layer from "effect/Layer";
 import * as Schema from "effect/Schema";
 import * as Scope from "effect/Scope";
 import * as Stdio from "effect/Stdio";
-import * as Stream from "effect/Stream";
 import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
 
 import * as CodexRpc from "./_generated/meta.gen.ts";
@@ -17,7 +16,7 @@ import {
   encodeOptionalPayload,
   runHandler,
 } from "./_internal/shared.ts";
-import { makeChildStdio, makeTerminationError } from "./_internal/stdio.ts";
+import { makeChildStdio, makeStderrTail, makeTerminationError } from "./_internal/stdio.ts";
 
 export interface CodexAppServerClientOptions {
   readonly logIncoming?: boolean;
@@ -270,6 +269,6 @@ export const layerChildProcess = (
 const makeChildProcessClient = Effect.fn(
   "effect-codex-app-server/CodexAppServerClient.makeChildProcessClient",
 )(function* (handle: ChildProcessSpawner.ChildProcessHandle, options: CodexAppServerClientOptions) {
-  yield* Stream.runDrain(handle.stderr).pipe(Effect.ignore, Effect.forkScoped);
-  return yield* make(makeChildStdio(handle), options, makeTerminationError(handle));
+  const stderrTail = yield* makeStderrTail(handle.stderr);
+  return yield* make(makeChildStdio(handle), options, makeTerminationError(handle, stderrTail));
 });

packages/effect-codex-app-server/src/errors.ts

@@ -148,13 +148,16 @@ export class CodexAppServerProcessExitedError extends Schema.TaggedError<CodexAp
   {
     code: Schema.optional(Schema.Number),
     pid: Schema.optionalKey(Schema.Int),
+    stderr: Schema.optionalKey(Schema.String),
     cause: Schema.optional(Schema.Defect()),
   },
 ) {
   override get message() {
-    return this.code === undefined
-      ? "Codex App Server process exited"
-      : `Codex App Server process exited with code ${this.code}`;
+    const base =
+      this.code === undefined
+        ? "Codex App Server process exited"
+        : `Codex App Server process exited with code ${this.code}`;
+    return this.stderr ? `${base}: ${this.stderr}` : base;
   }
 }