31 Commits

• ci: run SDK tests with a Bazel-built codex (#16046)

  ## Why
  
  Before this change, the SDK CI job built `codex` with Cargo before
  running the TypeScript package tests. That step has been getting more
  expensive as the Rust workspace grows, while the repo already has a
  Bazel-backed build path for the CLI.
  
  The SDK tests also need a normal executable path they can spawn
  repeatedly. Moving the job to Bazel exposed an extra CI detail: a plain
  `bazel-bin/...` lookup is not reliable under the Linux config because
  top-level outputs may stay remote and the wrapper emits status lines
  around `cquery` output.
  
  ## What Changed
  
  - taught `sdk/typescript/tests/testCodex.ts` to honor `CODEX_EXEC_PATH`
  before falling back to the local Cargo-style `target/debug/codex` path
  - added `--remote-download-toplevel` to
  `.github/scripts/run-bazel-ci.sh` so workflows can force Bazel to
  materialize top-level outputs on disk after a build
  - switched `.github/workflows/sdk.yml` from `cargo build --bin codex` to
  the shared Bazel CI setup and `//codex-rs/cli:codex` build target
  - changed the SDK workflow to resolve the built CLI with wrapper-backed
  `cquery --output=files`, stage the binary into
  `${GITHUB_WORKSPACE}/.tmp/sdk-ci/codex`, and point the SDK tests at that
  path via `CODEX_EXEC_PATH`
  - kept the warm-up step before Jest and the Bazel repository-cache save
  step
  
  ## Verification
  
  - `bash -n .github/scripts/run-bazel-ci.sh`
  - `./.github/scripts/run-bazel-ci.sh -- cquery --output=files --
  //codex-rs/cli:codex | grep -E '^(/|bazel-out/)' | tail -n 1`
  - `./.github/scripts/run-bazel-ci.sh --remote-download-toplevel -- build
  --build_metadata=TAG_job=sdk -- //codex-rs/cli:codex`
  - `CODEX_EXEC_PATH="$PWD/.tmp/sdk-ci/codex" pnpm --dir sdk/typescript
  test --runInBand`
  - `pnpm --dir sdk/typescript lint`

  Michael Bolin · 2026-03-27 17:17:22 -07:00
  2ffb32db98
• fix: disable plugins in SDK integration tests (#16036)

  ## Why
  
  The TypeScript SDK tests create a fresh `CODEX_HOME` for each Jest case
  and delete it during teardown. That cleanup has been flaking because the
  real `codex` binary can still be doing background curated-plugin startup
  sync under `.tmp/plugins-clone-*`, which races the test harness's
  recursive delete and leaves `ENOTEMPTY` failures behind.
  
  This path is unrelated to what the SDK tests are exercising, so letting
  plugin startup run during these tests only adds nondeterministic
  filesystem activity. This showed up recently in the `sdk` CI lane for
  [#16031](https://github.com/openai/codex/pull/16031).
  
  ## What Changed
  
  - updated `sdk/typescript/tests/testCodex.ts` to merge test config
  through a single helper
  - disabled `features.plugins` unconditionally for SDK integration tests
  so the CLI does not start curated-plugin sync in the temporary
  `CODEX_HOME`
  - preserved other explicit feature overrides from individual tests while
  forcing `plugins` back to `false`
  - kept the existing mock-provider override behavior intact for
  SSE-backed tests
  
  ## Verification
  
  - `pnpm test --runInBand`
  - `pnpm lint`

  Michael Bolin · 2026-03-27 13:04:34 -07:00
  95845cf6ce
• Prefer websockets when providers support them (#13592)

  Remove all flags and model settings.
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  pakrym-oai · 2026-03-17 19:46:44 -07:00
  770616414a
• Add openai_base_url config override for built-in provider (#12031)

  We regularly get bug reports from users who mistakenly have the
  `OPENAI_BASE_URL` environment variable set. This PR deprecates this
  environment variable in favor of a top-level config key
  `openai_base_url` that is used for the same purpose. By making it a
  config key, it will be more visible to users. It will also participate
  in all of the infrastructure we've added for layered and managed
  configs.
  
  Summary
  - introduce the `openai_base_url` top-level config key, update
  schema/tests, and route the built-in openai provider through it while
  - fall back to deprecated `OPENAI_BASE_URL` env var but warn user of
  deprecation when no `openai_base_url` config key is present
  - update CLI, SDK, and TUI code to prefer the new config path (with a
  deprecated env-var fallback) and document the SDK behavior change

  Eric Traut · 2026-03-13 20:12:25 -06:00
  4b9d5c8c1b
• 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