@oxygen-agent/cli 1.922.14 → 1.948.1

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,13 +32,20 @@
 //   * 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;
-// 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.
+/**
+ * The OTLP exporter's own deadline, in SECONDS (the @langfuse/otel option's
+ * unit). Deliberately ABOVE FLUSH_TIMEOUT_MS: our bound protects the caller,
+ * this one protects the batch, and making them equal — the SDK's 5s default —
+ * meant every flush that ran long lost its spans instead of finishing late.
+ */
+const LANGFUSE_EXPORT_TIMEOUT_SECONDS = 10;
+// 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
@@ -93,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]";
@@ -142,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))
@@ -158,42 +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),
+                    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,
+                });
+                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"),
+                    },
                 });
-                // 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,
+                // 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" });
@@ -203,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()),
     };
@@ -313,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 {
@@ -343,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,
@@ -366,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({
@@ -384,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({
@@ -435,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/object-storage.d.ts

@@ -1,4 +1,10 @@
+import { S3Client } from "@aws-sdk/client-s3";
 export declare function isObjectStorageConfigured(): boolean;
+/** Server-only storage adapter seam. Callers own tenant and object-policy checks. */
+export declare function resolveObjectStorageClient(): {
+    client: S3Client;
+    bucket: string;
+};
 export declare function buildImportObjectKey(input: {
     organizationId: string;
     fileName?: string | null;

package/node_modules/@oxygen/shared/dist/object-storage.js

@@ -77,6 +77,11 @@ function resolveClient() {
 }
 // Keys are namespaced by org so a tenant can only ever be handed (and the
 // enqueue route only accepts) keys under its own prefix.
+/** Server-only storage adapter seam. Callers own tenant and object-policy checks. */
+export function resolveObjectStorageClient() {
+    const { client, config } = resolveClient();
+    return { client, bucket: config.bucket };
+}
 export function buildImportObjectKey(input) {
     const safeName = sanitizeFileName(input.fileName) || "import";
     return `imports/${input.organizationId}/${randomUUID()}/${safeName}`;

package/node_modules/@oxygen/shared/dist/product-analytics-core.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Product-analytics core — the TRANSPORT-FREE half of PostHog emission.
+ *
+ * Two runtimes emit product events: the web/API runtime (`apps/web/src/lib/
+ * product-analytics.ts`, `posthog-node` on Vercel) and the Fly worker
+ * (`apps/worker/src/product-analytics.ts`, `posthog-node` batching). What they
+ * must agree on lives here, once: property sanitization, the distinct-id
+ * chain, the person-profile posture, org grouping, and the runtime dimensions
+ * every event carries. Two copies of that logic drifted in the past — the
+ * worker would have minted a throwaway person per request while the web side
+ * did not — and PostHog cannot join what the emitters disagree about.
+ *
+ * Deliberately NO `posthog-node`, no fetch, no I/O: `packages/shared` is
+ * vendored into the published `@oxygen-agent/cli` tarball, so every runtime
+ * dependency added here lands on every customer's machine
+ * (`scripts/cli-package-dependencies.mjs`, the langfuse-class guard). The
+ * capture message is a plain object structurally compatible with
+ * `posthog-node`'s `EventMessage`; each runtime owns its own client.
+ */
+export declare const PRODUCT_ANALYTICS_MAX_PROPERTY_KEY_LENGTH = 80;
+export declare const PRODUCT_ANALYTICS_MAX_PROPERTY_STRING_LENGTH = 500;
+/**
+ * Byte ceiling for a structured (object/array) property value.
+ *
+ * Structured values pass through UNTOUCHED — see `sanitizeStructuredValue` — so
+ * this is the only thing standing between a careless caller and an unbounded
+ * ingest payload. Set well above `MCP_PAYLOAD_LIMITS.maxSerializedBytes` (8 KiB,
+ * in apps/web `analytics/mcp-analytics.ts`) so it can never re-cut a payload
+ * that module already bounded and marked; it exists for the callers that bound
+ * nothing.
+ */
+export declare const PRODUCT_ANALYTICS_MAX_STRUCTURED_PROPERTY_BYTES = 32768;
+/**
+ * A JSON value PostHog can index as a structured property.
+ *
+ * PostHog's reserved MCP-Analytics properties (`$mcp_parameters`,
+ * `$mcp_response`, `$mcp_listed_tool_names`) are objects and arrays by vendor
+ * contract, so a scalar-only property type made the entire `$mcp_*` surface
+ * untransmittable: a `.slice(...)` on an array is a `TypeError`, and that throw
+ * escaped `trackProductEvent` — losing the whole event, not just the property.
+ */
+export type ProductAnalyticsJsonValue = string | number | boolean | null | readonly ProductAnalyticsJsonValue[] | {
+    readonly [key: string]: ProductAnalyticsJsonValue;
+};
+export type ProductAnalyticsValue = ProductAnalyticsJsonValue | undefined;
+/** What `sanitizeProductAnalyticsProperties` is allowed to hand the SDK. */
+export type ProductAnalyticsSanitizedValue = string | number | boolean | null | ProductAnalyticsJsonValue;
+export type ProductAnalyticsProperties = Record<string, ProductAnalyticsValue>;
+export type ProductAnalyticsEventInput = {
+    event: string;
+    distinctId?: string | null | undefined;
+    organizationId?: string | null | undefined;
+    userId?: string | null | undefined;
+    properties?: ProductAnalyticsProperties;
+    /**
+     * Ingestion id. PostHog dedupes on it, so a revenue event replayed from a
+     * Stripe webhook redelivery — or a run outcome re-read after a worker
+     * restart — lands once instead of double-counting. Supply a value derived
+     * from the source fact (the KPI event key, the run id), never a random one,
+     * or replay stops being deterministic.
+     */
+    uuid?: string | null | undefined;
+    /** When the fact happened, if that is not "now" (webhook replay, backfill, run settle). */
+    timestamp?: Date | null | undefined;
+};
+/**
+ * The message shape both `posthog-node` capture paths accept. Declared here so
+ * the builder needs no `posthog-node` import; the web/worker clients pass it
+ * straight to `capture` / `captureImmediate`.
+ */
+export type ProductAnalyticsCaptureMessage = {
+    distinctId: string;
+    event: string;
+    properties: Record<string, ProductAnalyticsSanitizedValue>;
+    groups?: Record<string, string>;
+    uuid?: string;
+    timestamp?: Date;
+};
+/**
+ * What the emitting runtime knows about itself. `environment` is the
+ * PROD/MAIN/DEV/LOCAL dimension every insight filters on
+ * (`resolveProductAnalyticsEnvironmentFromEnv`); `runtimeProperties` are the
+ * runtime-specific facts (Vercel env/sha/region on the web, Fly app/region on
+ * the worker) and are set BEFORE the caller's properties so a caller can
+ * override them but never lose them by accident.
+ */
+export type ProductAnalyticsRuntimeContext = {
+    environment: string;
+    oxygenVersion: string;
+    runtimeProperties?: ProductAnalyticsProperties;
+};
+export declare function sanitizeProductAnalyticsProperties(properties: ProductAnalyticsProperties): Record<string, ProductAnalyticsSanitizedValue>;
+export declare function normalizeProductAnalyticsIdentifier(value: ProductAnalyticsValue): string | null;
+/**
+ * Build the capture message every runtime sends. Returns null when no distinct
+ * id can be derived — an event with no subject is dropped, never invented.
+ */
+export declare function buildProductAnalyticsCaptureMessage(input: ProductAnalyticsEventInput, context: ProductAnalyticsRuntimeContext): ProductAnalyticsCaptureMessage | null;