@oxygen-agent/cli 1.894.0 → 1.917.5

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

@@ -24,6 +24,7 @@ export * from "./crm-activity-events.js";
 export * from "./column-types.js";
 export * from "./copilot-errors.js";
 export * from "./copilot-journeys.js";
+export * from "./copilot-plan.js";
 export * from "./credit-guidance.js";
 export * from "./directory.js";
 export * from "./email-tracking-token.js";
@@ -49,6 +50,7 @@ export * from "./member-columns.js";
 export * from "./microsoft-consent-url.js";
 export * from "./networks.js";
 export * from "./person-name.js";
+export * from "./product-doctrine.js";
 export * from "./recipes.js";
 export * from "./sequence-template.js";
 export * from "./sequence-crm-events.js";
@@ -86,6 +88,7 @@ export * from "./postgres-text.js";
 export * from "./tags.js";
 export * from "./telemetry.js";
 export * from "./tenant-database-secret.js";
+export * from "./egress-transport-readiness.js";
 export * from "./timing.js";
 export * from "./type-guards.js";
 export * from "./worker-failures-queue.js";

package/node_modules/@oxygen/shared/dist/langfuse.d.ts

@@ -1,4 +1,3 @@
-import { Langfuse } from "langfuse";
 type EnvMap = Record<string, string | undefined>;
 export type LlmObservationLevel = "DEBUG" | "DEFAULT" | "WARNING" | "ERROR";
 export type LlmTraceBody = {
@@ -10,6 +9,13 @@ export type LlmTraceBody = {
     output?: unknown;
     metadata?: Record<string, unknown>;
     tags?: string[];
+    /**
+     * Root-observation span. v3 emitted a durationless trace object; v5's root IS
+     * an observation, so a root emitted once at completion should carry the real
+     * turn/run window. Defaults to "now" for both when omitted.
+     */
+    startTime?: Date;
+    endTime?: Date;
 };
 export type LlmSpanBody = {
     id: string;
@@ -22,6 +28,14 @@ export type LlmSpanBody = {
     endTime?: Date;
     level?: LlmObservationLevel;
     statusMessage?: string | null;
+    /**
+     * v5 observations-first correlation. Pass the SAME sessionId/userId the trace
+     * carries: in v5 these live on every observation, and session-level cost only
+     * adds up if the cost-bearing generations carry the session too. Optional so
+     * an emitter that has no session still traces.
+     */
+    sessionId?: string | null;
+    userId?: string | null;
 };
 export type LlmGenerationBody = LlmSpanBody & {
     model?: string | null;
@@ -36,12 +50,46 @@ export type LlmEventBody = {
     input?: unknown;
     metadata?: Record<string, unknown>;
     startTime?: Date;
+    /** See LlmSpanBody.sessionId. */
+    sessionId?: string | null;
+    userId?: string | null;
+};
+/**
+ * An eval/annotation attached to a trace (ADR 0014 files these as exactly what
+ * the LLM store exists to enable). Narrower than the API's CreateScoreRequest on
+ * purpose: `traceId` is REQUIRED (a score orphaned from its trace is unreadable
+ * in the UI), `value` is numeric-only, and `dataType` drops "CATEGORICAL"
+ * because that variant requires a *string* value. Widening later stays additive.
+ */
+export type LlmScoreBody = {
+    /** Deterministic id upserts; omit for a new score each call. */
+    id?: string;
+    traceId: string;
+    name: string;
+    value: number;
+    dataType?: "BOOLEAN" | "NUMERIC";
+    comment?: string;
 };
 export type LlmTracingClient = {
     trace(body: LlmTraceBody): void;
     span(body: LlmSpanBody): void;
     generation(body: LlmGenerationBody): void;
     event(body: LlmEventBody): void;
+    /**
+     * Attach a score to an existing trace.
+     *
+     * ASYNC, unlike the four above, because it is not the same transport. Spans go
+     * through the OTel processor, which batches and is drained by `flush()`; a
+     * score has no span, so it is one HTTP call to the scores API. Awaiting it is
+     * what keeps it alive on a serverless function that freezes the moment the
+     * handler returns — there is nothing for `flush()` to drain on its behalf.
+     *
+     * Never rejects: resolves `true` when the score was accepted, `false` when it
+     * was not (transport down, tracing misconfigured, API refusal). Fail-open like
+     * every other path here — telemetry must not break the product write it
+     * describes.
+     */
+    score(body: LlmScoreBody): Promise<boolean>;
     /** Never rejects; bounded at ~5s. */
     flush(): Promise<void>;
     /** Flush + stop background timers. Never rejects; bounded at ~5s. */
@@ -53,16 +101,56 @@ export type LlmTracingClient = {
  */
 export declare function isLlmTracingEnabled(env?: EnvMap): boolean;
 export declare function resolveLlmTracingEnvironment(env?: EnvMap): string;
-type LangfuseLike = Pick<Langfuse, "trace" | "span" | "generation" | "event" | "flushAsync" | "shutdownAsync"> & {
-    on?: (event: string, listener: (...args: unknown[]) => void) => void;
+/**
+ * Deterministic Langfuse trace id for an external seed (copilot turn id, agent
+ * run id, AI-column run id).
+ *
+ * Byte-identical to `createTraceId(seed)` from @langfuse/tracing — sha256 of the
+ * UTF-8 seed, first 32 hex chars — but SYNCHRONOUS. The official helper returns
+ * a Promise (it uses WebCrypto), and every cross-link site here writes the id on
+ * a hot, synchronous path: the tenant ledger's `turn_started` payload and the
+ * Axiom `copilot.turn.finished` rollup both carry `langfuse_trace_id`, and a
+ * tracer's `traceId` is read synchronously. langfuse.test.ts pins this against
+ * the SDK's own implementation so the two can never drift.
+ */
+export declare function llmTraceIdForSeed(seed: string): string;
+export type LlmEmissionKind = "span" | "generation" | "event";
+/** v5 correlating attributes, propagated onto the emitted observation. */
+export type LlmCorrelation = {
+    traceName?: string;
+    userId?: string;
+    sessionId?: string;
+    tags?: string[];
+};
+export type LlmEmission = {
+    kind: LlmEmissionKind;
+    /** External seed (turn/run id) — hashed into the W3C trace id. */
+    traceSeed: string;
+    name: string;
+    /** Observation-level attributes, already compacted/bounded. */
+    attributes: Record<string, unknown>;
+    /** Correlating attributes applied via propagateAttributes(). */
+    correlation: LlmCorrelation;
+    startTime: Date;
+    endTime?: Date;
+};
+export type LlmEmitter = {
+    emit(emission: LlmEmission): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+};
+export type LlmScorer = {
+    /** Resolves true when the score was accepted. Never rejects. */
+    score(body: LlmScoreBody): Promise<boolean>;
 };
 /**
  * Construct a fail-open Langfuse client, or `null` when tracing is disabled or
  * misconfigured. Prefer the process-wide `getLlmTracingClient` in app code;
- * this direct factory exists for tests (inject `langfuseImpl`).
+ * this direct factory exists for tests (inject `emitterImpl`).
  */
 export declare function createLlmTracingClient(env?: EnvMap, options?: {
-    langfuseImpl?: LangfuseLike;
+    emitterImpl?: LlmEmitter;
+    scorerImpl?: LlmScorer;
 }): LlmTracingClient | null;
 export declare function getLlmTracingClient(env?: EnvMap): LlmTracingClient | null;
 /** Flush the singleton if it exists. Never rejects. Hang off request/cycle ends. */

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

@@ -1,18 +1,40 @@
 // LLM-observability transport (ADR 0014): Langfuse is the ONE sanctioned store
 // for full prompt/completion/tool-IO payloads. Axiom stays metadata-only (log.ts
 // redaction drops prompt/input/output-named fields BY DESIGN — that boundary is
-// unchanged), and PostHog stays sanitized product analytics. This module
-// deliberately rides the official `langfuse` SDK's own batched ingestion instead
-// of the OTel pipeline so prompt-bearing telemetry can never reach the Axiom
-// OTLP exporters by construction.
+// unchanged), and PostHog stays sanitized product analytics.
+//
+// Langfuse SDK v5 is OpenTelemetry-based, so the v3-era "never touch OTel"
+// isolation is now bought a different way: this module builds its OWN
+// TracerProvider, hands it to Langfuse via setLangfuseTracerProvider(), and
+// NEVER calls .register(). That matters — @vercel/otel (web) and NodeSDK
+// (worker) install Axiom OTLP exporters on the GLOBAL provider, and every
+// processor on a provider sees every span it creates. Registering globally
+// would therefore ship prompts, completions and tool IO straight into
+// oxygen-traces. The private provider is the load-bearing part of this file.
 //
 // Fail-open doctrine: tracing must never fail or stall product work. Every
 // method swallows internally (worst case: one throttled metadata-only warn via
 // log()), `flush()`/`shutdown()` never reject and are time-bounded, and a
-// missing flag/key yields `null` (callers no-op). Deterministic observation ids
-// are the caller's job — Langfuse upserts by id, which is what makes worker
-// lease-reclaim replays converge instead of duplicating.
-import { Langfuse } from "langfuse";
+// missing flag/key yields `null` (callers no-op).
+//
+// v5 semantics (CHANGED from v3):
+//   * 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.
+//   * 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
+//     propagateAttributes() around each emission — which is why the span/
+//     generation/event bodies carry sessionId/userId at all.
+//   * 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 { log } from "./log.js";
 const FLUSH_TIMEOUT_MS = 5_000;
 const WARN_THROTTLE_MS = 30_000;
@@ -56,6 +78,34 @@ export function resolveLlmTracingEnvironment(env = process.env) {
         return flyEnv === "production" ? "production" : "development";
     return "development";
 }
+/**
+ * Deterministic Langfuse trace id for an external seed (copilot turn id, agent
+ * run id, AI-column run id).
+ *
+ * Byte-identical to `createTraceId(seed)` from @langfuse/tracing — sha256 of the
+ * UTF-8 seed, first 32 hex chars — but SYNCHRONOUS. The official helper returns
+ * a Promise (it uses WebCrypto), and every cross-link site here writes the id on
+ * a hot, synchronous path: the tenant ledger's `turn_started` payload and the
+ * Axiom `copilot.turn.finished` rollup both carry `langfuse_trace_id`, and a
+ * tracer's `traceId` is read synchronously. langfuse.test.ts pins this against
+ * the SDK's own implementation so the two can never drift.
+ */
+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).
+ */
+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) {
@@ -76,10 +126,21 @@ function boundJsonField(value) {
         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
+// 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]";
+function boundComment(comment) {
+    if (comment.length <= MAX_JSON_FIELD_CHARS)
+        return comment;
+    return comment.slice(0, MAX_JSON_FIELD_CHARS - COMMENT_TRUNCATION_MARKER.length) + COMMENT_TRUNCATION_MARKER;
+}
 function compact(body) {
     const out = {};
     for (const [key, value] of Object.entries(body)) {
-        if (value === undefined)
+        if (value === undefined || value === null)
             continue;
         out[key] = key === "input" || key === "output" ? boundJsonField(value) : value;
     }
@@ -97,13 +158,148 @@ 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.
+ */
+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 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),
+                });
+                // 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,
+                };
+            }
+            catch (error) {
+                warn(error, { stage: "init" });
+                return null;
+            }
+        })();
+        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 }));
+        },
+        flush: () => init().then((h) => h?.processor.forceFlush() ?? Promise.resolve()),
+        shutdown: () => init().then((h) => h?.processor.shutdown() ?? Promise.resolve()),
+    };
+}
+/**
+ * The real scorer: one authenticated POST to the Langfuse scores API.
+ *
+ * `@langfuse/core` is imported LAZILY on first score for the same reason the
+ * OTel tree is — a runtime with tracing disabled (the packed CLI, every test)
+ * never pays for it.
+ *
+ * The API client's `environment` option is its BASE URL, not the Langfuse
+ * environment tag; the tag is the `environment` FIELD on the score body, and it
+ * is resolved from the same helper the span processor uses so a score lands in
+ * the same Langfuse environment as the trace it scores. OXYGEN always sets
+ * LANGFUSE_BASE_URL (the project is US-region and the EU host 401s these keys);
+ * the fallback is the SDK's documented default, which `@langfuse/core` itself
+ * does not supply.
+ */
+function createApiScorer(env, warn) {
+    let handle = null;
+    const init = () => {
+        handle ??= (async () => {
+            try {
+                const { LangfuseAPIClient } = await import("@langfuse/core");
+                const client = new LangfuseAPIClient({
+                    environment: env.LANGFUSE_BASE_URL?.trim() || "https://cloud.langfuse.com",
+                    username: env.LANGFUSE_PUBLIC_KEY,
+                    password: env.LANGFUSE_SECRET_KEY,
+                });
+                return client.scores;
+            }
+            catch (error) {
+                warn(error, { stage: "score_init" });
+                return null;
+            }
+        })();
+        return handle;
+    };
+    return {
+        score: async (body) => {
+            try {
+                const api = await init();
+                if (!api)
+                    return false;
+                await api.create(compact({
+                    id: body.id,
+                    traceId: body.traceId,
+                    name: body.name,
+                    value: body.value,
+                    dataType: body.dataType,
+                    comment: typeof body.comment === "string" ? boundComment(body.comment) : undefined,
+                    environment: resolveLlmTracingEnvironment(env),
+                }));
+                return true;
+            }
+            catch (error) {
+                warn(error, { stage: "score" });
+                return false;
+            }
+        },
+    };
+}
 /**
  * Construct a fail-open Langfuse client, or `null` when tracing is disabled or
  * misconfigured. Prefer the process-wide `getLlmTracingClient` in app code;
- * this direct factory exists for tests (inject `langfuseImpl`).
+ * this direct factory exists for tests (inject `emitterImpl`).
  */
 export function createLlmTracingClient(env = process.env, options) {
-    if (!options?.langfuseImpl && !isLlmTracingEnabled(env))
+    if (!options?.emitterImpl && !isLlmTracingEnabled(env))
         return null;
     let lastWarnAtMs = 0;
     const warn = (error, context) => {
@@ -117,30 +313,8 @@ export function createLlmTracingClient(env = process.env, options) {
             ...context,
         });
     };
-    let sdk;
-    try {
-        sdk =
-            options?.langfuseImpl ??
-                new Langfuse({
-                    publicKey: env.LANGFUSE_PUBLIC_KEY,
-                    secretKey: env.LANGFUSE_SECRET_KEY,
-                    ...(env.LANGFUSE_BASE_URL?.trim() ? { baseUrl: env.LANGFUSE_BASE_URL.trim() } : {}),
-                    environment: resolveLlmTracingEnvironment(env),
-                    sdkIntegration: "oxygen",
-                });
-    }
-    catch (error) {
-        warn(error, { stage: "construct" });
-        return null;
-    }
-    // The SDK surfaces async ingest failures on its emitter; unheard, they are
-    // unhandled rejections. Route them into the throttled warn.
-    try {
-        sdk.on?.("error", (error) => warn(error, { stage: "ingest" }));
-    }
-    catch {
-        // an emitter-less test double is fine
-    }
+    const emitter = options?.emitterImpl ?? createOtelEmitter(env, warn);
+    const scorer = options?.scorerImpl ?? createApiScorer(env, warn);
     const guarded = (fn, stage) => {
         try {
             fn();
@@ -149,13 +323,122 @@ export function createLlmTracingClient(env = process.env, options) {
             warn(error, { stage });
         }
     };
+    // propagateAttributes rejects non-string ids and anything over 200 chars, and
+    // drops the whole attribute with a warning rather than truncating. Normalize
+    // here so a stray null/oversized id degrades to "absent", never to a dropped
+    // correlation on every observation of the run.
+    const correlate = (input) => {
+        const bounded = (value) => {
+            if (typeof value !== "string")
+                return undefined;
+            const trimmed = value.trim();
+            if (trimmed === "" || trimmed.length > 200)
+                return undefined;
+            return trimmed;
+        };
+        return compact({
+            traceName: input.traceName,
+            sessionId: bounded(input.sessionId),
+            userId: bounded(input.userId),
+            tags: input.tags,
+        });
+    };
     return {
-        trace: (body) => guarded(() => void sdk.trace(compact(body)), "trace"),
-        span: (body) => guarded(() => void sdk.span(compact(body)), "span"),
-        generation: (body) => guarded(() => void sdk.generation(compact(body)), "generation"),
-        event: (body) => guarded(() => void sdk.event(compact(body)), "event"),
-        flush: () => boundedNever(sdk.flushAsync(), (error) => warn(error, { stage: "flush" })),
-        shutdown: () => boundedNever(sdk.shutdownAsync(), (error) => warn(error, { stage: "shutdown" })),
+        trace: (body) => guarded(() => {
+            const startTime = body.startTime ?? new Date();
+            emitter.emit({
+                kind: "span",
+                traceSeed: body.id,
+                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 },
+                }),
+                correlation: correlate({
+                    traceName: body.name,
+                    sessionId: body.sessionId,
+                    userId: body.userId,
+                    ...(body.tags ? { tags: body.tags } : {}),
+                }),
+                startTime,
+                endTime: body.endTime ?? startTime,
+            });
+        }, "trace"),
+        span: (body) => guarded(() => {
+            emitter.emit({
+                kind: "span",
+                traceSeed: body.traceId,
+                name: body.name,
+                attributes: compact({
+                    input: body.input,
+                    output: body.output,
+                    level: body.level,
+                    statusMessage: body.statusMessage,
+                    metadata: { ...(body.metadata ?? {}), oxygen_observation_id: body.id },
+                }),
+                correlation: correlate({ sessionId: body.sessionId, userId: body.userId }),
+                startTime: body.startTime ?? new Date(),
+                ...(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"),
+        event: (body) => guarded(() => {
+            const startTime = body.startTime ?? new Date();
+            emitter.emit({
+                kind: "event",
+                traceSeed: body.traceId,
+                name: body.name,
+                attributes: compact({
+                    input: body.input,
+                    metadata: { ...(body.metadata ?? {}), oxygen_observation_id: body.id },
+                }),
+                correlation: correlate({ sessionId: body.sessionId, userId: body.userId }),
+                startTime,
+                endTime: startTime,
+            });
+        }, "event"),
+        // Already fail-open inside the scorer; the extra catch is here so that a
+        // scorer which throws SYNCHRONOUSLY (a substituted one in a test, a future
+        // implementation) still cannot escape into a product write.
+        score: async (body) => {
+            try {
+                return await scorer.score(body);
+            }
+            catch (error) {
+                warn(error, { stage: "score" });
+                return false;
+            }
+        },
+        // 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
+        // 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" })),
     };
 }
 // --- Process-wide singleton (both runtimes construct at most one client) ------
@@ -188,7 +471,8 @@ export function flushLlmTracing(env = process.env) {
 // then call scheduleLlmTracingFlush() and the flush runs post-response instead
 // of adding latency inside the request. Off-web (worker, tests) there is no
 // scheduler and the flush degrades to fire-and-forget — the worker's cycle-end
-// awaited flush + SDK interval flush are the durability guarantee there.
+// awaited flush + the processor's own interval flush are the durability
+// guarantee there.
 //
 // The registration lives on globalThis, not in a module-local: Next.js gives
 // instrumentation.ts and each route handler their own copy of this module, so a

package/node_modules/@oxygen/shared/dist/linkedin-quota-denial.d.ts

@@ -1,5 +1,5 @@
 /**
- * How a LinkedIn quota denial is read by the background jobs that hit it.
+ * How a LinkedIn/WhatsApp quota denial is read by the background jobs that hit it.
  *
  * The denial itself is raised by the chokepoint in
  * packages/integrations/src/linkedin-quota.ts; this module is the consumer half,

package/node_modules/@oxygen/shared/dist/linkedin-quota-denial.js

@@ -1,5 +1,5 @@
 /**
- * How a LinkedIn quota denial is read by the background jobs that hit it.
+ * How a LinkedIn/WhatsApp quota denial is read by the background jobs that hit it.
  *
  * The denial itself is raised by the chokepoint in
  * packages/integrations/src/linkedin-quota.ts; this module is the consumer half,
@@ -16,10 +16,21 @@
  */
 import { OxygenError } from "./cli-result.js";
 import { isRecord } from "./type-guards.js";
-// The two codes a denial is raised with. Either is a "come back later" signal,
-// not a broken caller: a daily cap / closed active window that reopens on its own
-// clock, or an account the status webhook will reactivate.
-const QUOTA_DENIED_CODES = new Set(["linkedin_rate_limited", "linkedin_account_unavailable"]);
+// The codes a denial is raised with. Each is a "come back later" signal, not a
+// broken caller: a daily cap / closed active window that reopens on its own clock,
+// or an account the status webhook will reactivate.
+//
+// The WhatsApp mirrors are here because the inbox backstop is shared across
+// networks: a WhatsApp daily-limit denial was reaching it, missing this set, and
+// so was logged as a failure AND never parked -- the same hot re-deny loop the
+// LinkedIn codes were added to stop. Both WhatsApp denials carry `resets_at`, so
+// the park lands on the real reset rather than the fallback below.
+const QUOTA_DENIED_CODES = new Set([
+    "linkedin_rate_limited",
+    "linkedin_account_unavailable",
+    "whatsapp_rate_limited",
+    "whatsapp_account_unavailable",
+]);
 /** Park length when a denial carries no usable `resets_at` hint. */
 const QUOTA_FALLBACK_BACKOFF_MS = 60 * 60 * 1000;
 /** Was this thrown error the quota chokepoint refusing the call? */