@traceai/codex-sdk 0.0.0-stage → 0.1.1

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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"}