From d0e3aea191b3661cfedec467c5aa864d50815947 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Wed, 14 Oct 2026 18:28:52 -0700 Subject: [PATCH 1/6] docs(coding-agents): OpenAI Codex SDK tracing (TH-8262) New page integrations/coding-agents/codex-sdk for @traceai/codex-sdk: install, register, manuallyInstrument / wrapCodex, the span tree, what is and is not captured, the running-total token handling, privacy default and opt-in, and troubleshooting. One nav entry after the coding-agents:codex-sdk marker. Co-Authored-By: Claude Opus 5.5 --- src/lib/navigation.ts | 1 + .../integrations/coding-agents/codex-sdk.mdx | 158 ++++++++++++++++++ 2 files changed, 159 insertions(+) create mode 100644 src/pages/docs/integrations/coding-agents/codex-sdk.mdx diff --git a/src/lib/navigation.ts b/src/lib/navigation.ts index 9ebda640c..2c48363cb 100644 --- a/src/lib/navigation.ts +++ b/src/lib/navigation.ts @@ -962,6 +962,7 @@ export const tabNavigation: NavTab[] = [ // coding-agents:claude-cowork // coding-agents:codex // coding-agents:codex-sdk + { title: 'Codex SDK', href: '/docs/integrations/coding-agents/codex-sdk' }, // coding-agents:cursor { title: 'Cursor', href: '/docs/integrations/coding-agents/cursor' }, // coding-agents:cursor-sdk diff --git a/src/pages/docs/integrations/coding-agents/codex-sdk.mdx b/src/pages/docs/integrations/coding-agents/codex-sdk.mdx new file mode 100644 index 000000000..a6ca343a0 --- /dev/null +++ b/src/pages/docs/integrations/coding-agents/codex-sdk.mdx @@ -0,0 +1,158 @@ +--- +title: "OpenAI Codex SDK tracing with Future AGI" +description: "Trace @openai/codex-sdk threads in Future AGI with @traceai/codex-sdk: one trace per turn with shell commands, file changes, MCP tool calls, web searches, reasoning, agent messages, token usage, and errors. Prompt and tool content stay off by default." +--- + +## About + +The [OpenAI Codex SDK](https://developers.openai.com/codex/sdk) (`@openai/codex-sdk`) runs the Codex agent from your own TypeScript code: it starts the `codex` binary in a subprocess and streams the agent's events back to you. The `@traceai/codex-sdk` package turns that event stream into spans, so every `thread.run()` or `thread.runStreamed()` shows up in Future AGI as one trace: + +``` +codex.turn one run() / runStreamed(): session.id = thread id, model, tokens +├── codex.reasoning reasoning summary +├── codex.agent_message LLM: a message from the agent +├── codex.command_execution TOOL: shell command, exit code, status +├── codex.file_change TOOL: patch, number and kinds of changes +├── codex.mcp_tool_call TOOL: MCP server and tool, status +├── codex.web_search TOOL +├── codex.todo_list the agent's plan, items done +└── codex.error non-fatal error item, status ERROR +``` + +All turns of one Codex thread share a `session.id`, so Future AGI groups them into one session. + +This is not the same as: + +- **Codex application session tracing**: the `codex` CLI, TUI, and IDE extension exporting their own telemetry through the `[otel]` section of `~/.codex/config.toml`. That is a separate integration. +- **OpenAI API tracing** (`@traceai/openai`). The SDK makes its model requests inside the `codex` subprocess, so an OpenAI client instrumentor in your app does not see them. + +| | | +| --- | --- | +| Tested with | `@openai/codex-sdk` 0.162.1 and its bundled `codex` 0.162.1 (macOS, Node 22) | +| Supported SDK versions | 0.44.0 or later, below 1.0 | +| Codex docs used | [Codex SDK](https://developers.openai.com/codex/sdk), the SDK's published type definitions (`dist/index.d.ts`), read 2026-10-14 | +| Requires | Node 18 or later | +| Source | [typescript/packages/traceai_codex_sdk](https://github.com/future-agi/traceAI/tree/main/typescript/packages/traceai_codex_sdk) in traceAI | + +## 1. Install + +```bash +npm install @traceai/codex-sdk @traceai/fi-core @openai/codex-sdk +``` + +## 2. Set environment variables + +```bash +export FI_API_KEY="your-futureagi-api-key" +export FI_SECRET_KEY="your-futureagi-secret-key" +``` + +Codex itself authenticates as it normally does (`codex login`, or the `apiKey` option on `Codex`). For a self-hosted Future AGI, also set `FI_BASE_URL`; traces go to `$FI_BASE_URL/tracer/v1/traces`. + +## 3. Register a tracer provider and instrument the SDK + +```typescript +import * as CodexSDK from "@openai/codex-sdk"; +import { register, ProjectType } from "@traceai/fi-core"; +import { CodexSDKInstrumentation, shutdown } from "@traceai/codex-sdk"; + +const tracerProvider = register({ + projectType: ProjectType.OBSERVE, + projectName: "codex-sdk-app", +}); + +new CodexSDKInstrumentation({ tracerProvider }).manuallyInstrument(CodexSDK); +``` + +Pass the module namespace (`import * as CodexSDK`), not the `Codex` class. The SDK is ESM-only, so the package patches its `Thread` class once for the whole process. + +To trace only some clients, wrap instances instead of the class: + +```typescript +const instrumentation = new CodexSDKInstrumentation({ tracerProvider }); +const codex = instrumentation.wrapCodex(new CodexSDK.Codex()); // every thread it starts or resumes +``` + +## 4. Run the agent + +```typescript +const codex = new CodexSDK.Codex(); +const thread = codex.startThread({ workingDirectory: "/path/to/repo", model: "gpt-5.6-terra" }); + +const turn = await thread.run("List the files in this folder and read README.md"); +console.log(turn.finalResponse); + +// Streaming works the same way and is traced the same way. +const { events } = await thread.runStreamed("Now summarize app.py"); +for await (const event of events) { + // the SDK's own event objects, unchanged +} + +await shutdown(tracerProvider); // flush before a short script exits +``` + +Open **Observe** in Future AGI and select the project (`codex-sdk-app` above). Each turn is one trace named **codex.turn**; open it to see the commands and messages it ran. Both turns above share the thread's `session.id`, so the **Sessions** view shows them together. + +## What is captured + +| SDK event | Future AGI span | Fields | +| --- | --- | --- | +| `thread.started` | **codex.turn** (root, `AGENT`) | `session.id` and `gen_ai.conversation.id` = thread id, `codex.thread.resumed` | +| `turn.completed` | **codex.turn** end | token usage (see below), status `OK` | +| `turn.failed`, `error` | **codex.turn** end, status `ERROR` | error message in `codex.error.message` | +| `command_execution` item | **codex.command_execution** (`TOOL`) | exit code, output length, status; `failed` marks the span `ERROR` | +| `file_change` item | **codex.file_change** (`TOOL`) | number of changes, kinds (`add`, `delete`, `update`), status | +| `mcp_tool_call` item | **codex.mcp_tool_call** (`TOOL`) | `tool.name` = MCP tool, `codex.mcp.server`, status | +| `web_search` item | **codex.web_search** (`TOOL`) | | +| `agent_message` item | **codex.agent_message** (`LLM`) | model, text length | +| `reasoning` item | **codex.reasoning** | text length | +| `todo_list` item | **codex.todo_list** | item count, completed count (updated until the turn ends) | +| `error` item | **codex.error**, status `ERROR` | Codex's error message | + +The turn span also records the thread options you passed: `gen_ai.request.model`, `codex.sandbox_mode`, `codex.approval_policy`, `codex.model_reasoning_effort`, `codex.web_search_mode`. If your code stops reading `runStreamed()` events before `turn.completed`, or aborts with `TurnOptions.signal`, the turn and any open items end as `ERROR` with `codex.cancelled=true`. If the `codex` binary exits with an error, the SDK's error is recorded on the turn and then thrown to your code unchanged. + +### Token usage + +Tokens are recorded on the **codex.turn** span only: `gen_ai.usage.input_tokens`, `output_tokens`, `total_tokens`, `cache_read_tokens`, `cache_write_tokens`, and `output_tokens.reasoning`. + +The SDK's `turn.completed` usage is the thread's running total, not the turn's own spend: in our test a thread's second turn reported 39,318 input tokens after the first reported 19,378. So each turn span holds the difference from the last total seen in your process for that thread, and Future AGI's per-trace and per-session sums stay correct. The running totals are on `codex.cumulative.*`. + +When a thread is resumed with `resumeThread(id)` in a process that has not seen it before (after a restart, or on another worker), the first turn has no earlier total to subtract. It records no `gen_ai.usage.*` and sets `codex.usage.baseline_unknown=true`; its later turns record their difference. Keep a thread's turns in one process for exact per-turn tokens. + +## What is not available + +- **Per-request model spans.** The SDK reports agent messages, not individual model requests, so there is no span per Responses API call and no per-request token counts. +- **Model chosen in `config.toml`.** The model is recorded only when you pass `model` in `startThread()` or `resumeThread()`; the SDK does not report which model the binary used. +- **Cost.** Codex does not report cost, and the package does not compute one. +- **Exact durations.** Span times are when each event reached your process. `agent_message` and `reasoning` arrive only when complete, so their spans start at the previous event. The binary reports a command's start and end close together, so command spans are short. +- **Approval decisions and subagent internals.** The SDK event stream does not carry them. + +## Privacy + +By default only structure and metadata are exported: thread id, item ids and types, statuses, exit codes, counts, lengths, tool and MCP server names, model, and token counts. + +**Not exported by default:** the prompt, shell commands, command output, file paths in patches, MCP arguments and results, web search queries, reasoning text, agent messages, to-do text, and an MCP tool's error text. + +To include content, opt in when you create the instrumentation: + +```typescript +new CodexSDKInstrumentation({ + tracerProvider, + traceConfig: { hideInputs: false, hideOutputs: false }, +}).manuallyInstrument(CodexSDK); +``` + +or set `FI_HIDE_INPUTS=false` and `FI_HIDE_OUTPUTS=false`. With inputs visible, the turn's `input.value` is the prompt and tool spans carry the command, file changes, MCP arguments, or search query. With outputs visible, the turn's `output.value` is the final agent message and items carry their output. Only the exact value `false` turns capture on: `1`, `yes`, or `true` keep content hidden. + +## Troubleshooting + +**No trace appears.** +1. `register()` needs a `projectName` (or `FI_PROJECT_NAME`); the collector drops spans without one. +2. Pass the module namespace to `manuallyInstrument()`: `import * as CodexSDK from "@openai/codex-sdk"`. It returns `false` and logs a warning when it finds no `Thread` class. +3. Call `await shutdown(tracerProvider)` before a short script exits, so the last spans are sent. + +**A turn has no token counts.** Look for `codex.usage.baseline_unknown=true` on the turn: the thread was resumed in a process that had not seen it. `codex.cumulative.*` still has the thread's totals. + +**The turn is marked cancelled.** Your code stopped iterating `runStreamed()` events before `turn.completed`, or aborted the turn. Read the stream to the end (or let `run()` finish) to record the turn as completed. + +**No model on the turn.** Pass `model` in the thread options. From 54f030c960f0ee4879219d9835c74f4b48f6d81a Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Wed, 14 Oct 2026 19:28:17 -0700 Subject: [PATCH 2/6] docs(coding-agents): Codex SDK cost is Future AGI's estimate from model and tokens (TH-8262) Co-Authored-By: Claude Opus 5.5 --- src/pages/docs/integrations/coding-agents/codex-sdk.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/docs/integrations/coding-agents/codex-sdk.mdx b/src/pages/docs/integrations/coding-agents/codex-sdk.mdx index a6ca343a0..fc7d556e9 100644 --- a/src/pages/docs/integrations/coding-agents/codex-sdk.mdx +++ b/src/pages/docs/integrations/coding-agents/codex-sdk.mdx @@ -123,7 +123,7 @@ When a thread is resumed with `resumeThread(id)` in a process that has not seen - **Per-request model spans.** The SDK reports agent messages, not individual model requests, so there is no span per Responses API call and no per-request token counts. - **Model chosen in `config.toml`.** The model is recorded only when you pass `model` in `startThread()` or `resumeThread()`; the SDK does not report which model the binary used. -- **Cost.** Codex does not report cost, and the package does not compute one. +- **Reported cost.** Codex does not report cost and the package sends none. The cost Future AGI shows on a turn is its own estimate from the model and token counts, so it appears only when you pass `model` and Future AGI knows that model's price. - **Exact durations.** Span times are when each event reached your process. `agent_message` and `reasoning` arrive only when complete, so their spans start at the previous event. The binary reports a command's start and end close together, so command spans are short. - **Approval decisions and subagent internals.** The SDK event stream does not carry them. From 42dd35d472185a31e99b364979faa8ee703c440e Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Thu, 15 Oct 2026 05:39:56 -0700 Subject: [PATCH 3/6] docs(coding-agents): Codex SDK privacy covers error text; review fixes (TH-8262) Review fixes for #915, matching traceAI#251 at its new head: - Privacy: with outputs hidden, a thrown error exports only its class and a fixed summary (no stderr, no stack trace); turn.failed and fatal error events give a fixed label. Lists the error text that is content (binary stderr with paths and user name, provider error bodies, stack traces, error item text) and says opt-in exports it. - Install note: the package ships with traceAI PR #251; install from source until it is on npm (recipe verified: clone, build, pack, install). - What is captured: error events are retries unless the turn never completes (codex.stream_error.count); error items are warnings with status unset; the turn opens on the first read, thread.started sets session.id. - Cancelled only on break/return()/abort; a dropped iterator exports nothing. Failed or cancelled turns' tokens land on the next completed turn. Token handling verified on 0.162.1 only; Thread shape versions listed. - Troubleshooting: register() throws without a project name; the manuallyInstrument() warning needs a diag logger; stream_error count on OK turns; summary-only error messages. - FI_HIDE_* wording, Codex SDK doc link (now learn.chatgpt.com), subagent (collab_tool_call) and provider limitations. Co-Authored-By: Claude Opus 5.5 --- .../integrations/coding-agents/codex-sdk.mdx | 66 ++++++++++++++----- 1 file changed, 48 insertions(+), 18 deletions(-) diff --git a/src/pages/docs/integrations/coding-agents/codex-sdk.mdx b/src/pages/docs/integrations/coding-agents/codex-sdk.mdx index fc7d556e9..af7169931 100644 --- a/src/pages/docs/integrations/coding-agents/codex-sdk.mdx +++ b/src/pages/docs/integrations/coding-agents/codex-sdk.mdx @@ -5,7 +5,7 @@ description: "Trace @openai/codex-sdk threads in Future AGI with @traceai/codex- ## About -The [OpenAI Codex SDK](https://developers.openai.com/codex/sdk) (`@openai/codex-sdk`) runs the Codex agent from your own TypeScript code: it starts the `codex` binary in a subprocess and streams the agent's events back to you. The `@traceai/codex-sdk` package turns that event stream into spans, so every `thread.run()` or `thread.runStreamed()` shows up in Future AGI as one trace: +The [OpenAI Codex SDK](https://learn.chatgpt.com/docs/codex-sdk) (`@openai/codex-sdk`) runs the Codex agent from your own TypeScript code: it starts the `codex` binary in a subprocess and streams the agent's events back to you. The `@traceai/codex-sdk` package turns that event stream into spans, so every `thread.run()` or `thread.runStreamed()` shows up in Future AGI as one trace: ``` codex.turn one run() / runStreamed(): session.id = thread id, model, tokens @@ -16,7 +16,7 @@ codex.turn one run() / runStreamed(): session.id = thread id ├── codex.mcp_tool_call TOOL: MCP server and tool, status ├── codex.web_search TOOL ├── codex.todo_list the agent's plan, items done -└── codex.error non-fatal error item, status ERROR +└── codex.error non-fatal error item (warning, deprecation, model reroute) ``` All turns of one Codex thread share a `session.id`, so Future AGI groups them into one session. @@ -29,8 +29,8 @@ This is not the same as: | | | | --- | --- | | Tested with | `@openai/codex-sdk` 0.162.1 and its bundled `codex` 0.162.1 (macOS, Node 22) | -| Supported SDK versions | 0.44.0 or later, below 1.0 | -| Codex docs used | [Codex SDK](https://developers.openai.com/codex/sdk), the SDK's published type definitions (`dist/index.d.ts`), read 2026-10-14 | +| Supported SDK versions | 0.44.0 or later, below 1.0. The `Thread` shape the package patches was checked on 0.44.0, 0.80.0, 0.100.0, 0.140.0, and 0.162.1; per-turn token counts were verified on 0.162.1 only (see [Token usage](#token-usage)) | +| Codex docs used | [Codex SDK](https://learn.chatgpt.com/docs/codex-sdk), the SDK's published type definitions (`dist/index.d.ts`), read 2026-10-14 | | Requires | Node 18 or later | | Source | [typescript/packages/traceai_codex_sdk](https://github.com/future-agi/traceAI/tree/main/typescript/packages/traceai_codex_sdk) in traceAI | @@ -40,6 +40,19 @@ This is not the same as: npm install @traceai/codex-sdk @traceai/fi-core @openai/codex-sdk ``` + +`@traceai/codex-sdk` ships with [traceAI PR #251](https://github.com/future-agi/traceAI/pull/251). Until it is released to npm, install it from source: + +```bash +git clone --depth 1 --branch feat/th-8262-codex-sdk https://github.com/future-agi/traceAI.git +cd traceAI/typescript +pnpm install --filter "@traceai/codex-sdk..." +cd packages/traceai_codex_sdk && pnpm run build && pnpm pack --pack-destination /tmp +cd /path/to/your/app +npm install /tmp/traceai-codex-sdk-0.1.0.tgz @traceai/fi-core @openai/codex-sdk +``` + + ## 2. Set environment variables ```bash @@ -97,9 +110,11 @@ Open **Observe** in Future AGI and select the project (`codex-sdk-app` above). E | SDK event | Future AGI span | Fields | | --- | --- | --- | -| `thread.started` | **codex.turn** (root, `AGENT`) | `session.id` and `gen_ai.conversation.id` = thread id, `codex.thread.resumed` | +| your `run()` / `runStreamed()` call | **codex.turn** (root, `AGENT`), opened when the first event is read | prompt length, thread options, `codex.thread.resumed` | +| `thread.started` | sets `session.id` and `gen_ai.conversation.id` = thread id on **codex.turn** | | | `turn.completed` | **codex.turn** end | token usage (see below), status `OK` | -| `turn.failed`, `error` | **codex.turn** end, status `ERROR` | error message in `codex.error.message` | +| `turn.failed` | **codex.turn** end, status `ERROR` | `codex.error.message` (see [Privacy](#privacy)) | +| `error` | counted in `codex.stream_error.count`, one `codex.stream_error` span event each | Codex also sends `error` for errors it retries ("Reconnecting... 1/5"). A turn that still reaches `turn.completed` ends `OK`; one that does not ends `ERROR` | | `command_execution` item | **codex.command_execution** (`TOOL`) | exit code, output length, status; `failed` marks the span `ERROR` | | `file_change` item | **codex.file_change** (`TOOL`) | number of changes, kinds (`add`, `delete`, `update`), status | | `mcp_tool_call` item | **codex.mcp_tool_call** (`TOOL`) | `tool.name` = MCP tool, `codex.mcp.server`, status | @@ -107,31 +122,40 @@ Open **Observe** in Future AGI and select the project (`codex-sdk-app` above). E | `agent_message` item | **codex.agent_message** (`LLM`) | model, text length | | `reasoning` item | **codex.reasoning** | text length | | `todo_list` item | **codex.todo_list** | item count, completed count (updated until the turn ends) | -| `error` item | **codex.error**, status `ERROR` | Codex's error message | +| `error` item | **codex.error**, status unset, `codex.warning=true` | message length. Codex 0.162.1 sends config warnings, deprecation notices, and model reroutes this way, so they do not mark the turn `ERROR` | -The turn span also records the thread options you passed: `gen_ai.request.model`, `codex.sandbox_mode`, `codex.approval_policy`, `codex.model_reasoning_effort`, `codex.web_search_mode`. If your code stops reading `runStreamed()` events before `turn.completed`, or aborts with `TurnOptions.signal`, the turn and any open items end as `ERROR` with `codex.cancelled=true`. If the `codex` binary exits with an error, the SDK's error is recorded on the turn and then thrown to your code unchanged. +The turn span also records the thread options you passed: `gen_ai.request.model`, `codex.sandbox_mode`, `codex.approval_policy`, `codex.model_reasoning_effort`, `codex.web_search_mode`. If you `break` out of the `for await` loop (or call `events.return()`) before `turn.completed`, or abort with `TurnOptions.signal`, the turn and any open items end as `ERROR` with `codex.cancelled=true`. A `runStreamed()` iterator that is neither read to the end nor closed never ends its turn, so nothing is exported for it. If the `codex` binary exits with an error, the turn ends `ERROR` with `codex.error.type` and a summary in `codex.error.message` (see [Privacy](#privacy)), and the SDK's error is thrown to your code unchanged. ### Token usage Tokens are recorded on the **codex.turn** span only: `gen_ai.usage.input_tokens`, `output_tokens`, `total_tokens`, `cache_read_tokens`, `cache_write_tokens`, and `output_tokens.reasoning`. -The SDK's `turn.completed` usage is the thread's running total, not the turn's own spend: in our test a thread's second turn reported 39,318 input tokens after the first reported 19,378. So each turn span holds the difference from the last total seen in your process for that thread, and Future AGI's per-trace and per-session sums stay correct. The running totals are on `codex.cumulative.*`. +The SDK's `turn.completed` usage is the thread's running total, not the turn's own spend: on 0.162.1 a thread's second turn reported 39,318 input tokens after the first reported 19,378. So each turn span holds the difference from the last total seen in your process for that thread, and Future AGI's per-trace and per-session sums stay correct. The running totals are on `codex.cumulative.*`. When a thread is resumed with `resumeThread(id)` in a process that has not seen it before (after a restart, or on another worker), the first turn has no earlier total to subtract. It records no `gen_ai.usage.*` and sets `codex.usage.baseline_unknown=true`; its later turns record their difference. Keep a thread's turns in one process for exact per-turn tokens. +A turn that fails or is cancelled reports no usage, so its tokens are counted on the thread's next completed turn. A new thread starts at zero even when its first turn fails, so the next turn still records its difference. If the running total ever goes down, the reported value is recorded as is and `codex.usage.non_monotonic=true` is set. + +This running-total handling was measured on 0.162.1. Older SDK and `codex` versions were checked for the `Thread` shape only, not for how they report usage across turns. + ## What is not available - **Per-request model spans.** The SDK reports agent messages, not individual model requests, so there is no span per Responses API call and no per-request token counts. - **Model chosen in `config.toml`.** The model is recorded only when you pass `model` in `startThread()` or `resumeThread()`; the SDK does not report which model the binary used. - **Reported cost.** Codex does not report cost and the package sends none. The cost Future AGI shows on a turn is its own estimate from the model and token counts, so it appears only when you pass `model` and Future AGI knows that model's price. - **Exact durations.** Span times are when each event reached your process. `agent_message` and `reasoning` arrive only when complete, so their spans start at the previous event. The binary reports a command's start and end close together, so command spans are short. -- **Approval decisions and subagent internals.** The SDK event stream does not carry them. +- **Approval decisions.** The SDK event stream does not carry them. +- **Subagents.** Codex 0.162.1 also emits `collab_tool_call` items (a subagent spawn) that are not in the SDK's types. They appear as a generic `codex.collab_tool_call` span, with no link to the subagent's own work. +- **The actual provider.** `gen_ai.provider.name` is always `openai`. The SDK does not report which `model_provider` the binary used, so an Azure, `--oss`, or other custom provider setup is still labelled `openai`. ## Privacy -By default only structure and metadata are exported: thread id, item ids and types, statuses, exit codes, counts, lengths, tool and MCP server names, model, and token counts. +By default only structure and metadata are exported: thread id, item ids and types, statuses, exit codes, counts, lengths, tool and MCP server names, model, token counts, and fixed error summaries: + +- A thrown error (for example the `codex` binary exiting non-zero) exports its class name in `codex.error.type` and only a fixed summary in `codex.error.message`, the span status, and the exception event: `Codex Exec exited with code N` (or `signal S`), `Failed to parse item`, or the class name. The exception event has no stack trace. +- `turn.failed` exports the label `turn failed`, and a turn that had an `error` event and never reached `turn.completed` exports `stream error`. -**Not exported by default:** the prompt, shell commands, command output, file paths in patches, MCP arguments and results, web search queries, reasoning text, agent messages, to-do text, and an MCP tool's error text. +**Not exported by default:** the prompt, shell commands, command output, file paths in patches, MCP arguments and results, web search queries, reasoning text, agent messages, to-do text, and all error text: the SDK's full error message (on a non-zero exit it includes the `codex` binary's stderr, which can quote config lines, absolute paths, and your user name), the provider's error body from `turn.failed` and `error` events, the exception stack trace (local file paths), the text of `codex.error` items, and an MCP tool's error text. To include content, opt in when you create the instrumentation: @@ -142,17 +166,23 @@ new CodexSDKInstrumentation({ }).manuallyInstrument(CodexSDK); ``` -or set `FI_HIDE_INPUTS=false` and `FI_HIDE_OUTPUTS=false`. With inputs visible, the turn's `input.value` is the prompt and tool spans carry the command, file changes, MCP arguments, or search query. With outputs visible, the turn's `output.value` is the final agent message and items carry their output. Only the exact value `false` turns capture on: `1`, `yes`, or `true` keep content hidden. +or set `FI_HIDE_INPUTS=false` and `FI_HIDE_OUTPUTS=false`. With inputs visible, the turn's `input.value` is the prompt and tool spans carry the command, the file changes including their paths, MCP arguments, or search query; any path in those is exported too. With outputs visible, the turn's `output.value` is the final agent message, items carry their output, and every error text listed above is exported, including the SDK's full error message with the binary's stderr and the exception stack trace. Only `false` (any case) turns capture on; `0`, `no`, or `off` keep content hidden. ## Troubleshooting +**`register()` throws `FI_PROJECT_NAME is not set`.** Pass `projectName` to `register()` or set `FI_PROJECT_NAME`. + **No trace appears.** -1. `register()` needs a `projectName` (or `FI_PROJECT_NAME`); the collector drops spans without one. -2. Pass the module namespace to `manuallyInstrument()`: `import * as CodexSDK from "@openai/codex-sdk"`. It returns `false` and logs a warning when it finds no `Thread` class. -3. Call `await shutdown(tracerProvider)` before a short script exits, so the last spans are sent. +1. Pass the module namespace to `manuallyInstrument()`: `import * as CodexSDK from "@openai/codex-sdk"`. It returns `false` when it finds no `Thread` class. Its warning is logged only when an OpenTelemetry diag logger is set, for example `diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.WARN)` from `@opentelemetry/api`. +2. Call `await shutdown(tracerProvider)` before a short script exits, so the last spans are sent. +3. Read every `runStreamed()` iterator to the end, or close it with `break` or `events.return()`. An iterator that is dropped part way never ends its turn, so that turn is never exported. + +**A turn has no token counts.** Look for `codex.usage.baseline_unknown=true` on the turn: the thread was resumed in a process that had not seen it. `codex.cumulative.*` still has the thread's totals. A failed or cancelled turn has no token counts either; its tokens are counted on the thread's next completed turn. + +**The turn is marked cancelled.** Your code left the `for await` loop with `break` (or called `events.return()`) before `turn.completed`, or aborted the turn. Read the stream to the end (or let `run()` finish) to record the turn as completed. -**A turn has no token counts.** Look for `codex.usage.baseline_unknown=true` on the turn: the thread was resumed in a process that had not seen it. `codex.cumulative.*` still has the thread's totals. +**An OK turn has `codex.stream_error.count`.** Codex hit a stream error, retried, and the turn completed. Nothing failed. -**The turn is marked cancelled.** Your code stopped iterating `runStreamed()` events before `turn.completed`, or aborted the turn. Read the stream to the end (or let `run()` finish) to record the turn as completed. +**The error message only says `Codex Exec exited with code 1`.** The full message, with the binary's stderr, is content. Set `hideOutputs: false` (or `FI_HIDE_OUTPUTS=false`) while you debug, or read the error your code receives. **No model on the turn.** Pass `model` in the thread options. From f4dac09931c8b5f5dfa45a5d85501d905fcb9cc9 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Sun, 18 Oct 2026 18:44:56 -0700 Subject: [PATCH 4/6] docs(coding-agents): Codex SDK item spans before their turn; failed MCP calls are ERROR (TH-8262) - A dropped runStreamed() iterator exports the items that already finished, without their codex.turn parent (the page said nothing was exported). - Troubleshooting: the turn span ends after its items and is sent last; Future AGI writes spans in batches, so items can show a few seconds before their turn. - A failed mcp_tool_call marks its span ERROR (traceAI#251 acd367e fixed real failed MCP calls being dropped). Co-Authored-By: Claude Opus 5.5 --- src/pages/docs/integrations/coding-agents/codex-sdk.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/pages/docs/integrations/coding-agents/codex-sdk.mdx b/src/pages/docs/integrations/coding-agents/codex-sdk.mdx index af7169931..3b9786e66 100644 --- a/src/pages/docs/integrations/coding-agents/codex-sdk.mdx +++ b/src/pages/docs/integrations/coding-agents/codex-sdk.mdx @@ -117,14 +117,14 @@ Open **Observe** in Future AGI and select the project (`codex-sdk-app` above). E | `error` | counted in `codex.stream_error.count`, one `codex.stream_error` span event each | Codex also sends `error` for errors it retries ("Reconnecting... 1/5"). A turn that still reaches `turn.completed` ends `OK`; one that does not ends `ERROR` | | `command_execution` item | **codex.command_execution** (`TOOL`) | exit code, output length, status; `failed` marks the span `ERROR` | | `file_change` item | **codex.file_change** (`TOOL`) | number of changes, kinds (`add`, `delete`, `update`), status | -| `mcp_tool_call` item | **codex.mcp_tool_call** (`TOOL`) | `tool.name` = MCP tool, `codex.mcp.server`, status | +| `mcp_tool_call` item | **codex.mcp_tool_call** (`TOOL`) | `tool.name` = MCP tool, `codex.mcp.server`, status; `failed` marks the span `ERROR` | | `web_search` item | **codex.web_search** (`TOOL`) | | | `agent_message` item | **codex.agent_message** (`LLM`) | model, text length | | `reasoning` item | **codex.reasoning** | text length | | `todo_list` item | **codex.todo_list** | item count, completed count (updated until the turn ends) | | `error` item | **codex.error**, status unset, `codex.warning=true` | message length. Codex 0.162.1 sends config warnings, deprecation notices, and model reroutes this way, so they do not mark the turn `ERROR` | -The turn span also records the thread options you passed: `gen_ai.request.model`, `codex.sandbox_mode`, `codex.approval_policy`, `codex.model_reasoning_effort`, `codex.web_search_mode`. If you `break` out of the `for await` loop (or call `events.return()`) before `turn.completed`, or abort with `TurnOptions.signal`, the turn and any open items end as `ERROR` with `codex.cancelled=true`. A `runStreamed()` iterator that is neither read to the end nor closed never ends its turn, so nothing is exported for it. If the `codex` binary exits with an error, the turn ends `ERROR` with `codex.error.type` and a summary in `codex.error.message` (see [Privacy](#privacy)), and the SDK's error is thrown to your code unchanged. +The turn span also records the thread options you passed: `gen_ai.request.model`, `codex.sandbox_mode`, `codex.approval_policy`, `codex.model_reasoning_effort`, `codex.web_search_mode`. If you `break` out of the `for await` loop (or call `events.return()`) before `turn.completed`, or abort with `TurnOptions.signal`, the turn and any open items end as `ERROR` with `codex.cancelled=true`. A `runStreamed()` iterator that is neither read to the end nor closed never ends its turn: items that already finished are exported, but without their **codex.turn** parent. If the `codex` binary exits with an error, the turn ends `ERROR` with `codex.error.type` and a summary in `codex.error.message` (see [Privacy](#privacy)), and the SDK's error is thrown to your code unchanged. ### Token usage @@ -177,6 +177,8 @@ or set `FI_HIDE_INPUTS=false` and `FI_HIDE_OUTPUTS=false`. With inputs visible, 2. Call `await shutdown(tracerProvider)` before a short script exits, so the last spans are sent. 3. Read every `runStreamed()` iterator to the end, or close it with `break` or `events.return()`. An iterator that is dropped part way never ends its turn, so that turn is never exported. +**Item spans show without their codex.turn parent.** The turn span ends after its items, so it is sent last, and Future AGI writes incoming spans in batches: for a few seconds after a turn ends, its items can be visible before the turn. Refresh the trace. If the turn never appears, a `runStreamed()` iterator was dropped part way (see above): the items that finished are exported, the turn is not. + **A turn has no token counts.** Look for `codex.usage.baseline_unknown=true` on the turn: the thread was resumed in a process that had not seen it. `codex.cumulative.*` still has the thread's totals. A failed or cancelled turn has no token counts either; its tokens are counted on the thread's next completed turn. **The turn is marked cancelled.** Your code left the `for await` loop with `break` (or called `events.return()`) before `turn.completed`, or aborted the turn. Read the stream to the end (or let `run()` finish) to record the turn as completed. From 921dfb1f95f4f4c4bc9ec5f3060349e96a76eab2 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Wed, 21 Oct 2026 15:14:24 -0700 Subject: [PATCH 5/6] docs(codex-sdk): drop the install-from-source note; the page goes live after @traceai/codex-sdk is on npm (TH-8262) Co-Authored-By: Claude Opus 5.5 --- .../docs/integrations/coding-agents/codex-sdk.mdx | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/src/pages/docs/integrations/coding-agents/codex-sdk.mdx b/src/pages/docs/integrations/coding-agents/codex-sdk.mdx index 3b9786e66..1e06293b9 100644 --- a/src/pages/docs/integrations/coding-agents/codex-sdk.mdx +++ b/src/pages/docs/integrations/coding-agents/codex-sdk.mdx @@ -40,19 +40,6 @@ This is not the same as: npm install @traceai/codex-sdk @traceai/fi-core @openai/codex-sdk ``` - -`@traceai/codex-sdk` ships with [traceAI PR #251](https://github.com/future-agi/traceAI/pull/251). Until it is released to npm, install it from source: - -```bash -git clone --depth 1 --branch feat/th-8262-codex-sdk https://github.com/future-agi/traceAI.git -cd traceAI/typescript -pnpm install --filter "@traceai/codex-sdk..." -cd packages/traceai_codex_sdk && pnpm run build && pnpm pack --pack-destination /tmp -cd /path/to/your/app -npm install /tmp/traceai-codex-sdk-0.1.0.tgz @traceai/fi-core @openai/codex-sdk -``` - - ## 2. Set environment variables ```bash From 0e18e1cb4e4e27ba77cc37796a5e8adb99e5bd02 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Thu, 5 Nov 2026 16:34:10 -0800 Subject: [PATCH 6/6] docs(ci): pin browser checks to a supported Ubuntu runner The Codex SDK PR build succeeds, but Playwright 1.56.1 cannot install Chromium dependencies on the Ubuntu 26.04 image now selected by ubuntu-latest. Use Ubuntu 24.04 for the browser job without changing or skipping its checks. Co-Authored-By: Claude Code --- .github/workflows/pr-checks.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/pr-checks.yml b/.github/workflows/pr-checks.yml index 2bb5470c3..1910ffbec 100644 --- a/.github/workflows/pr-checks.yml +++ b/.github/workflows/pr-checks.yml @@ -76,7 +76,8 @@ jobs: docs-build: name: Docs build & Pagefind - runs-on: ubuntu-latest + # Playwright 1.56.1 supports Ubuntu 24.04, not the newer ubuntu-latest image. + runs-on: ubuntu-24.04 steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4