feat: add dual esm + cjs build with shim guard, updated exports, and lambda support

[vrtnis]

Hey @seratch, here’s the PR. It’s been tested locally and directly on AWS Lambda. A lambda-local test is included in the PR, and I’ve documented the steps for building and testing on Lambda itself in this gist

• Dual build – every public package now emits:

  • dist/ → ES 2022 (unchanged, ESM users are unaffected – import keeps loading the original ES modules.)
  • dist-cjs/ → CommonJS (module: "commonjs")

• Exports wiring – main, exports.import/require, and types point at the correct build for every sub-path (./realtime, ./utils, _shims…).

• Shim guard – loadEnv() now uses:

  try { const m = (0, eval)('import.meta'); … } catch {}

so require() no longer crashes in CJS runtimes.

• Realtime CJS build – @openai/agents-realtime gets its own dist-cjs/ output and is fully exported.

• Integration tests:

  • integration-tests/esm-import – proves dynamic import() on Node 22
  • integration-tests/lambda-local – spins up lambda-local and asserts a 200 response from a CommonJS handler that uses both Agent and OpenAIRealtimeWebSocket.

• Changeset – bumps all affected packages with a patch release.

Some thoughts:

We can run the realtime transport inside the same CJS process that handles Twilio events, enabling “live call” use‑cases without extra shims. Also, we can just drop the SDK into Twilio Functions or a Flex Plugin without converting the whole workspace to ESM or adding a bundler step. (Overall, better DX for TS code bases that remain on CJS.)

Of course, AWS Lambda, Azure Functions, and Google Cloud Functions all support native ESM, but every one of them still defaults to CJS for a typical “zip‑and‑upload” or framework‑generated project.

Because the Agents SDK now ships a first‑class CJS build, we can drop it into those default workflows without extra flags or custom runtimes. (If a team is already running an explicit ESM handler e.g. .mjs file or "type":"module"then the existing ESM build continues to work.)

Happy to address any feedback, please feel free to convert this to a draft for further review if needed. Thanks!

Resolves #245 and resolves #213

[changeset-bot]

🦋 Changeset detected

Latest commit: 80cdb88

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
@openai/agents-extensions	Patch
@openai/agents-realtime	Patch
@openai/agents-openai	Patch
@openai/agents-core	Patch
@openai/agents	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[seratch]

Thanks for sending this. I didn't have time for checking this repo today, but will check this one and #258 to resolve this issue soon.

[seratch]

Thanks for sending this. I am now checking this branch on my local machine.

First thing I noticed is these warnings introduced in this PR. Can you take a look?

➜  openai-agents-js git:(vrtnis-fix/esm-cjs-refactor) ✗ pnpm build

> [email protected] prebuild /Users/seratch/code/openai-agents-js
> pnpm -F @openai/* -r prebuild

Scope: 5 of 22 workspace projects
packages/agents-core prebuild$ tsx ../../scripts/embedMeta.ts
└─ Done in 147ms
packages/agents-openai prebuild$ tsx ../../scripts/embedMeta.ts
└─ Done in 169ms
packages/agents-realtime prebuild$ tsx ../../scripts/embedMeta.ts
└─ Done in 168ms
packages/agents prebuild$ tsx ../../scripts/embedMeta.ts
└─ Done in 148ms
packages/agents-extensions prebuild$ tsx ../../scripts/embedMeta.ts
└─ Done in 150ms

> [email protected] build /Users/seratch/code/openai-agents-js
> npm run build:esm && npm run build:cjs

npm warn Unknown env config "_--openai-registry". This will stop working in the next major version of npm.
npm warn Unknown env config "publish-branch". This will stop working in the next major version of npm.
npm warn Unknown env config "verify-deps-before-run". This will stop working in the next major version of npm.
npm warn Unknown env config "_jsr-registry". This will stop working in the next major version of npm.
npm warn Unknown env config "node-linker". This will stop working in the next major version of npm.
npm warn Unknown env config "_---openai-registry". This will stop working in the next major version of npm.
npm warn Unknown project config "node-linker". This will stop working in the next major version of npm.

> [email protected] build:esm
> tsc-multi

[mjs]: Found 0 errors.
[js]: Found 0 errors.
npm warn Unknown env config "_--openai-registry". This will stop working in the next major version of npm.
npm warn Unknown env config "publish-branch". This will stop working in the next major version of npm.
npm warn Unknown env config "verify-deps-before-run". This will stop working in the next major version of npm.
npm warn Unknown env config "_jsr-registry". This will stop working in the next major version of npm.
npm warn Unknown env config "node-linker". This will stop working in the next major version of npm.
npm warn Unknown env config "_---openai-registry". This will stop working in the next major version of npm.
npm warn Unknown project config "node-linker". This will stop working in the next major version of npm.

> [email protected] build:cjs
> tsc-multi --config tsc-multi.cjs.json

[cjs]: Found 0 errors.

> [email protected] postbuild /Users/seratch/code/openai-agents-js
> pnpm -r -F @openai/* bundle

Scope: 5 of 22 workspace projects
packages/agents-realtime bundle$ vite build
│ vite v6.3.5 building for production...
│ transforming...
│ ✓ 209 modules transformed.
│ rendering chunks...
│ computing gzip size...
│ dist/bundle/openai-realtime-agents.mjs  1,857.68 kB │ gzip: 416.00 kB │ map: 1,116.10 kB
│ ✓ built in 451ms
└─ Done in 596ms

Also, when I go through these steps here, pnpm test:integration fails for the following tests while those tests pass with :

[vite-react] Building

 ❯ integration-tests/vite-react.test.ts (1 test | 1 skipped) 12872ms
   ↓ Vite React > should be able to run
 ❯ integration-tests/cloudflare.test.ts (1 test | 1 skipped) 60008ms
   ↓ Cloudflare Workers > should be able to run

So, something needs to be addressed.

I will look into alternative solutions for this too.

[seratch]

My #346 should resolve this issue; if you have any comments, please feel free to write in.

[vrtnis]

Thanks for flagging! I reproduced the warnings/errors locally. I've updated the root build script to call tsc-multi directly (like upstream main - instead of chaining through npm run, which was triggering the .npmrc warnings.)

Also fixed CJS build type errors in TwilioRealtimeTransportLayer by guarding emit, on, and updateSessionConfig calls with (this as any)/optional chaining so they compile across sdk versions without altering behavior.

Both ESM and CJS builds now run clean, and verdaccio + integration tests pass here. Happy to dig in further if you see issues. BTW I can to rebase #333 on top of #346 based on your guidance on that thread.

[seratch]

Closing in favor of #346