chore: release v0.14.0

Author: OhadAssulin

CHANGELOG.md

@@ -1,11 +1,20 @@
 # Changelog
 
+## [0.14.0] - 2025-11-10
+### 🚀 Enhancements
+- Added `createHeadlessCodex()` helper that auto-registers the adapter and returns a coder, reducing the boilerplate needed in most server runtimes.
+- Codex adapter now enforces a Node-only runtime, guards worker spawns, and exposes the worker path via `new URL('./worker.js', import.meta.url)` so bundlers have a deterministic asset to copy.
+- README docs call out the server-only requirement and provide lazy-loading snippets for frameworks like Next.js.
+
+### 🛠 DX
+- Added runtime guards/warnings that keep browser bundlers from crashing by tree-shaking the `child_process` fork when it’s unreachable.
+
 ## [0.13.1] - 2025-11-10
 ### ✨ Packaging & DX
 - Core and every adapter now emit real entry points via `tsup`, producing both ESM (`dist/*.js`) and CommonJS (`dist/*.cjs`) bundles with colocated typings, so downstream apps can import the declared exports without diving into `dist/*/src` internals.
 - Updated exports maps to expose `factory`, `types`, adapter workers, and `package.json`, unlocking better metadata discovery and `require()` support.
 - Codex adapter gained a README that documents the worker co-location requirement, plus LICENSE files were added to every publishable package for npm completeness.
-- Bumped `@openai/codex-sdk` to `0.57.0` and refreshed peer dependency ranges to `^0.13.0` across the adapters.
+- Bumped `@openai/codex-sdk` to `0.57.0` and refreshed peer dependency ranges to `^0.14.0` across the adapters.
 
 ### 🧪 Tooling
 - Added `npm run smoke`, which builds, packs, and installs the tarballs into a throwaway project to verify both CommonJS and ESM consumers and assert that the Codex worker ships beside the entry point.

README.md

@@ -38,12 +38,9 @@ npm i @headless-coder-sdk/core @headless-coder-sdk/codex-adapter
 ```
 
 ```ts
-import { registerAdapter, createCoder } from '@headless-coder-sdk/core';
-import { CODER_NAME as CODEX, createAdapter as createCodex } from '@headless-coder-sdk/codex-adapter';
+import { createHeadlessCodex } from '@headless-coder-sdk/codex-adapter';
 
-registerAdapter(CODEX, createCodex);
-
-const coder = createCoder(CODEX);
+const coder = createHeadlessCodex({ workingDirectory: process.cwd() });
 const thread = await coder.startThread();
 const result = await thread.run('Write a hello world script');
 console.log(result.text);
@@ -239,6 +236,38 @@ In this workflow two reviewers (Claude, Codex) analyze the same commit in parall
 
 ---
 
+## ⚠️ Codex Adapter Runtime
+
+- The Codex adapter forks worker processes via Node’s `child_process` API and **must run on the server**. It is safe to import in build tooling, but gate runtime usage to environments where `process.versions.node` exists.
+- A convenience helper, `createHeadlessCodex`, registers the adapter and returns a coder in one call:
+
+  ```ts
+  import { createHeadlessCodex } from '@headless-coder-sdk/codex-adapter';
+
+  if (typeof window !== 'undefined') {
+    throw new Error('Codex adapter is server-only');
+  }
+
+  const codex = createHeadlessCodex({ workingDirectory: process.cwd() });
+  ```
+
+- In frameworks like Next.js, lazy-load the helper inside server components or API routes to avoid bundling it client-side:
+
+  ```ts
+  export async function POST() {
+    if (typeof window !== 'undefined') {
+      throw new Error('Codex must run on the server');
+    }
+    const { createHeadlessCodex } = await import('@headless-coder-sdk/codex-adapter');
+    const coder = createHeadlessCodex({ workingDirectory: process.cwd() });
+    const thread = await coder.startThread();
+    const result = await thread.run('List recent commits');
+    return Response.json({ text: result.text });
+  }
+  ```
+
+---
+
 ## ⚙️ Development
 
 **Install**
@@ -299,6 +328,7 @@ Open an [issue](https://github.com/OhadAssulin/headless-coder-sdk/issues) or sub
 ## 📦 Distribution Notes
 
 - Every workspace now emits flattened entry points at `dist/*.js` (ESM) and `dist/*.cjs` (CommonJS), with `.d.ts` files sitting beside them for better editor support.
+- You can import `createCoder` or helper utilities directly from `@headless-coder-sdk/core` and `@headless-coder-sdk/codex-adapter` without deep `dist/*/src` paths—the `main`/`module` fields now point at those root files.
 - `package.json` is exposed via the exports map (`import '@headless-coder-sdk/core/package.json'`) for tooling that needs to inspect versions at runtime.
 - `@headless-coder-sdk/codex-adapter` forks a worker via `fileURLToPath(new URL('./worker.js', import.meta.url))`; keep `dist/worker.js` adjacent when rebundling so that child processes can spawn correctly.
 

packages/claude-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headless-coder-sdk/claude-adapter",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -19,7 +19,7 @@
   },
   "peerDependencies": {
     "@anthropic-ai/claude-agent-sdk": "*",
-    "@headless-coder-sdk/core": "^0.13.0"
+    "@headless-coder-sdk/core": "^0.14.0"
   },
   "devDependencies": {
     "typescript": "^5.4.0",

packages/codex-adapter/README.md

@@ -11,16 +11,37 @@ npm install @headless-coder-sdk/core @headless-coder-sdk/codex-adapter
 ## Usage
 
 ```ts
-import { registerAdapter, createCoder } from '@headless-coder-sdk/core';
-import { CODER_NAME as CODEX, createAdapter } from '@headless-coder-sdk/codex-adapter';
+import { createHeadlessCodex } from '@headless-coder-sdk/codex-adapter';
 
-registerAdapter(CODEX, createAdapter);
-const coder = createCoder(CODEX, { workingDirectory: process.cwd() });
+if (typeof window !== 'undefined') {
+  throw new Error('Codex adapter is server-only');
+}
+
+const coder = createHeadlessCodex({ workingDirectory: process.cwd() });
 const thread = await coder.startThread();
 const turn = await thread.run('Write unit tests for the git helper.');
 console.log(turn.text);
 ```
 
+`createHeadlessCodex` registers the adapter (if necessary) and returns a coder in one call so you no longer have to wire up `registerAdapter` manually.
+
+## Next.js / server frameworks
+
+The adapter forks worker processes via Node’s `child_process`, so keep it on the server:
+
+```ts
+export async function POST() {
+  if (typeof window !== 'undefined') {
+    throw new Error('Codex adapter must run on the server');
+  }
+  const { createHeadlessCodex } = await import('@headless-coder-sdk/codex-adapter');
+  const coder = createHeadlessCodex({ workingDirectory: process.cwd() });
+  const thread = await coder.startThread();
+  const result = await thread.run('List open pull requests');
+  return Response.json({ text: result.text });
+}
+```
+
 ## Worker placement
 
 - The adapter forks a worker via `fileURLToPath(new URL('./worker.js', import.meta.url))`.

packages/codex-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headless-coder-sdk/codex-adapter",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -27,7 +27,7 @@
     "build": "tsup --config tsup.config.ts"
   },
   "peerDependencies": {
-    "@headless-coder-sdk/core": "^0.13.0",
+    "@headless-coder-sdk/core": "^0.14.0",
     "@openai/codex-sdk": "^0.57.0"
   },
   "devDependencies": {

packages/codex-adapter/src/index.ts

@@ -5,8 +5,13 @@
 
 import { fork, ChildProcess } from 'node:child_process';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { now } from '@headless-coder-sdk/core';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import {
+  now,
+  registerAdapter,
+  getAdapterFactory,
+  createCoder,
+} from '@headless-coder-sdk/core';
 import type {
   AdapterFactory,
   HeadlessCoder,
@@ -20,19 +25,38 @@ import type {
   Provider,
 } from '@headless-coder-sdk/core';
 
-const moduleFilename = typeof __filename === 'string' ? __filename : fileURLToPath(import.meta.url);
-const WORKER_PATH = path.join(path.dirname(moduleFilename), 'worker.js');
+const moduleUrl =
+  typeof __filename === 'string' ? pathToFileURL(__filename).href : import.meta.url;
+const workerUrl = new URL('./worker.js', moduleUrl);
+const WORKER_PATH = fileURLToPath(workerUrl);
 const SOFT_KILL_DELAY_MS = 250;
 const HARD_KILL_DELAY_MS = 1500;
 const DONE = Symbol('stream-done');
 const STDERR_BUFFER_LIMIT = 64 * 1024;
+const isNodeRuntime = typeof process !== 'undefined' && !!process.versions?.node;
+
+function ensureNodeRuntime(action: string): void {
+  if (!isNodeRuntime) {
+    throw new Error(
+      `@headless-coder-sdk/codex-adapter can only ${action} inside a Node.js runtime.`,
+    );
+  }
+}
 
 export const CODER_NAME: Provider = 'codex';
 export function createAdapter(defaults?: StartOpts): HeadlessCoder {
   return new CodexAdapter(defaults);
 }
 (createAdapter as AdapterFactory).coderName = CODER_NAME;
 
+export function createHeadlessCodex(defaults?: StartOpts): HeadlessCoder {
+  if (!getAdapterFactory(CODER_NAME)) {
+    registerAdapter(createAdapter as AdapterFactory);
+  }
+  ensureNodeRuntime('create a Codex coder');
+  return createCoder(CODER_NAME, defaults);
+}
+
 interface CodexThreadOptions {
   model?: string;
   sandboxMode?: 'read-only' | 'workspace-write' | 'danger-full-access';
@@ -174,6 +198,7 @@ export class CodexAdapter implements HeadlessCoder {
   }
 
   private launchRunWorker(state: CodexThreadState, input: string, opts?: RunOpts) {
+    ensureNodeRuntime('spawn a Codex worker');
     const child = fork(WORKER_PATH, { stdio: ['inherit', 'inherit', 'pipe', 'ipc'] });
     const stderr = collectChildStderr(child);
     const abortController = new AbortController();
@@ -278,6 +303,7 @@ export class CodexAdapter implements HeadlessCoder {
     input: string,
     opts?: RunOpts,
   ): EventIterator {
+    ensureNodeRuntime('stream Codex events');
     const child = fork(WORKER_PATH, { stdio: ['inherit', 'inherit', 'pipe', 'ipc'] });
     const stderr = collectChildStderr(child);
     const abortController = new AbortController();

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headless-coder-sdk/core",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Unified SDK for headless AI coders (Codex, Claude, Gemini) with standardized threading, streaming, and sandboxing.",
   "type": "module",
   "main": "./dist/index.cjs",

packages/gemini-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headless-coder-sdk/gemini-adapter",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -18,7 +18,7 @@
     "build": "tsup --config tsup.config.ts"
   },
   "peerDependencies": {
-    "@headless-coder-sdk/core": "^0.13.0"
+    "@headless-coder-sdk/core": "^0.14.0"
   },
   "devDependencies": {
     "typescript": "^5.4.0",