@traceai/codex-sdk 0.0.0-stage → 0.1.1

package/src/attributes.ts

@@ -0,0 +1,113 @@
+/**
+ * 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",
+} as const;
+
+/** SDK item type -> span name and Future AGI span kind. */
+export const ITEM_SPANS: Record<string, { name: string; kind: FISpanKind; tool: boolean }> = {
+  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",
+} as const;
+
+/** 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,
+} as const;
+
+export const AGENT_NAME = "codex";
+/** Codex talks to the OpenAI Responses API (or an OpenAI-compatible proxy). */
+export const PROVIDER_NAME = "openai";

package/src/codexWrapper.ts

@@ -0,0 +1,71 @@
+import { diag } from "@opentelemetry/api";
+
+const PATCH_RECORD = Symbol.for("@traceai/codex-sdk/client-patch-record");
+const METHODS = ["startThread", "resumeThread"] as const;
+type Client = Record<string | symbol, unknown>;
+
+interface Owner {
+  active: boolean;
+}
+
+interface FactoryPatch {
+  method: typeof METHODS[number];
+  originalDescriptor: PropertyDescriptor | undefined;
+  wrapper: (...args: unknown[]) => object;
+}
+
+interface ClientPatch {
+  owner: Owner;
+  factories: FactoryPatch[];
+}
+
+/** Retain neither the client nor a possibly bound original factory in this closure. */
+function weakUndo(ref: WeakRef<Client>, owner: Owner): () => void {
+  return () => {
+    // Saved wrappers must remain inert even if the instrumentor is enabled again.
+    owner.active = false;
+    const target = ref.deref();
+    if (!target) return;
+    const record = Object.getOwnPropertyDescriptor(target, PATCH_RECORD)?.value as ClientPatch | undefined;
+    if (record?.owner !== owner) return;
+    for (const { method, originalDescriptor, wrapper } of record.factories) {
+      try {
+        // Inspect the descriptor, not the value: application accessors must not run.
+        if (Object.getOwnPropertyDescriptor(target, method)?.value !== wrapper) continue;
+        if (originalDescriptor) Object.defineProperty(target, method, originalDescriptor);
+        else delete target[method];
+      } catch (error) {
+        diag.debug(`@traceai/codex-sdk: factory unpatch failed: ${error}`);
+      }
+    }
+    delete target[PATCH_RECORD];
+  };
+}
+
+/** A client has one active owner, just like a Thread; duplicate owners do not stack. */
+export function patchCodex(target: Client, wrapThread: (thread: object) => object): (() => void) | undefined {
+  if ((target[PATCH_RECORD] as ClientPatch | undefined)?.owner.active) return undefined;
+  const owner: Owner = { active: true };
+  const record: ClientPatch = { owner, factories: [] };
+  const undo = weakUndo(new WeakRef(target), owner);
+  Object.defineProperty(target, PATCH_RECORD, { value: record, configurable: true });
+  try {
+    for (const method of METHODS) {
+      const original = target[method];
+      if (typeof original !== "function") continue;
+      const originalDescriptor = Object.getOwnPropertyDescriptor(target, method);
+      const wrapper = function tracedThreadFactory(this: unknown, ...args: unknown[]): object {
+        const thread = original.apply(this, args);
+        return owner.active ? wrapThread(thread) : thread;
+      };
+      Object.defineProperty(target, method, { value: wrapper, writable: true, configurable: true });
+      record.factories.push({ method, originalDescriptor, wrapper });
+    }
+  } catch (error) {
+    undo();
+    throw error;
+  }
+  if (record.factories.length) return undo;
+  undo();
+  return undefined;
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+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";

package/src/instrumentation.ts

@@ -0,0 +1,227 @@
+/**
+ * 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, diag, trace } from "@opentelemetry/api";
+import { FITracer, TraceConfigOptions } from "@traceai/fi-core";
+import { patchCodex } from "./codexWrapper";
+import { ContentPolicy } from "./spans";
+import { TurnTracingContext, patchThread } from "./threadWrapper";
+import { CodexModuleLike, ThreadLike } from "./types";
+import { VERSION } from "./version";
+
+export const 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";
+
+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;
+}
+
+/** `false` only for an explicit `false`; any other value (or none) keeps content hidden. */
+function envHide(key: string): boolean {
+  const value = typeof process !== "undefined" ? process.env?.[key] : undefined;
+  return !(typeof value === "string" && value.trim().toLowerCase() === "false");
+}
+
+/** Precedence: explicit option > fi-core env var > this package's default (hidden). */
+export function resolveContentPolicy(traceConfig?: TraceConfigOptions): ContentPolicy {
+  return {
+    hideInputs: traceConfig?.hideInputs ?? envHide(FI_HIDE_INPUTS),
+    hideOutputs: traceConfig?.hideOutputs ?? envHide(FI_HIDE_OUTPUTS),
+    hideErrorDetails: traceConfig?.hideErrorDetails ?? 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.
+ */
+export class CodexSDKInstrumentation {
+  private tracerProvider?: TracerProvider;
+  private readonly traceConfig?: TraceConfigOptions;
+  /** Undo functions for class patches. */
+  private readonly undo: Array<() => void> = [];
+  /** Client undo functions hold only WeakRefs; collected clients release their bookkeeping. */
+  private readonly clientUndo = new Set<() => void>();
+  private readonly clientFinalizer = new FinalizationRegistry<() => void>((undo) => {
+    // Deactivate the owner too: saved factories must remain inert after collection.
+    undo();
+    this.clientUndo.delete(undo);
+  });
+  /** Thread undo functions hold only WeakRefs; collected threads release their bookkeeping. */
+  private readonly threadUndo = new Set<() => void>();
+  private readonly threadFinalizer = new FinalizationRegistry<() => void>((undo) => {
+    this.threadUndo.delete(undo);
+  });
+  private enabled = true;
+
+  constructor(config: CodexSDKInstrumentationConfig = {}) {
+    this.traceConfig = config.traceConfig;
+    this.tracerProvider = config.tracerProvider;
+  }
+
+  setTracerProvider(tracerProvider: TracerProvider): void {
+    this.tracerProvider = tracerProvider;
+  }
+
+  /** The content policy this instrumentation applies. */
+  get contentPolicy(): 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: CodexModuleLike): boolean {
+    const proto = (module?.Thread as { prototype?: ThreadLike } | undefined)?.prototype;
+    if (!proto) {
+      diag.warn(`${INSTRUMENTATION_NAME}: manuallyInstrument() expects the @openai/codex-sdk module (no Thread export found)`);
+      return false;
+    }
+    this.enabled = true;
+    const undo = patchThread(proto, () => this.tracingContext());
+    if (undo) this.undo.push(undo);
+    return !!undo;
+  }
+
+  /**
+   * Patch one Thread instance. Returns the same instance. Only a weak reference
+   * is kept, so `unpatch()` can restore live threads without retaining dropped ones.
+   */
+  wrapThread<T extends object>(thread: T): T {
+    this.enabled = true;
+    const undo = patchThread(thread as ThreadLike, () => this.tracingContext());
+    if (undo) {
+      this.threadUndo.add(undo);
+      this.threadFinalizer.register(thread, undo, undo);
+    }
+    return thread;
+  }
+
+  /** Patch one Codex instance so every thread it starts or resumes is traced. Returns the same instance. */
+  wrapCodex<T extends object>(codex: T): T {
+    if (!codex || typeof codex !== "object") return codex;
+    this.enabled = true;
+    const undo = patchCodex(codex as Record<string | symbol, unknown>, (thread) => this.wrapThread(thread));
+    if (undo) {
+      this.clientUndo.add(undo);
+      this.clientFinalizer.register(codex, undo, undo);
+    }
+    return codex;
+  }
+
+  /** Remove every patch this instrumentation applied. */
+  unpatch(): void {
+    this.enabled = false;
+    for (const undo of this.threadUndo) {
+      this.threadFinalizer.unregister(undo);
+      undo();
+    }
+    this.threadUndo.clear();
+    for (const undo of this.clientUndo) {
+      this.clientFinalizer.unregister(undo);
+      try {
+        undo();
+      } catch (error) {
+        diag.debug(`${INSTRUMENTATION_NAME}: unpatch failed: ${error}`);
+      }
+    }
+    this.clientUndo.clear();
+    while (this.undo.length) {
+      const fn = this.undo.pop();
+      try {
+        fn?.();
+      } catch (error) {
+        diag.debug(`${INSTRUMENTATION_NAME}: unpatch failed: ${error}`);
+      }
+    }
+  }
+
+  /** Flush the provider's span processors. Does not shut the provider down. */
+  async forceFlush(): Promise<void> {
+    await flushProvider(this.tracerProvider ?? trace.getTracerProvider());
+  }
+
+  private tracingContext(): TurnTracingContext | undefined {
+    if (!this.enabled) return undefined;
+    const policy = this.contentPolicy;
+    const provider = this.tracerProvider ?? trace.getTracerProvider();
+    const tracer = new FITracer({
+      tracer: provider.getTracer(INSTRUMENTATION_NAME, VERSION),
+      traceConfig: { ...this.traceConfig, hideInputs: policy.hideInputs, hideOutputs: policy.hideOutputs, hideErrorDetails: policy.hideErrorDetails },
+    });
+    return { tracer, policy };
+  }
+}
+
+/** Python-style convenience constructor. */
+export function instrumentCodexSDK(
+  module: CodexModuleLike,
+  config: CodexSDKInstrumentationConfig = {},
+): CodexSDKInstrumentation {
+  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.
+ */
+export async function shutdown(tracerProvider?: TracerProvider): Promise<void> {
+  await flushProvider(tracerProvider ?? trace.getTracerProvider());
+}
+
+function resolveDelegate(provider: TracerProvider): TracerProvider {
+  const maybeProxy = provider as TracerProvider & {
+    getDelegate?: () => TracerProvider;
+    forceFlush?: () => Promise<void>;
+  };
+  if (typeof maybeProxy.forceFlush !== "function" && typeof maybeProxy.getDelegate === "function") {
+    return maybeProxy.getDelegate();
+  }
+  return provider;
+}
+
+async function flushProvider(provider: TracerProvider): Promise<void> {
+  const target = resolveDelegate(provider) as TracerProvider & { forceFlush?: () => Promise<void> };
+  if (typeof target.forceFlush !== "function") return;
+  try {
+    await target.forceFlush();
+  } catch (error) {
+    diag.warn(`${INSTRUMENTATION_NAME}: forceFlush failed: ${error}`);
+  }
+}