@oxygen-agent/cli 1.936.1 → 1.982.3

package/node_modules/@oxygen/shared/dist/langfuse.js

@@ -21,11 +21,9 @@
 //   * Trace ids stay deterministic: sha256(seed) — same trace per turn/run, so
 //     lease-reclaim replays still converge onto ONE trace. See
 //     llmTraceIdForSeed.
-//   * Observation ids can NO LONGER be chosen. v5 observation ids are W3C span
-//     ids minted by OTel. The caller's stable id (`gen:<turn>:<n>`, `tool:…`)
-//     is preserved as metadata.oxygen_observation_id for correlation, but it no
-//     longer upserts: a replayed slice appends duplicate observations to the
-//     same trace instead of overwriting them.
+//   * A private OTel id generator emits one real deterministic root per seed.
+//     Child ids identify physical observations; oxygen_observation_id preserves
+//     the caller's logical identity without conflating repeated executions.
 //   * v5 is observations-first: correlating attributes (userId, sessionId,
 //     tags) must ride EVERY observation, not just the root, or per-session cost
 //     rollups miss the cost-bearing generations. They are applied through
@@ -34,7 +32,9 @@
 //   * Trace-level input/output is deprecated in v5. Overall IO goes on the ROOT
 //     observation instead; setTraceIO()/setActiveTraceIO() are deliberately not
 //     used here.
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
+import { OXYGEN_VERSION } from "./version.js";
+import { prepareLlmPayload } from "./llm-payload.js";
 import { log } from "./log.js";
 const FLUSH_TIMEOUT_MS = 5_000;
 const WARN_THROTTLE_MS = 30_000;
@@ -45,9 +45,7 @@ const WARN_THROTTLE_MS = 30_000;
  * meant every flush that ran long lost its spans instead of finishing late.
  */
 const LANGFUSE_EXPORT_TIMEOUT_SECONDS = 10;
-// Defensive per-field bound, well under Langfuse's ~1 MB event cap. Copilot
-// transcripts max out around 150 KB; anything larger is truncated with an
-// explicit marker rather than risking a rejected ingestion batch.
+// Scores are API strings; unlike observation payloads they cannot use chunks.
 const MAX_JSON_FIELD_CHARS = 400_000;
 /**
  * FAIL CLOSED: LLM tracing is on only when OXYGEN_LLM_TRACING_ENABLED is exactly
@@ -100,42 +98,13 @@ export function resolveLlmTracingEnvironment(env = process.env) {
 export function llmTraceIdForSeed(seed) {
     return createHash("sha256").update(seed, "utf8").digest("hex").slice(0, 32);
 }
-/**
- * Deterministic synthetic parent span id for one trace.
- *
- * v5 does not let a caller choose observation ids, and the worker emits a single
- * run's observations from different processes and slices — so there is no real
- * root span id to nest under. Every observation of a run instead attaches to
- * this stable pseudo-parent, which reproduces EXACTLY the flat shape the v3
- * adapter already produced (v3 passed only `traceId`, never
- * `parentObservationId`, so observations were already siblings of the trace).
- */
+/** The real root's stable W3C span id, also used across worker resumes. */
 function rootSpanIdForSeed(seed) {
     return createHash("sha256").update(`langfuse-root:${seed}`, "utf8").digest("hex").slice(0, 16);
 }
-// Bound one JSON-bearing field. Over the cap → an explicit truncation marker
-// (never a silently clipped payload that parses as complete).
-function boundJsonField(value) {
-    if (value === undefined || value === null)
-        return value;
-    let serialized;
-    try {
-        serialized = JSON.stringify(value) ?? "";
-    }
-    catch {
-        return { truncated: true, reason: "unserializable" };
-    }
-    if (serialized.length <= MAX_JSON_FIELD_CHARS)
-        return value;
-    return {
-        truncated: true,
-        chars: serialized.length,
-        preview: serialized.slice(0, MAX_JSON_FIELD_CHARS),
-    };
-}
 // A score's `comment` is free text (a thumbs-down reason is user-authored and
 // unbounded) and the API types it as a STRING, so it cannot take
-// boundJsonField's `{truncated, preview}` envelope. It gets the same
+// a recoverable payload envelope. It gets the same
 // MAX_JSON_FIELD_CHARS ceiling and the same "explicit marker, never a silent
 // clip" rule, with the marker counted INSIDE the cap so the bound holds.
 const COMMENT_TRUNCATION_MARKER = "…[truncated]";
@@ -149,13 +118,13 @@ function compact(body) {
     for (const [key, value] of Object.entries(body)) {
         if (value === undefined || value === null)
             continue;
-        out[key] = key === "input" || key === "output" ? boundJsonField(value) : value;
+        out[key] = value;
     }
     return out;
 }
-function boundedNever(rejectable, warn) {
+function boundedNever(rejectable, warn, timeoutMs = FLUSH_TIMEOUT_MS) {
     return new Promise((resolve) => {
-        const timer = setTimeout(resolve, FLUSH_TIMEOUT_MS);
+        const timer = setTimeout(resolve, timeoutMs);
         timer.unref?.();
         rejectable
             .catch((error) => warn(error))
@@ -165,52 +134,98 @@ function boundedNever(rejectable, warn) {
         });
     });
 }
-/**
- * The real v4 emitter. Everything OTel is loaded LAZILY, on first emission, so
- * a runtime with tracing disabled (the packed CLI, every test) never pays for
- * the OTel tree — matching the "inert unless enabled" doctrine the flag already
- * promises.
- */
+/** Lazy, private, always-sampled OTel transport. Never register it globally. */
 function createOtelEmitter(env, warn) {
     let handle = null;
     const init = () => {
         handle ??= (async () => {
             try {
-                const [{ LangfuseSpanProcessor }, { BasicTracerProvider }, tracing] = await Promise.all([
-                    import("@langfuse/otel"),
-                    import("@opentelemetry/sdk-trace-base"),
-                    import("@langfuse/tracing"),
+                const [{ LangfuseSpanProcessor }, { BasicTracerProvider, AlwaysOnSampler }, tracing, otel, core] = await Promise.all([
+                    import("@langfuse/otel"), import("@opentelemetry/sdk-trace-base"),
+                    import("@langfuse/tracing"), import("@opentelemetry/api"), import("@langfuse/core"),
                 ]);
                 const processor = new LangfuseSpanProcessor({
                     publicKey: env.LANGFUSE_PUBLIC_KEY,
                     secretKey: env.LANGFUSE_SECRET_KEY,
                     ...(env.LANGFUSE_BASE_URL?.trim() ? { baseUrl: env.LANGFUSE_BASE_URL.trim() } : {}),
                     environment: resolveLlmTracingEnvironment(env),
-                    // SECONDS, and the OTLP POST's own deadline. The SDK default is 5,
-                    // which is exactly FLUSH_TIMEOUT_MS — zero headroom, so a batch that
-                    // needed 6s was guaranteed to die on the transport and be dropped:
-                    // 37 `llm_tracing.ingest_failed` warns over 30 days to 2026-09-09,
-                    // every one stage='flush' / 'Request timed out', against 275,970
-                    // traces Langfuse accepted in the same window. 10s gives the POST
-                    // room without touching FLUSH_TIMEOUT_MS — boundedNever still
-                    // releases the caller at 5s, so a slow Langfuse can never hold a
-                    // worker tick.
+                    release: env.VERCEL_GIT_COMMIT_SHA || env.OXYGEN_GIT_SHA || OXYGEN_VERSION,
                     timeout: LANGFUSE_EXPORT_TIMEOUT_SECONDS,
+                    // SimpleSpanProcessor hits the exporter's concurrent-request limit
+                    // on large chunk bursts. Batch them, starting promptly; after() drains
+                    // the batch with a bound above the exporter's own deadline.
+                    exportMode: "batched",
+                    flushInterval: 1,
+                    flushAt: 128,
                 });
-                // PRIVATE provider. Deliberately NOT .register()ed — see the file
-                // header: the global provider carries the Axiom OTLP exporters, and a
-                // processor there would receive every prompt-bearing span.
-                //
-                // v5's smart default span filter needs no override here: this provider
-                // only ever creates spans through the Langfuse tracer, and
-                // `langfuse-sdk` spans are in the default allow-list.
-                const provider = new BasicTracerProvider({ spanProcessors: [processor] });
-                tracing.setLangfuseTracerProvider(provider);
-                return {
-                    processor,
-                    startObservation: tracing.startObservation,
-                    propagateAttributes: tracing.propagateAttributes,
+                let identity;
+                const provider = new BasicTracerProvider({
+                    spanProcessors: [{
+                            onStart: (span) => {
+                                // Directly pass the private parent claim to the processor. A
+                                // standalone process may have no global context manager at all;
+                                // context.with()/propagateAttributes alone would silently lose
+                                // the claim and user/session on every observation in that case.
+                                const parentContext = identity && !identity.isRoot
+                                    ? core.setLangfuseTraceIdInBaggage(otel.ROOT_CONTEXT, identity.traceId)
+                                    : otel.ROOT_CONTEXT;
+                                processor.onStart(span, parentContext);
+                                if (identity)
+                                    span.setAttributes(compact({
+                                        "user.id": identity.correlation.userId,
+                                        "session.id": identity.correlation.sessionId,
+                                        "langfuse.trace.name": identity.correlation.traceName,
+                                        "langfuse.trace.tags": identity.correlation.tags,
+                                    }));
+                            },
+                            onEnd: (span) => processor.onEnd(span),
+                            forceFlush: () => processor.forceFlush(),
+                            shutdown: () => processor.shutdown(),
+                        }], sampler: new AlwaysOnSampler(),
+                    idGenerator: {
+                        generateTraceId: () => identity?.traceId ?? randomBytes(16).toString("hex"),
+                        generateSpanId: () => identity?.spanId ?? randomBytes(8).toString("hex"),
+                    },
+                });
+                // Only used to avoid repeatedly creating provisional roots in this
+                // process. A final root emission always updates the same physical id.
+                const roots = new Set();
+                const emit = (emission) => {
+                    const traceId = llmTraceIdForSeed(emission.traceSeed);
+                    const rootId = rootSpanIdForSeed(emission.traceSeed);
+                    if (!emission.isRoot && !roots.has(traceId)) {
+                        emit({
+                            kind: "span", traceSeed: emission.traceSeed, isRoot: true,
+                            observationId: rootId, name: emission.correlation.traceName ?? emission.name.split(".")[0] + ".run",
+                            attributes: { version: OXYGEN_VERSION, metadata: { oxygen_trace_root: true, oxygen_trace_seed: emission.traceSeed, oxygen_capture_version: 2 } },
+                            correlation: emission.correlation, startTime: emission.startTime, endTime: emission.startTime,
+                        });
+                    }
+                    if (emission.isRoot) {
+                        roots.add(traceId);
+                        if (roots.size > 4096)
+                            roots.delete(roots.values().next().value);
+                    }
+                    // SDK configuration is module-local, whereas Next bundles and tests
+                    // may construct more than one private client. Select THIS provider
+                    // immediately before the synchronous creation; never use global OTel.
+                    tracing.setLangfuseTracerProvider(provider);
+                    identity = { traceId, spanId: emission.observationId ?? randomBytes(8).toString("hex"), isRoot: emission.isRoot === true, correlation: emission.correlation };
+                    try {
+                        otel.context.with(emission.isRoot ? otel.ROOT_CONTEXT : core.setLangfuseTraceIdInBaggage(otel.ROOT_CONTEXT, traceId), () => tracing.propagateAttributes(emission.correlation, () => {
+                            const observation = tracing.startObservation(emission.name, emission.attributes, {
+                                asType: emission.kind, startTime: emission.startTime,
+                                ...(emission.isRoot ? {} : { parentSpanContext: { traceId, spanId: emission.parentObservationId ?? rootId, traceFlags: 1 } }),
+                            });
+                            if (emission.kind !== "event")
+                                observation.end(emission.endTime);
+                        }));
+                    }
+                    finally {
+                        identity = undefined;
+                    }
                 };
+                return { processor, emit };
             }
             catch (error) {
                 warn(error, { stage: "init" });
@@ -220,33 +235,7 @@ function createOtelEmitter(env, warn) {
         return handle;
     };
     return {
-        emit: (emission) => {
-            void init()
-                .then((h) => {
-                if (!h)
-                    return;
-                const traceId = llmTraceIdForSeed(emission.traceSeed);
-                // propagateAttributes is scope-based in v5: the observation must be
-                // created INSIDE the callback to inherit userId/sessionId/tags.
-                h.propagateAttributes(emission.correlation, () => {
-                    // The kind is a union, so no single overload matches it. Every
-                    // overload returns an observation extending the same base, and the
-                    // only method used here is .end() — so resolving against the span
-                    // overload is safe while the real kind is passed at runtime.
-                    const observation = h.startObservation(emission.name, emission.attributes, {
-                        asType: emission.kind,
-                        startTime: emission.startTime,
-                        parentSpanContext: {
-                            traceId,
-                            spanId: rootSpanIdForSeed(emission.traceSeed),
-                            traceFlags: 1,
-                        },
-                    });
-                    observation.end(emission.endTime);
-                });
-            })
-                .catch((error) => warn(error, { stage: emission.kind }));
-        },
+        emit: (emission) => { void init().then((h) => h?.emit(emission)).catch((error) => warn(error, { stage: emission.kind })); },
         flush: () => init().then((h) => h?.processor.forceFlush() ?? Promise.resolve()),
         shutdown: () => init().then((h) => h?.processor.shutdown() ?? Promise.resolve()),
     };
@@ -330,7 +319,52 @@ export function createLlmTracingClient(env = process.env, options) {
             ...context,
         });
     };
-    const emitter = options?.emitterImpl ?? createOtelEmitter(env, warn);
+    const transport = options?.emitterImpl ?? createOtelEmitter(env, warn);
+    const emitter = {
+        ...transport,
+        emit: (emission) => {
+            const observationId = emission.observationId ?? randomBytes(8).toString("hex");
+            const metadata = { ...emission.attributes.metadata, oxygen_capture_version: 2 };
+            const attributes = { ...emission.attributes, version: OXYGEN_VERSION, metadata };
+            const chunkEmissions = [];
+            const capture = (value, field, key) => {
+                const prepared = prepareLlmPayload(value, key);
+                for (const chunk of prepared.chunks) {
+                    chunkEmissions.push({
+                        kind: "event", traceSeed: emission.traceSeed, name: "llm.payload_chunk", parentObservationId: observationId,
+                        attributes: { version: OXYGEN_VERSION, input: chunk, metadata: {
+                                oxygen_capture_version: 2, oxygen_payload_id: chunk.payload_id,
+                                oxygen_payload_chunk_index: chunk.index, oxygen_payload_chunk_count: prepared.chunks.length,
+                                oxygen_observation_id: `${metadata.oxygen_observation_id ?? observationId}:payload:${field}:${chunk.index}`,
+                            } },
+                        correlation: emission.correlation, startTime: emission.endTime ?? emission.startTime, endTime: emission.endTime ?? emission.startTime,
+                    });
+                }
+                return prepared.value;
+            };
+            for (const key of ["input", "output", "modelParameters"]) {
+                if (key in attributes)
+                    attributes[key] = capture(attributes[key], key);
+            }
+            if (typeof attributes.statusMessage === "string") {
+                const status = prepareLlmPayload(attributes.statusMessage);
+                if (typeof status.value === "string" && status.value.length <= 2000)
+                    attributes.statusMessage = status.value;
+                else {
+                    metadata.status_message = attributes.statusMessage;
+                    attributes.statusMessage = "See metadata.status_message for full error detail";
+                }
+            }
+            for (const [key, value] of Object.entries(metadata))
+                metadata[key] = capture(value, `metadata.${key}`, key);
+            if (attributes.modelParameters && typeof attributes.modelParameters === "object") {
+                attributes.modelParameters = Object.fromEntries(Object.entries(attributes.modelParameters).map(([key, value]) => [key, typeof value === "number" || typeof value === "string" ? value : JSON.stringify(value)]));
+            }
+            transport.emit({ ...emission, observationId, attributes });
+            for (const chunk of chunkEmissions)
+                transport.emit(chunk);
+        },
+    };
     const scorer = options?.scorerImpl ?? createApiScorer(env, warn);
     const guarded = (fn, stage) => {
         try {
@@ -360,19 +394,44 @@ export function createLlmTracingClient(env = process.env, options) {
             tags: input.tags,
         });
     };
+    const modelObservation = (body, kind) => guarded(() => {
+        emitter.emit({
+            kind,
+            traceSeed: body.traceId,
+            name: body.name,
+            attributes: compact({
+                input: body.input,
+                output: body.output,
+                level: body.level,
+                statusMessage: body.statusMessage,
+                model: body.model,
+                modelParameters: body.modelParameters,
+                completionStartTime: body.completionStartTime,
+                usageDetails: body.usageDetails,
+                costDetails: body.costDetails,
+                metadata: { ...(body.metadata ?? {}), oxygen_observation_id: body.id },
+            }),
+            // The cost-bearing observation: v5 session cost only rolls up when
+            // the generation itself carries the session.
+            correlation: correlate({ sessionId: body.sessionId, userId: body.userId }),
+            startTime: body.startTime ?? new Date(),
+            ...(body.endTime ? { endTime: body.endTime } : {}),
+        });
+    }, kind);
     return {
         trace: (body) => guarded(() => {
             const startTime = body.startTime ?? new Date();
             emitter.emit({
                 kind: "span",
                 traceSeed: body.id,
+                observationId: rootSpanIdForSeed(body.id), isRoot: true,
                 name: body.name,
                 // Overall trace IO lives on this ROOT observation — v5 deprecates
                 // trace-level input/output, so it is deliberately not set separately.
                 attributes: compact({
                     input: body.input,
                     output: body.output,
-                    metadata: { ...(body.metadata ?? {}), oxygen_observation_id: body.id },
+                    metadata: { ...(body.metadata ?? {}), oxygen_observation_id: body.id, oxygen_trace_root: true, oxygen_trace_seed: body.id },
                 }),
                 correlation: correlate({
                     traceName: body.name,
@@ -383,6 +442,15 @@ export function createLlmTracingClient(env = process.env, options) {
                 startTime,
                 endTime: body.endTime ?? startTime,
             });
+            if (body.metadata?.observation_scope === "execution_slice") {
+                const sliceStart = typeof body.metadata.slice_started_at === "string" ? new Date(body.metadata.slice_started_at) : startTime;
+                emitter.emit({
+                    kind: "span", traceSeed: body.id, name: `${body.name}.slice`,
+                    attributes: compact({ input: body.input, output: body.output, metadata: { ...body.metadata, oxygen_observation_id: `${body.id}:slice:${body.metadata.slice_id}` } }),
+                    correlation: correlate({ sessionId: body.sessionId, userId: body.userId }),
+                    startTime: Number.isFinite(sliceStart.getTime()) ? sliceStart : startTime, endTime: body.endTime ?? startTime,
+                });
+            }
         }, "trace"),
         span: (body) => guarded(() => {
             emitter.emit({
@@ -401,29 +469,8 @@ export function createLlmTracingClient(env = process.env, options) {
                 ...(body.endTime ? { endTime: body.endTime } : {}),
             });
         }, "span"),
-        generation: (body) => guarded(() => {
-            emitter.emit({
-                kind: "generation",
-                traceSeed: body.traceId,
-                name: body.name,
-                attributes: compact({
-                    input: body.input,
-                    output: body.output,
-                    level: body.level,
-                    statusMessage: body.statusMessage,
-                    model: body.model,
-                    completionStartTime: body.completionStartTime,
-                    usageDetails: body.usageDetails,
-                    costDetails: body.costDetails,
-                    metadata: { ...(body.metadata ?? {}), oxygen_observation_id: body.id },
-                }),
-                // The cost-bearing observation: v5 session cost only rolls up when
-                // the generation itself carries the session.
-                correlation: correlate({ sessionId: body.sessionId, userId: body.userId }),
-                startTime: body.startTime ?? new Date(),
-                ...(body.endTime ? { endTime: body.endTime } : {}),
-            });
-        }, "generation"),
+        generation: (body) => modelObservation(body, "generation"),
+        embedding: (body) => modelObservation(body, "embedding"),
         event: (body) => guarded(() => {
             const startTime = body.startTime ?? new Date();
             emitter.emit({
@@ -452,10 +499,10 @@ export function createLlmTracingClient(env = process.env, options) {
             }
         },
         // The "never rejects, bounded at ~5s" contract is the CLIENT's, so it is
-        // enforced here rather than inside one emitter — an emitter that throws
+        // enforced here (15s for serverless after()) rather than inside one emitter — an emitter that throws
         // synchronously or rejects must still not escape into product code.
-        flush: () => boundedNever((async () => emitter.flush())(), (error) => warn(error, { stage: "flush" })),
-        shutdown: () => boundedNever((async () => emitter.shutdown())(), (error) => warn(error, { stage: "shutdown" })),
+        flush: () => boundedNever((async () => emitter.flush())(), (error) => warn(error, { stage: "flush" }), env.VERCEL ? 15_000 : FLUSH_TIMEOUT_MS),
+        shutdown: () => boundedNever((async () => emitter.shutdown())(), (error) => warn(error, { stage: "shutdown" }), env.VERCEL ? 15_000 : FLUSH_TIMEOUT_MS),
     };
 }
 // --- Process-wide singleton (both runtimes construct at most one client) ------

package/node_modules/@oxygen/shared/dist/llm-payload.d.ts

@@ -0,0 +1,10 @@
+export type LlmPayloadChunk = {
+    payload_id: string;
+    index: number;
+    data: string;
+};
+/** Only credentials are masked: prompts, tool arguments and token counts stay. */
+export declare function prepareLlmPayload(value: unknown, fieldKey?: string): {
+    value: unknown;
+    chunks: LlmPayloadChunk[];
+};

package/node_modules/@oxygen/shared/dist/llm-payload.js

@@ -0,0 +1,54 @@
+import { createHash } from "node:crypto";
+import { redactSecretsInString } from "./redaction.js";
+// Bound individual OTLP fields in UTF-8 bytes. Large payloads remain fully
+// recoverable in child events rather than losing the end of a model response.
+const INLINE_BYTES = 128 * 1024;
+const CHUNK_BYTES = 64 * 1024;
+const SECRET_KEY = /^(?:authorization|proxy-authorization|cookie|set-cookie|password|passwd|secret|(?:x[-_]?)?api[-_]?key|x[-_]?auth[-_]?token|access[-_]?token|refresh[-_]?token|client[-_]?secret|private[-_]?key|connection[-_]?uri|database[-_]?url)$/i;
+const SECRET_QUERY = /([?&](?:token|access_token|api_key|key|signature|x-amz-signature|x-goog-signature)=)[^&#\s"]+/gi;
+/** Only credentials are masked: prompts, tool arguments and token counts stay. */
+export function prepareLlmPayload(value, fieldKey = "") {
+    if (SECRET_KEY.test(fieldKey))
+        value = "[REDACTED]";
+    if (value === undefined || value === null)
+        return { value, chunks: [] };
+    let serialized;
+    try {
+        // Tool arguments and SSE frames are often JSON encoded inside a string.
+        // Inspect those nested documents too; redacting only outer object keys
+        // would leave an API key inside tool_calls[].function.arguments intact.
+        const serialize = (input, nestedDepth = 0) => JSON.stringify(input, (key, item) => {
+            if (SECRET_KEY.test(key))
+                return "[REDACTED]";
+            if (typeof item !== "string")
+                return item;
+            let text = redactSecretsInString(item).replace(SECRET_QUERY, "$1[REDACTED]");
+            if (/^\s*[\[{]/.test(text)) {
+                try {
+                    const parsed = JSON.parse(text);
+                    if (nestedDepth >= 32)
+                        return "[REDACTED_NESTED_JSON_DEPTH]";
+                    text = serialize(parsed, nestedDepth + 1);
+                }
+                catch { /* ordinary prompt text, not a JSON document */ }
+            }
+            return text;
+        }) ?? "null";
+        serialized = serialize(value);
+    }
+    catch {
+        return { value: { truncated: true, reason: "unserializable" }, chunks: [] };
+    }
+    const bytes = Buffer.from(serialized, "utf8");
+    if (bytes.length <= INLINE_BYTES)
+        return { value: JSON.parse(serialized), chunks: [] };
+    const id = createHash("sha256").update(bytes).digest("hex");
+    const chunks = [];
+    for (let offset = 0; offset < bytes.length; offset += CHUNK_BYTES) {
+        chunks.push({ payload_id: id, index: chunks.length, data: bytes.subarray(offset, offset + CHUNK_BYTES).toString("base64") });
+    }
+    return {
+        value: { oxygen_payload: { id, encoding: "base64-json-utf8", bytes: bytes.length, chunks: chunks.length, sha256: id } },
+        chunks,
+    };
+}

package/node_modules/@oxygen/shared/dist/llm-usage.d.ts

@@ -0,0 +1,11 @@
+/** Inclusive provider counts. Keep the original provider usage on the observation's metadata. */
+export type LlmProviderUsage = {
+    promptTokens?: number | null | undefined;
+    completionTokens?: number | null | undefined;
+    reasoningTokens?: number | null | undefined;
+    cachedPromptTokens?: number | null | undefined;
+    cacheWriteTokens?: number | null | undefined;
+    totalTokens?: number | null | undefined;
+};
+/** Langfuse usage keys are mutually exclusive buckets, not inclusive breakdowns. */
+export declare function normalizeLlmUsageDetails(usage: LlmProviderUsage | null | undefined): Record<string, number> | undefined;

package/node_modules/@oxygen/shared/dist/llm-usage.js

@@ -0,0 +1,30 @@
+/** Langfuse usage keys are mutually exclusive buckets, not inclusive breakdowns. */
+export function normalizeLlmUsageDetails(usage) {
+    if (!usage)
+        return undefined;
+    const count = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0 ? Math.floor(n) : undefined;
+    const input = count(usage.promptTokens);
+    const output = count(usage.completionTokens);
+    const details = {};
+    if (input !== undefined) {
+        const cached = Math.min(input, count(usage.cachedPromptTokens) ?? 0);
+        const created = Math.min(input - cached, count(usage.cacheWriteTokens) ?? 0);
+        details.input = input - cached - created;
+        if (cached > 0)
+            details.input_cached_tokens = cached;
+        if (created > 0)
+            details.input_cache_creation_tokens = created;
+    }
+    if (output !== undefined) {
+        // Some providers return a detail count larger than its inclusive parent.
+        // Preserve the parent total rather than inventing extra billed tokens.
+        const reasoning = Math.min(output, count(usage.reasoningTokens) ?? 0);
+        details.output = output - reasoning;
+        if (reasoning > 0)
+            details.output_reasoning_tokens = reasoning;
+    }
+    const total = input !== undefined && output !== undefined ? input + output : count(usage.totalTokens);
+    if (total !== undefined)
+        details.total = total;
+    return Object.keys(details).length > 0 ? details : undefined;
+}

package/node_modules/@oxygen/shared/dist/mailbox-import.d.ts

@@ -8,6 +8,16 @@ export type NormalizedMailboxImportRow = {
     infrastructure_platform?: "google_workspace" | "microsoft_365" | "microsoft_azure";
     tenant_id?: string;
     app_password?: string;
+    /**
+     * WHO the inbox sends as (v1.954.0 — an inbox always belongs to a sender).
+     * Non-secret identity, so it rides the same whitelist as the address: a vendor
+     * export that already knows the person spares the customer a guessed profile
+     * named from the address local part.
+     */
+    first_name?: string;
+    last_name?: string;
+    display_name?: string;
+    sender_profile_id?: string;
 };
 export type MailboxImportValidationSummary = {
     valid: true;

package/node_modules/@oxygen/shared/dist/mailbox-import.js

@@ -49,6 +49,27 @@ const MAILBOX_TENANT_HEADERS = new Set([
     "microsofttenantid",
     "tenantid",
 ]);
+const MAILBOX_FIRST_NAME_HEADERS = new Set([
+    "first",
+    "firstname",
+    "givenname",
+]);
+const MAILBOX_LAST_NAME_HEADERS = new Set([
+    "familyname",
+    "last",
+    "lastname",
+    "surname",
+]);
+const MAILBOX_DISPLAY_NAME_HEADERS = new Set([
+    "displayname",
+    "fromname",
+    "name",
+    "sendername",
+]);
+const MAILBOX_SENDER_PROFILE_HEADERS = new Set([
+    "senderprofile",
+    "senderprofileid",
+]);
 const MAILBOX_NON_TRANSFERABLE_SECRET_HEADERS = new Set([
     "accesstoken",
     "applicationsecret",
@@ -328,6 +349,17 @@ function normalizeMailboxExportRow(row, index, mode) {
             ? "microsoft_azure"
             : null);
     const infrastructurePlatform = normalizeMailboxInfrastructurePlatform(infrastructurePlatformRaw, provider, index);
+    // WHO the inbox sends as. Carried through because an inbox always belongs to a
+    // sender (v1.954.0): a file that already names the person is the difference
+    // between a real sender profile and one OXYGEN guesses from the address.
+    const firstName = readMailboxIdentityName(byHeader, MAILBOX_FIRST_NAME_HEADERS, index, "first_name");
+    const lastName = readMailboxIdentityName(byHeader, MAILBOX_LAST_NAME_HEADERS, index, "last_name");
+    const displayName = readMailboxIdentityName(byHeader, MAILBOX_DISPLAY_NAME_HEADERS, index, "display_name");
+    const senderProfileId = readUniqueMailboxExportString(byHeader, MAILBOX_SENDER_PROFILE_HEADERS, index, "sender_profile_id", (value) => value.trim().toLowerCase());
+    if (senderProfileId &&
+        !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(senderProfileId)) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}].sender_profile_id must be a sender profile id (UUID). List them with \`oxygen senders profiles list\`, or drop the column and let the row's first/last name name the sender.`, { exitCode: 1 });
+    }
     return {
         email_address: email.trim().toLowerCase(),
         provider,
@@ -338,6 +370,10 @@ function normalizeMailboxExportRow(row, index, mode) {
             ? { infrastructure_platform: infrastructurePlatform }
             : {}),
         ...(tenantId ? { tenant_id: tenantId.trim().toLowerCase() } : {}),
+        ...(firstName ? { first_name: firstName } : {}),
+        ...(lastName ? { last_name: lastName } : {}),
+        ...(displayName ? { display_name: displayName } : {}),
+        ...(senderProfileId ? { sender_profile_id: senderProfileId } : {}),
         ...(mode === "credential" &&
             provider === "google" &&
             distinctPasswords[0] !== undefined
@@ -345,6 +381,23 @@ function normalizeMailboxExportRow(row, index, mode) {
             : {}),
     };
 }
+/**
+ * One identity half off an export row. Header-bound (the From name rides an SMTP
+ * header), so a CR/LF is refused by field name rather than silently stripped — the
+ * caller is usually holding hundreds of rows and needs to know which one.
+ */
+function readMailboxIdentityName(byHeader, headers, index, field) {
+    const value = readUniqueMailboxExportString(byHeader, headers, index, field, (raw) => raw.trim());
+    if (!value)
+        return null;
+    if (value.length > 200) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}].${field} must be at most 200 characters.`, { exitCode: 1 });
+    }
+    if (/[\r\n]/.test(value)) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}].${field} must be a single line.`, { exitCode: 1 });
+    }
+    return value;
+}
 function normalizeMailboxExportHeader(value) {
     return value
         .replace(/^\uFEFF/, "")

package/node_modules/@oxygen/shared/dist/plan-limits.d.ts

@@ -78,6 +78,14 @@ export type PlanLimits = {
  */
 export declare const TABLE_IMPORT_ROW_LIMIT: 3000000;
 export { VERCEL_REQUEST_BODY_LIMIT_BYTES } from "./import-limits.js";
+/**
+ * OXYGEN's own JSON-body ceiling for every `/api/cli/*` route (enforced by
+ * `assertCliJsonBodyWithinLimit` on the content-length header). Shared so the CLI
+ * pre-splits a row batch by measured bytes instead of learning the number from a
+ * 413. Must stay below VERCEL_REQUEST_BODY_LIMIT_BYTES, and must never be raised
+ * in the CLI alone — an older server would still 413 at the old number.
+ */
+export declare const MAX_CLI_JSON_BODY_BYTES = 2000000;
 /**
  * The per-rung limit matrix. `ai_live` deliberately equals `tool_live` at every
  * rung — one "live actions" mental model; the per-call cost asymmetry between