TypeScript SDK Thread.run() treats fatal stream errors as successful empty turns

Open 💬 2 comments Opened May 13, 2026 by chanwooyang1

What issue are you seeing?

The TypeScript SDK defines a top-level fatal stream error event, but Thread.run() does not handle it.

ThreadErrorEvent is defined in sdk/typescript/src/events.ts as:

export type ThreadErrorEvent = {
  type: "error";
  message: string;
};

and it is included in the ThreadEvent union.

However, Thread.run() in sdk/typescript/src/thread.ts only handles:

  • item.completed
  • turn.completed
  • turn.failed

It does not handle event.type === "error".

As a result, if the underlying CodexExec.run() stream emits a fatal top-level error event, Thread.run() resolves successfully with an empty turn instead of rejecting.

Observed result from a focused local regression test:

{
  "items": [],
  "finalResponse": "",
  "usage": null
}

This can make SDK callers interpret a fatal stream failure as a successful empty response.

What steps can reproduce the bug?

Using current openai/codex main at 155c04ad4, add a focused Jest test that stubs CodexExec.run() to emit a top-level error event:

import { Thread } from "../src/thread";

it("throws on fatal top-level stream errors", async () => {
  const exec = {
    async *run() {
      yield JSON.stringify({ type: "error", message: "fatal stream error" });
    },
  };

  const thread = new Thread(exec as never, {}, {});

  await expect(thread.run("fail")).rejects.toThrow("fatal stream error");
});

Then run:

corepack pnpm --filter @openai/codex-sdk exec jest tests/run.test.ts -t "fatal top-level" --runInBand

Current result:

Received promise resolved instead of rejected
Resolved to value: {"finalResponse": "", "items": [], "usage": null}

What is the expected behavior?

Thread.run() should reject when it receives a fatal top-level stream error event.

A narrow fix would be to handle event.type === "error" in sdk/typescript/src/thread.ts, for example by throwing new Error(event.message), and add regression coverage for this case.

Additional information

I searched existing issues and PRs for Thread.run, runStreamed, ThreadErrorEvent, top-level stream errors, and TypeScript SDK stream error handling, and did not find an exact duplicate.

This is separate from normal turn.failed handling. The issue is specifically that the SDK event union already includes a top-level ThreadErrorEvent, but the buffered Thread.run() API ignores it.

View original on GitHub ↗

2 Comments

chanwooyang1 · 3 months ago

I prepared a narrow fix and regression test in my fork here:

https://github.com/chanwooyang1/codex/tree/fix/thread-run-top-level-errors

This branch is rebased on the latest openai/codex main as of May 16, 2026.

Summary:

  • handle top-level event.type === "error" in Thread.run() by throwing new Error(event.message)
  • add regression coverage that stubs CodexExec.run() to emit { type: "error", message: "fatal stream error" }
  • confirmed the regression test fails before the fix by resolving to an empty successful turn, and passes after the fix

Validation:

  • corepack pnpm --filter @openai/codex-sdk exec jest tests/run.test.ts -t "top-level stream errors" --runInBand
  • corepack pnpm --filter @openai/codex-sdk lint
  • corepack pnpm --filter @openai/codex-sdk format
  • corepack pnpm --filter @openai/codex-sdk build

I also attempted the full SDK Jest suite, but my local checkout did not have codex-rs/target/debug/codex; building that binary failed locally in webrtc-sys C++ compilation, so I could not complete the full-suite run on this machine.

If this direction looks right, I’d be happy to open a PR if invited, following the repo’s contribution policy.

bongsu-rapportlabs · 3 months ago

Related TypeScript SDK stream-handling issue with a small candidate patch: #23131

Different failure mode, but same area of code (sdk/typescript/src/thread.ts): in #23131 the streamed event fails before callers receive a parsed ThreadEvent because a large MCP item.completed payload can be split inside a JSON string. I added a bounded-buffer parser patch and regression test there.

Linking in case maintainers batch SDK stream robustness fixes together.