codex

fix: ensure resume args precede image args (#10709 )

## Summary
Fixes argument ordering when `resumeThread()` is used with
`local_image`. The SDK previously emitted CLI args with `--image` before
`resume <threadId>`, which caused the Codex CLI to treat `resume`/UUID
as image paths and start a new session. This PR moves `resume
<threadId>` before any `--image` flags and adds a regression test.

## Bug Report / Links
- OpenAI issue: https://github.com/openai/codex/issues/10708
- Repro repo:
https://github.com/cryptonerdcn/codex-resume-local-image-repro
- Repro issue (repo):
https://github.com/cryptonerdcn/codex-resume-local-image-repro/issues/1

## Repro (pre-fix)
1. Build SDK from source
2. Run resume + local_image
3. Args order: `--image <path> resume <id>`
4. Result: new session created (thread id changes)

## Fix
Move `resume <threadId>` before `--image` in `CodexExec.run` and add a
regression test to assert ordering.

## Tests
- `cd sdk/typescript && npm test`
  - **Failed**: `codex-rs/target/debug/codex` missing (ENOENT)

## Notes
- I can rerun tests in an environment with `codex-rs` built and report
results.

cryptonerdcn · 2026-02-04 21:19:56 -08:00

1dc06b6ffc

feat: make it possible to specify --config flags in the SDK (#10003 )

Updates the `CodexOptions` passed to the `Codex()` constructor in the
SDK to support a `config` property that is a map of configuration data
that will be transformed into `--config` flags passed to the invocation
of `codex`.

Therefore, something like this:

```typescript
const codex = new Codex({
  config: {
    show_raw_agent_reasoning: true,
    sandbox_workspace_write: { network_access: true },
  },
});
```

would result in the following args being added to the invocation of
`codex`:

```shell
--config show_raw_agent_reasoning=true --config sandbox_workspace_write.network_access=true
```

Michael Bolin · 2026-01-27 10:47:07 -08:00

894923ed5d

add WebSearchMode enum (#9216 )

### What
Add `WebSearchMode` enum (disabled, cached live, defaults to cached) to
config + V2 protocol. This enum takes precedence over legacy flags:
`web_search_cached`, `web_search_request`, and `tools.web_search`.

Keep `--search` as live.

### Tests
Added tests

sayan-oai · 2026-01-14 12:51:42 -08:00

5e426ac270

fix: handle early codex exec exit (#8825 )

Fixes CodexExec to avoid missing early process exits by registering the
exit handler up front and deferring the error until after stdout is
drained, and adds a regression test that simulates a fast-exit child
while still producing output so hangs are caught.

Thibault Sottiaux · 2026-01-07 08:54:27 -08:00

0d788e6263

feat(ts-sdk): allow overriding CLI environment (#6648 )

## Summary
- add an `env` option for the TypeScript Codex client and plumb it into
`CodexExec` so the CLI can run without inheriting `process.env`
- extend the test spy to capture spawn environments, add coverage for
the new option, and document how to use it

## Testing
- `pnpm test` *(fails: corepack cannot download pnpm because outbound
network access is blocked in the sandbox)*

------
[Codex
Task](https://chatgpt.com/codex/tasks/task_i_6916b2d7c7548322a72d61d91a2dac85)

Ryan Lopopolo · 2025-11-14 19:44:19 +00:00

936650001f

feat: Add support for --add-dir to exec and TypeScript SDK (#6565 )

## Summary

Adds support for specifying additional directories in the TypeScript SDK
through a new `additionalDirectories` option in `ThreadOptions`.

## Changes

- Added `additionalDirectories` parameter to `ThreadOptions` interface
- Updated `CodexExec` to accept and pass through additional directories
via the `--config` flag for `sandbox_workspace_write.writable_roots`
- Added comprehensive test coverage for the new functionality

## Test plan

- Added test case that verifies `additionalDirectories` is correctly
passed as repeated flags
- Existing tests continue to pass

---------

Co-authored-by: Claude <noreply@anthropic.com>

Dan Hernandez · 2025-11-13 13:47:10 -08:00

b4a53aef47

Add AbortSignal support to TypeScript SDK (#6378 )

## Summary
Adds AbortSignal support to the TypeScript SDK for canceling thread
execution using AbortController.

## Changes
- Add `signal?: AbortSignal` property to `TurnOptions` type
- Pass signal through Thread class methods to exec layer  
- Add signal parameter to `CodexExecArgs`
- Leverage Node.js native `spawn()` signal support for automatic
cancellation
- Add comprehensive test coverage (6 tests covering all abort scenarios)

## Implementation
The implementation uses Node.js's built-in AbortSignal support in
`spawn()` (available since Node v15, SDK requires >=18), which
automatically handles:
- Checking if already aborted before starting
- Killing the child process when abort is triggered
- Emitting appropriate error events
- All cleanup operations

This is a one-line change to the core implementation (`signal:
args.signal` passed to spawn), making it simple, reliable, and
maintainable.

## Usage Example
```typescript
import { Codex } from '@openai/codex-sdk';

const codex = new Codex({ apiKey: 'your-api-key' });
const thread = codex.startThread();

// Create AbortController
const controller = new AbortController();

// Run with abort signal
const resultPromise = thread.run("Your prompt here", {
  signal: controller.signal
});

// Cancel anytime
controller.abort('User requested cancellation');
```

## Testing
All tests pass (23 total across SDK):
- ✅ Aborts when signal is already aborted (both run and runStreamed)
- ✅ Aborts during execution/iteration
- ✅ Completes normally when not aborted
- ✅ Backward compatible (signal is optional)

Tests verified to fail correctly when signal support is removed (no
false positives).

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: pakrym-oai <pakrym@openai.com>

Dan Hernandez · 2025-11-13 13:35:42 -08:00

439bc5dbbe

[SDK] Add network_access and web_search options to TypeScript SDK (#6367 )

## Summary

This PR adds two new optional boolean fields to `ThreadOptions` in the
TypeScript SDK:

- **`networkAccess`**: Enables network access in the sandbox by setting
`sandbox_workspace_write.network_access` config
- **`webSearch`**: Enables the web search tool by setting
`tools.web_search` config

These options map to existing Codex configuration options and are
properly threaded through the SDK layers:
1. `ThreadOptions` (threadOptions.ts) - User-facing API
2. `CodexExecArgs` (exec.ts) - Internal execution args  
3. CLI flags via `--config` in the `codex exec` command

## Changes

- `sdk/typescript/src/threadOptions.ts`: Added `networkAccess` and
`webSearch` fields to `ThreadOptions` type
- `sdk/typescript/src/exec.ts`: Added fields to `CodexExecArgs` and CLI
flag generation
- `sdk/typescript/src/thread.ts`: Pass options through to exec layer

## Test Plan

- [x] Build succeeds (`pnpm build`)
- [x] Linter passes (`pnpm lint`)
- [x] Type definitions are properly exported
- [ ] Manual testing with sample code (to be done by reviewer)

---------

Co-authored-by: Claude <noreply@anthropic.com>

Dan Hernandez · 2025-11-07 13:19:34 -08:00

c76528ca1f

Add modelReasoningEffort option to TypeScript SDK (#6237 )

## Summary
- Adds `ModelReasoningEffort` type to TypeScript SDK with values:
`minimal`, `low`, `medium`, `high`
- Adds `modelReasoningEffort` option to `ThreadOptions`
- Forwards the option to the codex CLI via `--config
model_reasoning_effort="<value>"`
- Includes test coverage for the new option

## Changes
- `sdk/typescript/src/threadOptions.ts`: Define `ModelReasoningEffort`
type and add to `ThreadOptions`
- `sdk/typescript/src/index.ts`: Export `ModelReasoningEffort` type
- `sdk/typescript/src/exec.ts`: Forward `modelReasoningEffort` to CLI as
config flag
- `sdk/typescript/src/thread.ts`: Pass option through to exec (+ debug
logging)
- `sdk/typescript/tests/run.test.ts`: Add test for
`modelReasoningEffort` flag forwarding

---------

Co-authored-by: Eric Traut <etraut@openai.com>

Dan Hernandez · 2025-11-05 08:51:03 -08:00

9a10e80ab7

Re-enable SDK image forwarding test (#5934 )

## Summary
- re-enable the TypeScript SDK test that verifies local images are
forwarded to `codex exec`

## Testing
- `pnpm test` *(fails: unable to download pnpm 10.8.1 because external
network access is blocked in the sandbox)*

------
https://chatgpt.com/codex/tasks/task_i_690289cb861083209fd006867e2adfb1

pakrym-oai · 2025-10-29 23:18:26 +00:00

bf35105af6

Skip flaky test (#5680 )

Did an investigation but couldn't find anything obvious. Let's skip for
now.

pakrym-oai · 2025-10-25 12:11:16 -07:00

c7e4e6d0ee

feat: add images support to the Codex Typescript SDK (#5281 )

Extend `run` and `runStreamed` input to be either a `string` or
structured input. A structured input is an array of text parts and/or
image paths, which will then be fed to the CLI through the `--image`
argument. Text parts are combined with double newlines. For instance:

```ts
const turn = await thread.run([
  { type: "text", text: "Describe these screenshots" },
  { type: "local_image", path: "./ui.png" },
  { type: "local_image", path: "./diagram.jpg" },
  { type: "text", text: "Thanks!" },
]);
```

Ends up launching the CLI with:

```
codex exec --image foo.png --image bar.png "Describe these screenshots\n\nThanks!" 
```

The complete `Input` type for both function now is:

```ts
export type UserInput =
  | {
      type: "text";
      text: string;
    }
  | {
      type: "local_image";
      path: string;
    };

export type Input = string | UserInput[];
```

This brings the Codex SDK closer to feature parity with the CLI.
Adresses #5280 .

needs · 2025-10-20 09:54:59 -07:00

3282e86a60

Set codex SDK TypeScript originator (#4894 )

## Summary
- ensure the TypeScript SDK sets CODEX_INTERNAL_ORIGINATOR_OVERRIDE to
codex_sdk_ts when spawning the Codex CLI
- extend the responses proxy test helper to capture request headers for
assertions
- add coverage that verifies Codex threads launched from the TypeScript
SDK send the codex_sdk_ts originator header

## Testing
- Not Run (not requested)


------
https://chatgpt.com/codex/tasks/task_i_68e561b125248320a487f129093d16e7

pakrym-oai · 2025-10-07 14:06:41 -07:00

60f9e85c16

Add structured-output support (#4793 )

Add samples and docs.

pakrym-oai · 2025-10-05 18:17:50 -07:00

90fe5e4a7e

Misc SDK fixes (#4752 )

Remove codex-level workingDirectory
Throw on turn.failed in `run()`
Cleanup readme

pakrym-oai · 2025-10-04 19:55:33 -07:00

356ea6ea34

Expose turn token usage in the SDK (#4700 )

It's present on the event, add it to the final result as well.

pakrym-oai · 2025-10-03 17:33:23 -07:00

848058f05b

Rename assistant message to agent message and fix item type field naming (#4610 )

Naming cleanup

pakrym-oai · 2025-10-02 15:07:14 -07:00

c405d8c06c

Store settings on the thread instead of turn (#4579 )

It's much more common to keep the same settings for the entire
conversation, we can add per-turn overrides later.

pakrym-oai · 2025-10-02 00:31:13 +00:00

c07fb71186

Add initial set of doc comments to the SDK (#4513 )

Also perform minor code cleanup.

pakrym-oai · 2025-10-01 13:12:59 -07:00

31102af54b

Explicit node imports (#4567 )

To help with compatibility

pakrym-oai · 2025-10-01 12:39:04 -07:00

170c685882

SDK: support working directory and skipGitRepoCheck options (#4563 )

Make options not required, add support for working directory and
skipGitRepoCheck options on the turn

pakrym-oai · 2025-10-01 11:26:49 -07:00

8a367ef6bf

Add executable detection and export Codex from the SDK (#4532 )

Executable detection uses the same rules as the codex wrapper.

pakrym-oai · 2025-09-30 18:06:16 -07:00

8dd771d217

[SDK] Test that a tread can be continued with extra params (#4508 )

pakrym-oai · 2025-09-30 17:22:14 +00:00

c89b0e1235

Support model and sandbox mode in the sdk (#4503 )

pakrym-oai · 2025-09-30 09:00:39 -07:00

516acc030b

Rename conversation to thread in codex exec (#4482 )

pakrym-oai · 2025-09-29 20:18:30 -07:00

ea82f86662

Add some types and a basic test to the SDK (#4472 )

pakrym-oai · 2025-09-29 19:40:08 -07:00

52e591ce60

TypeScript SDK scaffold (#4455 )

pakrym-oai · 2025-09-29 13:27:13 -07:00

adbc38a978

27 Commits