@traceai/codex-sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,165 @@
-# Temporary Holding Version
+# @traceai/codex-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+OpenTelemetry tracing for the [OpenAI Codex SDK](https://www.npmjs.com/package/@openai/codex-sdk) (`@openai/codex-sdk`), exported to Future AGI through `@traceai/fi-core`. Every `Thread.run()` and `Thread.runStreamed()` becomes one trace: a `codex.turn` span with one child span per thread item (shell commands, file changes, MCP tool calls, web searches, reasoning, agent messages, to-do lists, errors).
+
+Alpha. Tested against `@openai/codex-sdk` 0.162.1 driving the real `codex` 0.162.1 binary, and against the real SDK driving a stand-in binary (`contract/`).
+
+This is not Codex application session tracing (the `codex` TUI or IDE extension exporting through `[otel]` in `config.toml`), and not the OpenAI API instrumentation (`@traceai/openai`). The SDK runs the `codex` binary in a subprocess, so model requests made inside it are not visible to `@traceai/openai`.
+
+| Item | Value |
+|---|---|
+| Tested pin | `@openai/codex-sdk` 0.162.1 (Apache-2.0) with its bundled `@openai/codex` 0.162.1 |
+| Peer range | `>=0.44.0 <1`. The `Thread` shape this package patches was checked on 0.44.0, 0.80.0, 0.100.0, 0.140.0 and 0.162.1 (`src/__tests__/sdkShape.test.ts` checks the installed one). The token handling below was verified on 0.162.1 only |
+| Node | `>=18`, same as the SDK |
+
+## Install
+
+```bash
+npm install @traceai/codex-sdk @traceai/fi-core @openai/codex-sdk
+```
+
+## Use
+
+```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: "my-codex-app", // or FI_PROJECT_NAME; the collector drops a batch with no project_name
+});
+
+new CodexSDKInstrumentation({ tracerProvider }).manuallyInstrument(CodexSDK);
+
+const thread = new CodexSDK.Codex().startThread({ workingDirectory: "/path/to/repo" });
+const turn = await thread.run("List the files in this folder and read README.md");
+
+await shutdown(tracerProvider); // flush before a short script exits
+```
+
+`FI_API_KEY` and `FI_SECRET_KEY` are read by fi-core and sent as the `X-Api-Key` / `X-Secret-Key` headers. They are never copied onto spans.
+
+The SDK is ESM-only, so its module namespace cannot be patched; its `Thread` class can. `manuallyInstrument(CodexSDK)` patches `Thread.prototype` once for the whole process. To trace only some clients instead, wrap instances:
+
+```typescript
+const instrumentation = new CodexSDKInstrumentation({ tracerProvider });
+const codex = instrumentation.wrapCodex(new CodexSDK.Codex()); // every thread it starts or resumes
+const thread = instrumentation.wrapThread(existingThread);      // one thread
+instrumentation.unpatch();                                      // undo everything this object patched
+```
+
+`instrumentCodexSDK(CodexSDK, { tracerProvider })` is the one-call form.
+
+`CodexSDKInstrumentation` is not an OpenTelemetry `InstrumentationBase`: there is no module to hook on `require` or `import`, so passing it to `registerInstrumentations()` is not supported. Call `manuallyInstrument()` or the wrap methods.
+
+`wrapThread()` and threads from `wrapCodex()` keep no reference to the thread: after `unpatch()` their patched method stays in place and passes events through untraced.
+
+### What the wrapper does and does not do
+
+- `run()` and `runStreamed()` both drive the SDK's private `Thread.runStreamedInternal()` generator. The wrapper wraps that one method, so both entry points are traced with real per-event timing. It yields the SDK's own event objects, unchanged and in order, and forwards `return()` / `throw()`: `run()` returns exactly what it returned before, and throws the same errors. If a future SDK drops that method, the wrapper falls back to `runStreamed()` and logs a warning that `run()` may be untraced.
+- `Codex` options (`codexPathOverride`, `baseUrl`, `apiKey`, `config`, `env`) and thread options pass through untouched.
+- A tracing error never fails the agent. An exporter or collector failure is logged and does not reject the stream.
+- A turn ends when its event stream ends: read to the end, `break` out of `for await`, `events.return()`, a thrown error or an abort. A `runStreamed()` iterator that is dropped without any of these never ends its turn span: items that already finished are exported, but without their `codex.turn` parent. The turn span always ends last, after its open items, even if recording an attribute fails.
+
+## Spans
+
+```
+codex.turn                     AGENT   one per run() / runStreamed()
+├─ codex.reasoning             CHAIN
+├─ codex.agent_message         LLM
+├─ codex.command_execution     TOOL
+├─ codex.file_change           TOOL
+├─ codex.mcp_tool_call         TOOL
+├─ codex.web_search            TOOL
+├─ codex.todo_list             CHAIN
+└─ codex.error                 CHAIN   non-fatal error item: status UNSET, codex.warning=true
+```
+
+`fi.span.kind` and `gen_ai.span.kind` carry the kind. An item type a newer SDK adds becomes `codex.<type>` (CHAIN). `codex.error` items are non-fatal: codex 0.162.1 sends config warnings, deprecation notices and model reroutes this way, so they do not mark the span or the turn ERROR.
+
+| Field | Attributes | Source |
+|---|---|---|
+| Session | `session.id`, `gen_ai.conversation.id`, `codex.thread.id`; `codex.thread.resumed` | `thread.started.thread_id`, or the id of a resumed thread. Every child span carries `session.id` too |
+| Model | `gen_ai.request.model` on the turn and on agent messages | `ThreadOptions.model`, when set. The SDK does not report which model the binary used, so a model chosen in `config.toml` is not recorded |
+| Provider | `gen_ai.provider.name` = `openai`, always | Codex speaks the OpenAI Responses API. The SDK does not expose which `model_provider` the binary used, so a custom provider, Azure or `--oss` setup is still labelled `openai` |
+| Tokens | `gen_ai.usage.input_tokens`, `output_tokens`, `total_tokens`, `cache_read_tokens`, `cache_write_tokens`, `output_tokens.reasoning` | `turn.completed.usage`, on the turn span only. See "Token usage" |
+| Thread options | `codex.sandbox_mode`, `codex.approval_policy`, `codex.model_reasoning_effort`, `codex.web_search_mode` | `ThreadOptions` |
+| Items | `codex.item.id`, `codex.item.type`, `codex.item.status`, `tool.name`, `gen_ai.tool.call.id` | `item.*` events |
+| Commands | `codex.command.exit_code`, `codex.command.output_length` | `command_execution` |
+| File changes | `codex.file_change.count`, `codex.file_change.kinds` (`add`, `delete`, `update`) | `file_change` |
+| MCP | `tool.name` = the MCP tool, `codex.mcp.server`, `codex.mcp.tool` | `mcp_tool_call` |
+| To-dos | `codex.todo.count`, `codex.todo.completed` | `todo_list` (started, updated, completed with the turn) |
+| Errors | turn status ERROR; `codex.error.message`, `codex.error.type`; `codex.cancelled=true` | `turn.failed`; an `error` event with no `turn.completed` after it; a thrown error (for example `Codex Exec exited with code 1`); abort. `failed` items mark their own span ERROR. Error details are hidden independently of outputs (see "Privacy") |
+| Retries | `codex.stream_error.count`, one `codex.stream_error` span event each | `error` events. Codex sends them for errors it retries ("Reconnecting... 1/5"); a turn that still reaches `turn.completed` ends OK |
+
+Timing comes from when each event reaches your process. `agent_message` and `reasoning` items arrive only as `item.completed`; their spans start at the previous event (`codex.item.started_event=false`). The binary reports a command's `item.started` and `item.completed` close together, so command spans are short.
+
+A fi-core `session.id` the app set (fi-core context helpers) is kept; the thread id still goes to `codex.thread.id`.
+
+## Token usage
+
+`turn.completed.usage` is the thread's running total, not the turn's own spend. Verified on 0.162.1 only: a second turn on a thread reported 39,318 input tokens after the first reported 19,378, and a third turn resumed from a new process reported 49,397. The Future AGI collector sums `gen_ai.usage.*` over a trace and over a `session.id`, so the turn span holds only the new spend:
+
+- A new thread's first turn promotes the full value.
+- Later turns promote the total minus the last total this process saw for that thread id (an in-process map, at most 1000 threads). `resumeThread(id)` in the same process uses it too.
+- A resumed thread with no total seen in this process (a resume after a restart, or on another worker) promotes nothing on its first turn and sets `codex.usage.baseline_unknown=true`. Its later turns promote their difference.
+- A turn that fails or is cancelled reports no usage, so its spend is counted on the thread's next completed turn. A new thread's first turn starts the thread at zero even when it fails, so the next turn still promotes its difference.
+- If the total goes down, the reported value is promoted as is, `codex.usage.non_monotonic=true` is set, and the larger of the old and new totals is kept as the baseline.
+- The running totals are always on `codex.cumulative.input_tokens`, `cached_input_tokens`, `cache_write_input_tokens`, `output_tokens`, `reasoning_output_tokens`.
+
+`input_tokens` includes cached tokens and `output_tokens` includes reasoning tokens (OpenAI accounting); `total_tokens` is their sum. No cost is computed here; Future AGI estimates one from the model and tokens when `model` is set and it knows the model's price.
+
+## Privacy: content is off by default
+
+Prompts, shell commands, command output, file paths, MCP arguments and results, web search queries, reasoning, agent messages and to-do text can contain source code or secrets. They are **not** recorded unless you opt in:
+
+```typescript
+new CodexSDKInstrumentation({ tracerProvider, traceConfig: { hideInputs: false, hideOutputs: false } });
+// or: FI_HIDE_INPUTS=false FI_HIDE_OUTPUTS=false
+```
+
+With inputs visible, the turn's `input.value` is the prompt and tool spans carry the command, file changes (including their paths), MCP arguments or search query. With outputs visible, the turn's `output.value` is the final agent message and items carry their output. Precedence: `traceConfig`, then the env var, then hidden. The env vars fail closed: only `false` (trimmed, any case) turns capture on; `0`, `no`, `off` or an empty value keep content hidden. Structural fields (lengths, counts, exit codes, statuses, tool and MCP server names) are always recorded.
+
+Error details have a separate, default-on privacy gate: `hideErrorDetails: true`
+(or `FI_HIDE_ERROR_DETAILS=true`). Status codes, error types, cancellation flags
+and retry counts remain, but status descriptions, exception messages/stacks,
+`codex.error.message`, retry-event text and failed-command output are omitted.
+Turning ordinary outputs on does **not** turn error details on.
+
+To include raw error details, explicitly set both `hideOutputs: false` and
+`hideErrorDetails: false` (or both `FI_HIDE_OUTPUTS=false` and
+`FI_HIDE_ERROR_DETAILS=false`). This can export stderr, provider bodies, local
+paths, usernames and stack traces. If only error details are enabled while
+outputs stay hidden, thrown errors use a fixed summary (`Codex Exec exited with
+code N`, `Failed to parse item`, or the error class) rather than the raw message.
+
+## Not captured
+
+- **Per-request model spans and tokens.** The SDK reports agent messages, not individual Responses API calls.
+- **The model the binary picked.** Only `ThreadOptions.model` is recorded.
+- **Cost.** No cost is computed here; Future AGI estimates one from the model and tokens when `model` is set and it knows the model's price.
+- **Exact durations.** Times are when events reach your process (see "Spans").
+- **Approval decisions.** The event stream does not carry them.
+- **Sub-agents.** codex 0.162.1 also emits `collab_tool_call` items (a sub-agent spawn) that are not in the SDK's types. They appear as a generic `codex.collab_tool_call` CHAIN span, with no link to the sub-agent's own work.
+
+## Flushing
+
+`shutdown(provider)` calls `forceFlush()` on the provider. It does not shut the provider down.
+
+## Troubleshooting
+
+- **`FI_PROJECT_NAME is not set`.** `register()` throws this without `projectName` or `FI_PROJECT_NAME`.
+- **No traces.** `manuallyInstrument()` must get the module namespace (`import * as CodexSDK`), not the `Codex` class; it returns `false` otherwise. Its warning is logged only when an OpenTelemetry diag logger is set (`diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.WARN)`). A `runStreamed()` iterator that is neither read to the end nor closed (`break`, `return()`) exports nothing.
+- **Zero spans from a short script.** `await shutdown(provider)` before exit.
+- **No tokens on a turn.** Look for `codex.usage.baseline_unknown=true`: the thread was resumed with no earlier total in this process. `codex.cumulative.*` still has the totals.
+- **No model.** Pass `model` in `startThread()` / `resumeThread()` options.
+- **Spans marked cancelled.** The caller left the `for await` loop with `break` (or called `events.return()`) before `turn.completed`, or aborted with `TurnOptions.signal`.
+- **`codex.stream_error.count` on an OK turn.** Codex retried a stream error and the turn completed; nothing failed.
+
+## Tests
+
+```bash
+pnpm --filter @traceai/codex-sdk test            # jest: span model, privacy, usage, patching, SDK shape
+pnpm --filter @traceai/codex-sdk test:contract   # build, then the real SDK against contract/fake-codex.mjs
+```

package/dist/esm/attributes.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Span names and attribute keys for Codex SDK spans.
+ *
+ * Standard keys (`fi.span.kind`, `session.id`, `input.value`, token counts...)
+ * come from `@traceai/fi-semantic-conventions` so the Future AGI collector
+ * promotes them. `codex.*` keys carry the SDK's own structural fields.
+ */
+import { FISpanKind } from "@traceai/fi-semantic-conventions";
+export declare const SpanNames: {
+    readonly TURN: "codex.turn";
+    readonly AGENT_MESSAGE: "codex.agent_message";
+    readonly REASONING: "codex.reasoning";
+    readonly COMMAND_EXECUTION: "codex.command_execution";
+    readonly FILE_CHANGE: "codex.file_change";
+    readonly MCP_TOOL_CALL: "codex.mcp_tool_call";
+    readonly WEB_SEARCH: "codex.web_search";
+    readonly TODO_LIST: "codex.todo_list";
+    readonly ERROR: "codex.error";
+};
+/** SDK item type -> span name and Future AGI span kind. */
+export declare const ITEM_SPANS: Record<string, {
+    name: string;
+    kind: FISpanKind;
+    tool: boolean;
+}>;
+/** Fallback for an item type a newer SDK adds. */
+export declare const UNKNOWN_ITEM_SPAN: {
+    kind: FISpanKind;
+    tool: boolean;
+};
+export declare const CodexAttributes: {
+    readonly THREAD_ID: "codex.thread.id";
+    readonly THREAD_RESUMED: "codex.thread.resumed";
+    readonly SANDBOX_MODE: "codex.sandbox_mode";
+    readonly APPROVAL_POLICY: "codex.approval_policy";
+    readonly REASONING_EFFORT: "codex.model_reasoning_effort";
+    readonly WEB_SEARCH_MODE: "codex.web_search_mode";
+    readonly INPUT_IMAGE_COUNT: "codex.input.image_count";
+    readonly INPUT_LENGTH: "codex.input.length";
+    readonly ITEM_ID: "codex.item.id";
+    readonly ITEM_TYPE: "codex.item.type";
+    readonly ITEM_STATUS: "codex.item.status";
+    /** false when the SDK sent only `item.completed`; the span then starts at the previous event. */
+    readonly ITEM_STARTED_EVENT: "codex.item.started_event";
+    readonly ITEM_INCOMPLETE: "codex.item.incomplete";
+    readonly COMMAND_EXIT_CODE: "codex.command.exit_code";
+    readonly COMMAND_OUTPUT_LENGTH: "codex.command.output_length";
+    readonly FILE_CHANGE_COUNT: "codex.file_change.count";
+    readonly FILE_CHANGE_KINDS: "codex.file_change.kinds";
+    readonly MCP_SERVER: "codex.mcp.server";
+    readonly MCP_TOOL: "codex.mcp.tool";
+    readonly TODO_COUNT: "codex.todo.count";
+    readonly TODO_COMPLETED: "codex.todo.completed";
+    readonly TEXT_LENGTH: "codex.text.length";
+    readonly USAGE_CACHED_INPUT_TOKENS: "codex.usage.cached_input_tokens";
+    readonly USAGE_CACHE_WRITE_INPUT_TOKENS: "codex.usage.cache_write_input_tokens";
+    readonly USAGE_REASONING_OUTPUT_TOKENS: "codex.usage.reasoning_output_tokens";
+    /** A resumed thread's first turn in this process: no earlier total, so nothing promoted. */
+    readonly USAGE_BASELINE_UNKNOWN: "codex.usage.baseline_unknown";
+    /** The running total went down; the reported value was promoted as is. */
+    readonly USAGE_NON_MONOTONIC: "codex.usage.non_monotonic";
+    /** Prefix for the thread's running totals, e.g. `codex.cumulative.input_tokens`. */
+    readonly CUMULATIVE_PREFIX: "codex.cumulative.";
+    /** Fixed summary unless outputs are visible; see README "Privacy". */
+    readonly ERROR_MESSAGE: "codex.error.message";
+    /** Error class name of a thrown error, e.g. `Error`, `TypeError`. */
+    readonly ERROR_TYPE: "codex.error.type";
+    /** `error` events in the turn. Codex sends them for errors it retries; the turn can still complete. */
+    readonly STREAM_ERROR_COUNT: "codex.stream_error.count";
+    /** On `codex.error` spans: a non-fatal error item (warning, deprecation, model reroute). */
+    readonly WARNING: "codex.warning";
+    readonly CANCELLED: "codex.cancelled";
+};
+/** Standard keys used by this package, resolved from fi-semantic-conventions. */
+export declare const StandardAttributes: {
+    readonly FI_SPAN_KIND: "fi.span.kind";
+    /** Same value as `fi.span.kind`; the Python fi_instrumentation key the collector also reads. */
+    readonly GEN_AI_SPAN_KIND: "gen_ai.span.kind";
+    readonly SESSION_ID: "session.id";
+    readonly CONVERSATION_ID: "gen_ai.conversation.id";
+    readonly INPUT_VALUE: "input.value";
+    readonly INPUT_MIME_TYPE: "input.mime_type";
+    readonly OUTPUT_VALUE: "output.value";
+    readonly OUTPUT_MIME_TYPE: "output.mime_type";
+    readonly MODEL_NAME: "gen_ai.request.model";
+    readonly PROVIDER: "gen_ai.provider.name";
+    readonly TOOL_NAME: "tool.name";
+    readonly GEN_AI_TOOL_NAME: "gen_ai.tool.name";
+    readonly TOOL_CALL_ID: "gen_ai.tool.call.id";
+    readonly AGENT_NAME: "gen_ai.agent.name";
+    readonly INPUT_TOKENS: "gen_ai.usage.input_tokens";
+    readonly OUTPUT_TOKENS: "gen_ai.usage.output_tokens";
+    readonly TOTAL_TOKENS: "gen_ai.usage.total_tokens";
+    readonly CACHE_READ_TOKENS: "gen_ai.usage.cache_read_tokens";
+    readonly CACHE_WRITE_TOKENS: "gen_ai.usage.cache_write_tokens";
+    readonly REASONING_TOKENS: "gen_ai.usage.output_tokens.reasoning";
+};
+export declare const AGENT_NAME = "codex";
+/** Codex talks to the OpenAI Responses API (or an OpenAI-compatible proxy). */
+export declare const PROVIDER_NAME = "openai";
+//# sourceMappingURL=attributes.d.ts.map

package/dist/esm/attributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attributes.d.ts","sourceRoot":"","sources":["../../src/attributes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAuB,MAAM,kCAAkC,CAAC;AAEnF,eAAO,MAAM,SAAS;;;;;;;;;;CAUZ,CAAC;AAEX,2DAA2D;AAC3D,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAUxF,CAAC;AAEF,kDAAkD;AAClD,eAAO,MAAM,iBAAiB;;;CAA0C,CAAC;AAEzE,eAAO,MAAM,eAAe;;;;;;;;;;;;IAa1B,iGAAiG;;;;;;;;;;;;;;;IAiBjG,4FAA4F;;IAE5F,0EAA0E;;IAE1E,oFAAoF;;IAGpF,sEAAsE;;IAEtE,qEAAqE;;IAErE,uGAAuG;;IAEvG,4FAA4F;;;CAGpF,CAAC;AAEX,iFAAiF;AACjF,eAAO,MAAM,kBAAkB;;IAE7B,gGAAgG;;;;;;;;;;;;;;;;;;;;CAoBxF,CAAC;AAEX,eAAO,MAAM,UAAU,UAAU,CAAC;AAClC,+EAA+E;AAC/E,eAAO,MAAM,aAAa,WAAW,CAAC"}

package/dist/esm/attributes.js

@@ -0,0 +1,104 @@
+/**
+ * Span names and attribute keys for Codex SDK spans.
+ *
+ * Standard keys (`fi.span.kind`, `session.id`, `input.value`, token counts...)
+ * come from `@traceai/fi-semantic-conventions` so the Future AGI collector
+ * promotes them. `codex.*` keys carry the SDK's own structural fields.
+ */
+import { FISpanKind, SemanticConventions } from "@traceai/fi-semantic-conventions";
+export const SpanNames = {
+    TURN: "codex.turn",
+    AGENT_MESSAGE: "codex.agent_message",
+    REASONING: "codex.reasoning",
+    COMMAND_EXECUTION: "codex.command_execution",
+    FILE_CHANGE: "codex.file_change",
+    MCP_TOOL_CALL: "codex.mcp_tool_call",
+    WEB_SEARCH: "codex.web_search",
+    TODO_LIST: "codex.todo_list",
+    ERROR: "codex.error",
+};
+/** SDK item type -> span name and Future AGI span kind. */
+export const ITEM_SPANS = {
+    agent_message: { name: SpanNames.AGENT_MESSAGE, kind: FISpanKind.LLM, tool: false },
+    reasoning: { name: SpanNames.REASONING, kind: FISpanKind.CHAIN, tool: false },
+    command_execution: { name: SpanNames.COMMAND_EXECUTION, kind: FISpanKind.TOOL, tool: true },
+    file_change: { name: SpanNames.FILE_CHANGE, kind: FISpanKind.TOOL, tool: true },
+    mcp_tool_call: { name: SpanNames.MCP_TOOL_CALL, kind: FISpanKind.TOOL, tool: true },
+    web_search: { name: SpanNames.WEB_SEARCH, kind: FISpanKind.TOOL, tool: true },
+    todo_list: { name: SpanNames.TODO_LIST, kind: FISpanKind.CHAIN, tool: false },
+    // Non-fatal: status UNSET with codex.warning=true.
+    error: { name: SpanNames.ERROR, kind: FISpanKind.CHAIN, tool: false },
+};
+/** Fallback for an item type a newer SDK adds. */
+export const UNKNOWN_ITEM_SPAN = { kind: FISpanKind.CHAIN, tool: false };
+export const CodexAttributes = {
+    THREAD_ID: "codex.thread.id",
+    THREAD_RESUMED: "codex.thread.resumed",
+    SANDBOX_MODE: "codex.sandbox_mode",
+    APPROVAL_POLICY: "codex.approval_policy",
+    REASONING_EFFORT: "codex.model_reasoning_effort",
+    WEB_SEARCH_MODE: "codex.web_search_mode",
+    INPUT_IMAGE_COUNT: "codex.input.image_count",
+    INPUT_LENGTH: "codex.input.length",
+    ITEM_ID: "codex.item.id",
+    ITEM_TYPE: "codex.item.type",
+    ITEM_STATUS: "codex.item.status",
+    /** false when the SDK sent only `item.completed`; the span then starts at the previous event. */
+    ITEM_STARTED_EVENT: "codex.item.started_event",
+    ITEM_INCOMPLETE: "codex.item.incomplete",
+    COMMAND_EXIT_CODE: "codex.command.exit_code",
+    COMMAND_OUTPUT_LENGTH: "codex.command.output_length",
+    FILE_CHANGE_COUNT: "codex.file_change.count",
+    FILE_CHANGE_KINDS: "codex.file_change.kinds",
+    MCP_SERVER: "codex.mcp.server",
+    MCP_TOOL: "codex.mcp.tool",
+    TODO_COUNT: "codex.todo.count",
+    TODO_COMPLETED: "codex.todo.completed",
+    TEXT_LENGTH: "codex.text.length",
+    USAGE_CACHED_INPUT_TOKENS: "codex.usage.cached_input_tokens",
+    USAGE_CACHE_WRITE_INPUT_TOKENS: "codex.usage.cache_write_input_tokens",
+    USAGE_REASONING_OUTPUT_TOKENS: "codex.usage.reasoning_output_tokens",
+    /** A resumed thread's first turn in this process: no earlier total, so nothing promoted. */
+    USAGE_BASELINE_UNKNOWN: "codex.usage.baseline_unknown",
+    /** The running total went down; the reported value was promoted as is. */
+    USAGE_NON_MONOTONIC: "codex.usage.non_monotonic",
+    /** Prefix for the thread's running totals, e.g. `codex.cumulative.input_tokens`. */
+    CUMULATIVE_PREFIX: "codex.cumulative.",
+    /** Fixed summary unless outputs are visible; see README "Privacy". */
+    ERROR_MESSAGE: "codex.error.message",
+    /** Error class name of a thrown error, e.g. `Error`, `TypeError`. */
+    ERROR_TYPE: "codex.error.type",
+    /** `error` events in the turn. Codex sends them for errors it retries; the turn can still complete. */
+    STREAM_ERROR_COUNT: "codex.stream_error.count",
+    /** On `codex.error` spans: a non-fatal error item (warning, deprecation, model reroute). */
+    WARNING: "codex.warning",
+    CANCELLED: "codex.cancelled",
+};
+/** Standard keys used by this package, resolved from fi-semantic-conventions. */
+export const StandardAttributes = {
+    FI_SPAN_KIND: SemanticConventions.FI_SPAN_KIND,
+    /** Same value as `fi.span.kind`; the Python fi_instrumentation key the collector also reads. */
+    GEN_AI_SPAN_KIND: "gen_ai.span.kind",
+    SESSION_ID: SemanticConventions.SESSION_ID,
+    CONVERSATION_ID: SemanticConventions.GEN_AI_CONVERSATION_ID,
+    INPUT_VALUE: SemanticConventions.INPUT_VALUE,
+    INPUT_MIME_TYPE: SemanticConventions.INPUT_MIME_TYPE,
+    OUTPUT_VALUE: SemanticConventions.OUTPUT_VALUE,
+    OUTPUT_MIME_TYPE: SemanticConventions.OUTPUT_MIME_TYPE,
+    MODEL_NAME: SemanticConventions.LLM_MODEL_NAME,
+    PROVIDER: SemanticConventions.LLM_PROVIDER,
+    TOOL_NAME: SemanticConventions.TOOL_NAME,
+    GEN_AI_TOOL_NAME: "gen_ai.tool.name",
+    TOOL_CALL_ID: "gen_ai.tool.call.id",
+    AGENT_NAME: "gen_ai.agent.name",
+    INPUT_TOKENS: SemanticConventions.LLM_TOKEN_COUNT_PROMPT,
+    OUTPUT_TOKENS: SemanticConventions.LLM_TOKEN_COUNT_COMPLETION,
+    TOTAL_TOKENS: SemanticConventions.LLM_TOKEN_COUNT_TOTAL,
+    CACHE_READ_TOKENS: SemanticConventions.LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_READ,
+    CACHE_WRITE_TOKENS: SemanticConventions.LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_WRITE,
+    REASONING_TOKENS: SemanticConventions.LLM_TOKEN_COUNT_COMPLETION_DETAILS_REASONING,
+};
+export const AGENT_NAME = "codex";
+/** Codex talks to the OpenAI Responses API (or an OpenAI-compatible proxy). */
+export const PROVIDER_NAME = "openai";
+//# sourceMappingURL=attributes.js.map

package/dist/esm/attributes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attributes.js","sourceRoot":"","sources":["../../src/attributes.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.d.ts

@@ -0,0 +1,8 @@
+export { CodexSDKInstrumentation, INSTRUMENTATION_NAME, instrumentCodexSDK, resolveContentPolicy, shutdown, } from "./instrumentation.js";
+export type { CodexSDKInstrumentationConfig } from "./instrumentation.js";
+export { isPatched } from "./threadWrapper.js";
+export type { ContentPolicy } from "./spans.js";
+export { AGENT_NAME, CodexAttributes, ITEM_SPANS, PROVIDER_NAME, SpanNames, StandardAttributes, } from "./attributes.js";
+export type { CodexModuleLike, ThreadEventLike, ThreadItemLike, ThreadLike, ThreadOptionsLike, UsageLike, } from "./types.js";
+export { VERSION } from "./version.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,QAAQ,GACT,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,6BAA6B,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,EACL,UAAU,EACV,eAAe,EACf,UAAU,EACV,aAAa,EACb,SAAS,EACT,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,eAAe,EACf,eAAe,EACf,cAAc,EACd,UAAU,EACV,iBAAiB,EACjB,SAAS,GACV,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,5 @@
+export { CodexSDKInstrumentation, INSTRUMENTATION_NAME, instrumentCodexSDK, resolveContentPolicy, shutdown, } from "./instrumentation.js";
+export { isPatched } from "./threadWrapper.js";
+export { AGENT_NAME, CodexAttributes, ITEM_SPANS, PROVIDER_NAME, SpanNames, StandardAttributes, } from "./attributes.js";
+export { VERSION } from "./version.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,QAAQ,GACT,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EACL,UAAU,EACV,eAAe,EACf,UAAU,EACV,aAAa,EACb,SAAS,EACT,kBAAkB,GACnB,MAAM,cAAc,CAAC;AAStB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC"}

package/dist/esm/instrumentation.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Public entry points: an instrumentation object that patches the SDK's
+ * `Thread` class (or single `Codex` / `Thread` instances), and a `shutdown()`
+ * that flushes the tracer provider before a short script exits.
+ */
+import { TracerProvider } from "@opentelemetry/api";
+import { TraceConfigOptions } from "@traceai/fi-core";
+import { ContentPolicy } from "./spans.js";
+import { CodexModuleLike } from "./types.js";
+export declare const INSTRUMENTATION_NAME = "@traceai/codex-sdk";
+export interface CodexSDKInstrumentationConfig {
+    /** Provider to create spans with. Defaults to the global provider at call time. */
+    tracerProvider?: TracerProvider;
+    /**
+     * fi-core trace config. Unlike fi-core, `hideInputs` and `hideOutputs`
+     * default to `true` here: prompts, shell commands, command output, file
+     * paths and MCP arguments can contain source code or secrets. Opt in with
+     * `false`, or with `FI_HIDE_INPUTS=false` / `FI_HIDE_OUTPUTS=false`.
+     */
+    traceConfig?: TraceConfigOptions;
+}
+/** Precedence: explicit option > fi-core env var > this package's default (hidden). */
+export declare function resolveContentPolicy(traceConfig?: TraceConfigOptions): ContentPolicy;
+/**
+ * Traces `@openai/codex-sdk` turns.
+ *
+ * ```ts
+ * import * as CodexSDK from "@openai/codex-sdk";
+ * const instrumentation = new CodexSDKInstrumentation({ tracerProvider });
+ * instrumentation.manuallyInstrument(CodexSDK);
+ * const thread = new CodexSDK.Codex().startThread();
+ * await thread.run("...");   // one codex.turn trace
+ * ```
+ *
+ * The SDK is ESM-only, so its module namespace cannot be patched; its `Thread`
+ * class prototype can. `wrapCodex()` / `wrapThread()` patch single instances
+ * instead, for apps that prefer not to touch the shared class.
+ *
+ * This is not an OpenTelemetry `InstrumentationBase`: there is no module to
+ * hook on `require`/`import`, so it cannot be passed to
+ * `registerInstrumentations()`. Call `manuallyInstrument()` or the wrap methods.
+ */
+export declare class CodexSDKInstrumentation {
+    private tracerProvider?;
+    private readonly traceConfig?;
+    /** Undo functions for the class patch and wrapCodex() factories (never one per thread). */
+    private readonly undo;
+    /** False after unpatch(): instance patches stay in place but pass events through untraced. */
+    private enabled;
+    constructor(config?: CodexSDKInstrumentationConfig);
+    setTracerProvider(tracerProvider: TracerProvider): void;
+    /** The content policy this instrumentation applies. */
+    get contentPolicy(): ContentPolicy;
+    /**
+     * Patch `module.Thread.prototype`. Pass the SDK module namespace
+     * (`import * as CodexSDK from "@openai/codex-sdk"`) or `{ Thread }`.
+     * Returns `true` when the class was patched by this call.
+     */
+    manuallyInstrument(module: CodexModuleLike): boolean;
+    /**
+     * Patch one Thread instance. Returns the same instance. No reference to the
+     * thread is kept: after `unpatch()` the patched method passes events through
+     * untraced instead of being removed.
+     */
+    wrapThread<T extends object>(thread: T): T;
+    /** Patch one Codex instance so every thread it starts or resumes is traced. Returns the same instance. */
+    wrapCodex<T extends object>(codex: T): T;
+    /** Remove every patch this instrumentation applied. */
+    unpatch(): void;
+    /** Flush the provider's span processors. Does not shut the provider down. */
+    forceFlush(): Promise<void>;
+    private tracingContext;
+}
+/** Python-style convenience constructor. */
+export declare function instrumentCodexSDK(module: CodexModuleLike, config?: CodexSDKInstrumentationConfig): CodexSDKInstrumentation;
+/**
+ * Flush spans before a short script exits. Export errors are logged, never
+ * thrown: export failure does not fail the agent.
+ */
+export declare function shutdown(tracerProvider?: TracerProvider): Promise<void>;
+//# sourceMappingURL=instrumentation.d.ts.map

package/dist/esm/instrumentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation.d.ts","sourceRoot":"","sources":["../../src/instrumentation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,cAAc,EAAe,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAY,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAExC,OAAO,EAAE,eAAe,EAAc,MAAM,SAAS,CAAC;AAGtD,eAAO,MAAM,oBAAoB,uBAAuB,CAAC;AAUzD,MAAM,WAAW,6BAA6B;IAC5C,mFAAmF;IACnF,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC;AAQD,uFAAuF;AACvF,wBAAgB,oBAAoB,CAAC,WAAW,CAAC,EAAE,kBAAkB,GAAG,aAAa,CAMpF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,cAAc,CAAC,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAqB;IAClD,2FAA2F;IAC3F,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyB;IAC9C,8FAA8F;IAC9F,OAAO,CAAC,OAAO,CAAQ;gBAEX,MAAM,GAAE,6BAAkC;IAKtD,iBAAiB,CAAC,cAAc,EAAE,cAAc,GAAG,IAAI;IAIvD,uDAAuD;IACvD,IAAI,aAAa,IAAI,aAAa,CAEjC;IAED;;;;OAIG;IACH,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO;IAYpD;;;;OAIG;IACH,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC;IAM1C,0GAA0G;IAC1G,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC;IA4BxC,uDAAuD;IACvD,OAAO,IAAI,IAAI;IAYf,6EAA6E;IACvE,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC,OAAO,CAAC,cAAc;CAUvB;AAED,4CAA4C;AAC5C,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,eAAe,EACvB,MAAM,GAAE,6BAAkC,GACzC,uBAAuB,CAIzB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7E"}