@traceai/codex-sdk 0.0.0-stage → 0.1.0

package/dist/src/attributes.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROVIDER_NAME = exports.AGENT_NAME = exports.StandardAttributes = exports.CodexAttributes = exports.UNKNOWN_ITEM_SPAN = exports.ITEM_SPANS = exports.SpanNames = void 0;
+/**
+ * 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.
+ */
+const fi_semantic_conventions_1 = require("@traceai/fi-semantic-conventions");
+exports.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. */
+exports.ITEM_SPANS = {
+    agent_message: { name: exports.SpanNames.AGENT_MESSAGE, kind: fi_semantic_conventions_1.FISpanKind.LLM, tool: false },
+    reasoning: { name: exports.SpanNames.REASONING, kind: fi_semantic_conventions_1.FISpanKind.CHAIN, tool: false },
+    command_execution: { name: exports.SpanNames.COMMAND_EXECUTION, kind: fi_semantic_conventions_1.FISpanKind.TOOL, tool: true },
+    file_change: { name: exports.SpanNames.FILE_CHANGE, kind: fi_semantic_conventions_1.FISpanKind.TOOL, tool: true },
+    mcp_tool_call: { name: exports.SpanNames.MCP_TOOL_CALL, kind: fi_semantic_conventions_1.FISpanKind.TOOL, tool: true },
+    web_search: { name: exports.SpanNames.WEB_SEARCH, kind: fi_semantic_conventions_1.FISpanKind.TOOL, tool: true },
+    todo_list: { name: exports.SpanNames.TODO_LIST, kind: fi_semantic_conventions_1.FISpanKind.CHAIN, tool: false },
+    // Non-fatal: status UNSET with codex.warning=true.
+    error: { name: exports.SpanNames.ERROR, kind: fi_semantic_conventions_1.FISpanKind.CHAIN, tool: false },
+};
+/** Fallback for an item type a newer SDK adds. */
+exports.UNKNOWN_ITEM_SPAN = { kind: fi_semantic_conventions_1.FISpanKind.CHAIN, tool: false };
+exports.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. */
+exports.StandardAttributes = {
+    FI_SPAN_KIND: fi_semantic_conventions_1.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: fi_semantic_conventions_1.SemanticConventions.SESSION_ID,
+    CONVERSATION_ID: fi_semantic_conventions_1.SemanticConventions.GEN_AI_CONVERSATION_ID,
+    INPUT_VALUE: fi_semantic_conventions_1.SemanticConventions.INPUT_VALUE,
+    INPUT_MIME_TYPE: fi_semantic_conventions_1.SemanticConventions.INPUT_MIME_TYPE,
+    OUTPUT_VALUE: fi_semantic_conventions_1.SemanticConventions.OUTPUT_VALUE,
+    OUTPUT_MIME_TYPE: fi_semantic_conventions_1.SemanticConventions.OUTPUT_MIME_TYPE,
+    MODEL_NAME: fi_semantic_conventions_1.SemanticConventions.LLM_MODEL_NAME,
+    PROVIDER: fi_semantic_conventions_1.SemanticConventions.LLM_PROVIDER,
+    TOOL_NAME: fi_semantic_conventions_1.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: fi_semantic_conventions_1.SemanticConventions.LLM_TOKEN_COUNT_PROMPT,
+    OUTPUT_TOKENS: fi_semantic_conventions_1.SemanticConventions.LLM_TOKEN_COUNT_COMPLETION,
+    TOTAL_TOKENS: fi_semantic_conventions_1.SemanticConventions.LLM_TOKEN_COUNT_TOTAL,
+    CACHE_READ_TOKENS: fi_semantic_conventions_1.SemanticConventions.LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_READ,
+    CACHE_WRITE_TOKENS: fi_semantic_conventions_1.SemanticConventions.LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_WRITE,
+    REASONING_TOKENS: fi_semantic_conventions_1.SemanticConventions.LLM_TOKEN_COUNT_COMPLETION_DETAILS_REASONING,
+};
+exports.AGENT_NAME = "codex";
+/** Codex talks to the OpenAI Responses API (or an OpenAI-compatible proxy). */
+exports.PROVIDER_NAME = "openai";
+//# sourceMappingURL=attributes.js.map

package/dist/src/attributes.js.map

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

package/dist/src/index.d.ts

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

package/dist/src/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/src/index.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = exports.StandardAttributes = exports.SpanNames = exports.PROVIDER_NAME = exports.ITEM_SPANS = exports.CodexAttributes = exports.AGENT_NAME = exports.isPatched = exports.shutdown = exports.resolveContentPolicy = exports.instrumentCodexSDK = exports.INSTRUMENTATION_NAME = exports.CodexSDKInstrumentation = void 0;
+var instrumentation_1 = require("./instrumentation");
+Object.defineProperty(exports, "CodexSDKInstrumentation", { enumerable: true, get: function () { return instrumentation_1.CodexSDKInstrumentation; } });
+Object.defineProperty(exports, "INSTRUMENTATION_NAME", { enumerable: true, get: function () { return instrumentation_1.INSTRUMENTATION_NAME; } });
+Object.defineProperty(exports, "instrumentCodexSDK", { enumerable: true, get: function () { return instrumentation_1.instrumentCodexSDK; } });
+Object.defineProperty(exports, "resolveContentPolicy", { enumerable: true, get: function () { return instrumentation_1.resolveContentPolicy; } });
+Object.defineProperty(exports, "shutdown", { enumerable: true, get: function () { return instrumentation_1.shutdown; } });
+var threadWrapper_1 = require("./threadWrapper");
+Object.defineProperty(exports, "isPatched", { enumerable: true, get: function () { return threadWrapper_1.isPatched; } });
+var attributes_1 = require("./attributes");
+Object.defineProperty(exports, "AGENT_NAME", { enumerable: true, get: function () { return attributes_1.AGENT_NAME; } });
+Object.defineProperty(exports, "CodexAttributes", { enumerable: true, get: function () { return attributes_1.CodexAttributes; } });
+Object.defineProperty(exports, "ITEM_SPANS", { enumerable: true, get: function () { return attributes_1.ITEM_SPANS; } });
+Object.defineProperty(exports, "PROVIDER_NAME", { enumerable: true, get: function () { return attributes_1.PROVIDER_NAME; } });
+Object.defineProperty(exports, "SpanNames", { enumerable: true, get: function () { return attributes_1.SpanNames; } });
+Object.defineProperty(exports, "StandardAttributes", { enumerable: true, get: function () { return attributes_1.StandardAttributes; } });
+var version_1 = require("./version");
+Object.defineProperty(exports, "VERSION", { enumerable: true, get: function () { return version_1.VERSION; } });
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,qDAM2B;AALzB,0HAAA,uBAAuB,OAAA;AACvB,uHAAA,oBAAoB,OAAA;AACpB,qHAAA,kBAAkB,OAAA;AAClB,uHAAA,oBAAoB,OAAA;AACpB,2GAAA,QAAQ,OAAA;AAGV,iDAA4C;AAAnC,0GAAA,SAAS,OAAA;AAElB,2CAOsB;AANpB,wGAAA,UAAU,OAAA;AACV,6GAAA,eAAe,OAAA;AACf,wGAAA,UAAU,OAAA;AACV,2GAAA,aAAa,OAAA;AACb,uGAAA,SAAS,OAAA;AACT,gHAAA,kBAAkB,OAAA;AAUpB,qCAAoC;AAA3B,kGAAA,OAAO,OAAA"}

package/dist/src/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";
+import { CodexModuleLike } from "./types";
+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/src/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"}

package/dist/src/instrumentation.js

@@ -0,0 +1,213 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CodexSDKInstrumentation = exports.INSTRUMENTATION_NAME = void 0;
+exports.resolveContentPolicy = resolveContentPolicy;
+exports.instrumentCodexSDK = instrumentCodexSDK;
+exports.shutdown = shutdown;
+/**
+ * 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.
+ */
+const api_1 = require("@opentelemetry/api");
+const fi_core_1 = require("@traceai/fi-core");
+const threadWrapper_1 = require("./threadWrapper");
+const version_1 = require("./version");
+exports.INSTRUMENTATION_NAME = "@traceai/codex-sdk";
+/**
+ * fi-core env keys. Read fail-closed, unlike fi-core (`value.toLowerCase() ===
+ * "true"`): only an explicit `false` (trimmed, any case) opts in to content.
+ */
+const FI_HIDE_INPUTS = "FI_HIDE_INPUTS";
+const FI_HIDE_OUTPUTS = "FI_HIDE_OUTPUTS";
+const FI_HIDE_ERROR_DETAILS = "FI_HIDE_ERROR_DETAILS";
+/** `false` only for an explicit `false`; any other value (or none) keeps content hidden. */
+function envHide(key) {
+    var _a;
+    const value = typeof process !== "undefined" ? (_a = process.env) === null || _a === void 0 ? void 0 : _a[key] : undefined;
+    return !(typeof value === "string" && value.trim().toLowerCase() === "false");
+}
+/** Precedence: explicit option > fi-core env var > this package's default (hidden). */
+function resolveContentPolicy(traceConfig) {
+    var _a, _b, _c;
+    return {
+        hideInputs: (_a = traceConfig === null || traceConfig === void 0 ? void 0 : traceConfig.hideInputs) !== null && _a !== void 0 ? _a : envHide(FI_HIDE_INPUTS),
+        hideOutputs: (_b = traceConfig === null || traceConfig === void 0 ? void 0 : traceConfig.hideOutputs) !== null && _b !== void 0 ? _b : envHide(FI_HIDE_OUTPUTS),
+        hideErrorDetails: (_c = traceConfig === null || traceConfig === void 0 ? void 0 : traceConfig.hideErrorDetails) !== null && _c !== void 0 ? _c : envHide(FI_HIDE_ERROR_DETAILS),
+    };
+}
+/**
+ * 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.
+ */
+class CodexSDKInstrumentation {
+    constructor(config = {}) {
+        /** Undo functions for the class patch and wrapCodex() factories (never one per thread). */
+        this.undo = [];
+        /** False after unpatch(): instance patches stay in place but pass events through untraced. */
+        this.enabled = true;
+        this.traceConfig = config.traceConfig;
+        this.tracerProvider = config.tracerProvider;
+    }
+    setTracerProvider(tracerProvider) {
+        this.tracerProvider = tracerProvider;
+    }
+    /** The content policy this instrumentation applies. */
+    get contentPolicy() {
+        return resolveContentPolicy(this.traceConfig);
+    }
+    /**
+     * 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) {
+        var _a;
+        const proto = (_a = module === null || module === void 0 ? void 0 : module.Thread) === null || _a === void 0 ? void 0 : _a.prototype;
+        if (!proto) {
+            api_1.diag.warn(`${exports.INSTRUMENTATION_NAME}: manuallyInstrument() expects the @openai/codex-sdk module (no Thread export found)`);
+            return false;
+        }
+        this.enabled = true;
+        const undo = (0, threadWrapper_1.patchThread)(proto, () => this.tracingContext());
+        if (undo)
+            this.undo.push(undo);
+        return !!undo;
+    }
+    /**
+     * 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(thread) {
+        this.enabled = true;
+        (0, threadWrapper_1.patchThread)(thread, () => this.tracingContext());
+        return thread;
+    }
+    /** Patch one Codex instance so every thread it starts or resumes is traced. Returns the same instance. */
+    wrapCodex(codex) {
+        if (!codex || typeof codex !== "object")
+            return codex;
+        this.enabled = true;
+        const target = codex;
+        // Held weakly: a wrapped client the app drops can be collected before unpatch().
+        const ref = new WeakRef(target);
+        for (const method of ["startThread", "resumeThread"]) {
+            const original = target[method];
+            if (typeof original !== "function")
+                continue;
+            const hadOwn = Object.prototype.hasOwnProperty.call(codex, method);
+            const self = this;
+            Object.defineProperty(codex, method, {
+                value: function tracedThreadFactory(...args) {
+                    return self.wrapThread(original.apply(this, args));
+                },
+                writable: true,
+                configurable: true,
+            });
+            this.undo.push(() => {
+                const live = ref.deref();
+                if (!live)
+                    return;
+                if (hadOwn)
+                    Object.defineProperty(live, method, { value: original, writable: true, configurable: true });
+                else
+                    delete live[method];
+            });
+        }
+        return codex;
+    }
+    /** Remove every patch this instrumentation applied. */
+    unpatch() {
+        this.enabled = false;
+        while (this.undo.length) {
+            const fn = this.undo.pop();
+            try {
+                fn === null || fn === void 0 ? void 0 : fn();
+            }
+            catch (error) {
+                api_1.diag.debug(`${exports.INSTRUMENTATION_NAME}: unpatch failed: ${error}`);
+            }
+        }
+    }
+    /** Flush the provider's span processors. Does not shut the provider down. */
+    forceFlush() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            yield flushProvider((_a = this.tracerProvider) !== null && _a !== void 0 ? _a : api_1.trace.getTracerProvider());
+        });
+    }
+    tracingContext() {
+        var _a;
+        if (!this.enabled)
+            return undefined;
+        const policy = this.contentPolicy;
+        const provider = (_a = this.tracerProvider) !== null && _a !== void 0 ? _a : api_1.trace.getTracerProvider();
+        const tracer = new fi_core_1.FITracer({
+            tracer: provider.getTracer(exports.INSTRUMENTATION_NAME, version_1.VERSION),
+            traceConfig: Object.assign(Object.assign({}, this.traceConfig), { hideInputs: policy.hideInputs, hideOutputs: policy.hideOutputs, hideErrorDetails: policy.hideErrorDetails }),
+        });
+        return { tracer, policy };
+    }
+}
+exports.CodexSDKInstrumentation = CodexSDKInstrumentation;
+/** Python-style convenience constructor. */
+function instrumentCodexSDK(module, config = {}) {
+    const instrumentation = new CodexSDKInstrumentation(config);
+    instrumentation.manuallyInstrument(module);
+    return instrumentation;
+}
+/**
+ * Flush spans before a short script exits. Export errors are logged, never
+ * thrown: export failure does not fail the agent.
+ */
+function shutdown(tracerProvider) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield flushProvider(tracerProvider !== null && tracerProvider !== void 0 ? tracerProvider : api_1.trace.getTracerProvider());
+    });
+}
+function resolveDelegate(provider) {
+    const maybeProxy = provider;
+    if (typeof maybeProxy.forceFlush !== "function" && typeof maybeProxy.getDelegate === "function") {
+        return maybeProxy.getDelegate();
+    }
+    return provider;
+}
+function flushProvider(provider) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const target = resolveDelegate(provider);
+        if (typeof target.forceFlush !== "function")
+            return;
+        try {
+            yield target.forceFlush();
+        }
+        catch (error) {
+            api_1.diag.warn(`${exports.INSTRUMENTATION_NAME}: forceFlush failed: ${error}`);
+        }
+    });
+}
+//# sourceMappingURL=instrumentation.js.map

package/dist/src/instrumentation.js.map

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

package/dist/src/spans.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Span model for one Codex turn (one `Thread.run()` or `Thread.runStreamed()`).
+ *
+ * The SDK yields `ThreadEvent`s, not spans. `TurnTracer` turns them into:
+ *
+ *   codex.turn                     (AGENT)   session.id = thread id, usage
+ *   ├─ codex.reasoning             (CHAIN)
+ *   ├─ codex.command_execution     (TOOL)
+ *   ├─ codex.file_change           (TOOL)
+ *   ├─ codex.mcp_tool_call         (TOOL)
+ *   ├─ codex.web_search            (TOOL)
+ *   ├─ codex.todo_list             (CHAIN)
+ *   ├─ codex.agent_message         (LLM)
+ *   └─ codex.error                 (CHAIN, codex.warning=true)   non-fatal error item
+ *
+ * Every public method swallows its own errors: tracing never fails the agent.
+ */
+import { Context, HrTime, Tracer } from "@opentelemetry/api";
+import { InputLike, ThreadOptionsLike, TurnOptionsLike } from "./types";
+/** Which content the wrapper may copy onto spans. Both default to hidden. */
+export interface ContentPolicy {
+    hideInputs: boolean;
+    hideOutputs: boolean;
+    /** Error details remain hidden even when ordinary outputs are visible. */
+    hideErrorDetails: boolean;
+}
+/** How the wrapped event stream stopped. */
+export type FinishOutcome = {
+    kind: "completed";
+} | {
+    kind: "returned";
+} | {
+    kind: "error";
+    error: unknown;
+};
+/**
+ * One clock for every start and end time the wrapper sets. OTel falls back to
+ * millisecond `Date.now()` for the end of a span whose start time was given,
+ * so mixing explicit and implicit times can order a child after its parent.
+ */
+export declare function clockMs(): number;
+export declare function toHrTime(ms: number): HrTime;
+export declare function truncate(value: string, max: number): string;
+export declare function safeJson(value: unknown, max?: number): string;
+/** Same normalization as the SDK's `normalizeInput`: text parts joined by a blank line. */
+export declare function normalizeInput(input: InputLike | undefined): {
+    prompt: string;
+    images: number;
+};
+/**
+ * The SDK builds its thrown messages from raw data: `Codex Exec exited with
+ * code 1: <the binary's stderr>` and `Failed to parse item: <the raw line>`
+ * (dist/index.js of 0.162.1). Stderr can hold config lines, local paths and
+ * the user name; the raw line can hold the prompt or command output. With
+ * outputs hidden only this fixed summary is exported.
+ */
+export declare function errorSummary(error: unknown): string;
+type UsageTotals = {
+    input_tokens?: number;
+    cached_input_tokens?: number;
+    cache_write_input_tokens?: number;
+    output_tokens?: number;
+    reasoning_output_tokens?: number;
+};
+/**
+ * Last running total seen per thread id in this process (LRU, 1000 threads).
+ * Exact while a thread's turns run in one process; see the README.
+ */
+declare class UsageBaselines {
+    private readonly totals;
+    get(threadId: string): UsageTotals | undefined;
+    set(threadId: string, totals: UsageTotals): void;
+    clear(): void;
+    get size(): number;
+}
+export declare const usageBaselines: UsageBaselines;
+export declare class TurnTracer {
+    private readonly tracer;
+    private readonly policy;
+    private readonly parentContext;
+    private readonly startTimeMs;
+    private readonly input;
+    private readonly turnOptions;
+    private readonly threadOptions;
+    private readonly contextAttributes;
+    private readonly appSetSession;
+    private readonly resumed;
+    private turn?;
+    private turnContext?;
+    private finished;
+    private threadId?;
+    private lastEventMs;
+    private finalResponse?;
+    private completed;
+    /** `turn.failed` text; the turn failed. */
+    private failedMessage?;
+    /** Last `error` event text. Fatal only if the turn ends without `turn.completed`. */
+    private streamErrorMessage?;
+    private streamErrorCount;
+    private readonly items;
+    private anonymousItems;
+    constructor(args: {
+        tracer: Tracer;
+        policy: ContentPolicy;
+        parentContext: Context;
+        input: InputLike | undefined;
+        turnOptions?: TurnOptionsLike;
+        threadOptions?: ThreadOptionsLike;
+        threadId?: string | null;
+        startTimeMs?: number;
+    });
+    private get hideErrorText();
+    get isFinished(): boolean;
+    /** Open the turn span. Called on the first `next()`; idempotent. */
+    start(): void;
+    /** Record one SDK event. Never throws and never mutates the event. */
+    onEvent(event: unknown): void;
+    /**
+     * End every open span for this turn, the turn span last. Idempotent.
+     * The spans always end, even if recording their attributes throws: item
+     * spans that already ended were exported with the turn as their parent.
+     */
+    finish(outcome: FinishOutcome): void;
+    /** Statuses and attributes for `finish()`; closes open item spans. */
+    private recordFinish;
+    private turnStartAttributes;
+    private sessionAttributes;
+    private setThreadId;
+    /**
+     * `turn.completed.usage` is the thread's running total, not the turn's own
+     * spend (measured on 0.162.1: each resumed turn reports the previous total
+     * plus its own requests, also across processes). The promoted
+     * `gen_ai.usage.*` keys carry only this turn's new spend: the total minus
+     * the last total this process saw for the thread. A new thread starts at
+     * zero. A resumed thread with no total seen in this process promotes nothing
+     * (`codex.usage.baseline_unknown`); later turns promote their delta.
+     * A failed or cancelled turn reports no usage, so its spend lands on the
+     * thread's next completed turn. Running totals are always on
+     * `codex.cumulative.*`.
+     */
+    private setUsage;
+    private itemKey;
+    private onItemStarted;
+    private onItemUpdated;
+    private onItemCompleted;
+    private startItemSpan;
+    /** Structural fields always; content only when the policy allows it. */
+    private applyItemAttributes;
+    private applyItemStatus;
+}
+export {};
+//# sourceMappingURL=spans.d.ts.map

package/dist/src/spans.d.ts.map

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