@oxygen-agent/cli 1.354.0 → 1.377.3

package/node_modules/@oxygen/shared/dist/hosted-ai.js

@@ -0,0 +1,212 @@
+/**
+ * Canonical hosted-AI model registry — the single source of truth for which
+ * OXYGEN-hosted model backs each reasoning tier of each hosted-AI use case, its
+ * human-readable name, its fallback chain, the OpenRouter reasoning effort to
+ * request, and the conservative pre-call price estimates used ONLY to size
+ * credit reservations (billing always settles on the provider's actual
+ * `usage.cost`, never on the numbers here).
+ *
+ * Two use cases share the registry today:
+ *   - `ai_column` — managed AI table columns. Its default model ids are
+ *     re-sourced verbatim by `@oxygen/integrations` (`ai-column-runner.ts`
+ *     `DEFAULT_REASONING_MODELS`) and `@oxygen/tenant-db` (`ai-models.ts`
+ *     `DEFAULT_MANAGED_REASONING_MODELS`). Those modules keep owning the
+ *     `OXYGEN_OPENROUTER_MODEL_*` env-override resolution; this registry only
+ *     supplies the defaults, so AI-column behavior is byte-for-byte unchanged.
+ *   - `copilot` — the hosted copilot. Its model + fallback chain accept Doppler
+ *     overrides (`OXYGEN_COPILOT_MODEL_*` / `OXYGEN_COPILOT_FALLBACK_*`) applied
+ *     here by `resolveHostedAiModel`.
+ *
+ * Kept as a leaf module (mirrors ./pricing-sheet.ts): no imports, so any package
+ * can re-source the catalog without dragging in the shared barrel.
+ */
+export const HOSTED_AI_MODEL_REGISTRY = {
+    ai_column: {
+        low: {
+            model: "deepseek/deepseek-v4-flash",
+            displayName: "DeepSeek V4 Flash",
+            fallbackModels: [],
+            estPromptUsdPerM: 0.09,
+            estCompletionUsdPerM: 0.18,
+            maxOutputTokens: 4096,
+        },
+        medium: {
+            model: "deepseek/deepseek-v4-pro",
+            displayName: "DeepSeek V4 Pro",
+            fallbackModels: [],
+            estPromptUsdPerM: 0.435,
+            estCompletionUsdPerM: 0.87,
+            maxOutputTokens: 4096,
+        },
+        high: {
+            model: "moonshotai/kimi-k2.6",
+            displayName: "Kimi K2.6",
+            fallbackModels: [],
+            estPromptUsdPerM: 0.66,
+            estCompletionUsdPerM: 3.41,
+            maxOutputTokens: 4096,
+        },
+    },
+    copilot: {
+        low: {
+            model: "deepseek/deepseek-v4-flash",
+            displayName: "DeepSeek V4 Flash",
+            fallbackModels: [],
+            reasoningEffort: "medium",
+            estPromptUsdPerM: 0.09,
+            estCompletionUsdPerM: 0.18,
+            maxOutputTokens: 8192,
+        },
+        medium: {
+            model: "deepseek/deepseek-v4-pro",
+            displayName: "DeepSeek V4 Pro",
+            fallbackModels: [],
+            reasoningEffort: "high",
+            estPromptUsdPerM: 0.435,
+            estCompletionUsdPerM: 0.87,
+            maxOutputTokens: 8192,
+        },
+        high: {
+            model: "moonshotai/kimi-k3",
+            displayName: "Kimi K3",
+            fallbackModels: ["moonshotai/kimi-k2.6"],
+            // No reasoningEffort: Kimi K3 is max-only; the request builder omits the
+            // reasoning param for this tier.
+            estPromptUsdPerM: 3,
+            estCompletionUsdPerM: 15,
+            maxOutputTokens: 8192,
+        },
+    },
+    agent: {
+        low: {
+            model: "deepseek/deepseek-v4-flash",
+            displayName: "DeepSeek V4 Flash",
+            fallbackModels: [],
+            reasoningEffort: "medium",
+            estPromptUsdPerM: 0.09,
+            estCompletionUsdPerM: 0.18,
+            maxOutputTokens: 8192,
+        },
+        medium: {
+            model: "deepseek/deepseek-v4-pro",
+            displayName: "DeepSeek V4 Pro",
+            fallbackModels: ["deepseek/deepseek-v4-flash"],
+            reasoningEffort: "high",
+            estPromptUsdPerM: 0.435,
+            estCompletionUsdPerM: 0.87,
+            maxOutputTokens: 8192,
+        },
+        high: {
+            model: "moonshotai/kimi-k2.6",
+            displayName: "Kimi K2.6",
+            fallbackModels: ["deepseek/deepseek-v4-pro"],
+            estPromptUsdPerM: 0.66,
+            estCompletionUsdPerM: 3.41,
+            maxOutputTokens: 8192,
+        },
+    },
+};
+/** The reasoning tier the hosted copilot runs at by default. */
+export const COPILOT_DEFAULT_LEVEL = "high";
+export const AGENT_DEFAULT_LEVEL = "medium";
+const LEVEL_ENV_SUFFIX = {
+    low: "LOW",
+    medium: "MEDIUM",
+    high: "HIGH",
+};
+function readTrimmedEnv(env, key) {
+    const raw = env[key];
+    if (typeof raw !== "string")
+        return undefined;
+    const trimmed = raw.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function parseFallbackCsv(raw) {
+    return raw
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
+/**
+ * Resolve the model spec for a hosted-AI use case + reasoning level.
+ *
+ * For `copilot`, Doppler overrides are applied here:
+ *   - `OXYGEN_COPILOT_MODEL_{LOW,MEDIUM,HIGH}` replaces `.model` (and, since no
+ *     separate label is supplied, `.displayName` falls back to the model id).
+ *   - `OXYGEN_COPILOT_FALLBACK_{LOW,MEDIUM,HIGH}` replaces `.fallbackModels`
+ *     from a comma-separated list.
+ *
+ * For `ai_column`, NO env handling is applied here: `@oxygen/integrations`
+ * `ai-column-runner.ts` (`resolveModel`/`resolveAiColumnTierModels`) and
+ * `@oxygen/tenant-db` `ai-models.ts` (`resolveManagedReasoningModels`) remain
+ * the sole owners of `OXYGEN_OPENROUTER_MODEL_*` resolution, so the AI-column
+ * path is untouched.
+ */
+/**
+ * Look a model id up across the priced registry (same-use-case tiers first).
+ * A session-level model override must land on a spec that carries ITS OWN
+ * pricing/limits — splicing an arbitrary id onto another tier's spec sizes the
+ * credit reservation for the wrong model and breaks the spend ceiling.
+ */
+export function findHostedAiModelSpec(model, preferredUseCase) {
+    const useCases = Object.keys(HOSTED_AI_MODEL_REGISTRY);
+    const ordered = preferredUseCase
+        ? [preferredUseCase, ...useCases.filter((u) => u !== preferredUseCase)]
+        : useCases;
+    for (const useCase of ordered) {
+        for (const spec of Object.values(HOSTED_AI_MODEL_REGISTRY[useCase])) {
+            if (spec.model === model)
+                return spec;
+        }
+    }
+    return null;
+}
+export function resolveHostedAiModel(input) {
+    const base = HOSTED_AI_MODEL_REGISTRY[input.useCase][input.level];
+    if (input.useCase === "ai_column")
+        return base;
+    const env = input.env ?? process.env;
+    const suffix = LEVEL_ENV_SUFFIX[input.level];
+    const envPrefix = input.useCase === "agent" ? "OXYGEN_AGENT" : "OXYGEN_COPILOT";
+    const modelOverride = readTrimmedEnv(env, `${envPrefix}_MODEL_${suffix}`);
+    const rawFallback = readTrimmedEnv(env, `${envPrefix}_FALLBACK_${suffix}`);
+    const fallbackOverride = rawFallback === undefined ? undefined : parseFallbackCsv(rawFallback);
+    if (modelOverride === undefined && fallbackOverride === undefined)
+        return base;
+    // Spread preserves the absence of `reasoningEffort` on max-only tiers.
+    const resolved = { ...base };
+    if (modelOverride !== undefined) {
+        resolved.model = modelOverride;
+        resolved.displayName = modelOverride;
+    }
+    if (fallbackOverride !== undefined) {
+        resolved.fallbackModels = fallbackOverride;
+    }
+    return resolved;
+}
+/**
+ * Convenience map of each reasoning tier's default `.model` id for a use case.
+ * `@oxygen/integrations` and `@oxygen/tenant-db` re-source their AI-column
+ * default catalogs from `hostedAiDefaultModels("ai_column")` so the model ids
+ * live in exactly one place. Returns a fresh object each call.
+ */
+export function hostedAiDefaultModels(useCase) {
+    const specs = HOSTED_AI_MODEL_REGISTRY[useCase];
+    return {
+        low: specs.low.model,
+        medium: specs.medium.model,
+        high: specs.high.model,
+    };
+}
+/**
+ * Whether the hosted copilot is enabled for this environment. FAIL CLOSED: only
+ * the exact strings "1" or "true" (case-insensitive, trimmed) enable it;
+ * anything else — unset, "", "0", "false" — leaves it off.
+ */
+export function isCopilotEnabled(env = process.env) {
+    const raw = env.OXYGEN_COPILOT_ENABLED;
+    if (typeof raw !== "string")
+        return false;
+    const normalized = raw.trim().toLowerCase();
+    return normalized === "1" || normalized === "true";
+}

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

@@ -8,16 +8,20 @@ export * from "./cli-envelope.js";
 export * from "./cli-login-code.js";
 export * from "./cli-result.js";
 export * from "./column-types.js";
+export * from "./copilot-journeys.js";
 export * from "./credit-guidance.js";
 export * from "./directory.js";
 export * from "./email-tracking-token.js";
 export * from "./email-unsubscribe-token.js";
 export * from "./error-redaction.js";
+export * from "./hosted-ai.js";
 export * from "./identifiers.js";
 export * from "./knowledge-constants.js";
 export * from "./knowledge-links.js";
 export * from "./knowledge-markdown.js";
 export * from "./knowledge-seed-content.js";
+export * from "./langfuse.js";
+export * from "./linkedin-mentions.js";
 export * from "./linkedin-post-url.js";
 export * from "./linkedin-url.js";
 export * from "./linkedin-sequences.js";
@@ -27,6 +31,7 @@ export * from "./sequence-template.js";
 export * from "./sequences.js";
 export * from "./suppression-entries.js";
 export * from "./log.js";
+export { sanitizeLogFields } from "./redaction.js";
 export * from "./provider-request-outcomes.js";
 export * from "./schedule-label.js";
 export * from "./signup-lead-deliveries.js";

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

@@ -8,16 +8,20 @@ export * from "./cli-envelope.js";
 export * from "./cli-login-code.js";
 export * from "./cli-result.js";
 export * from "./column-types.js";
+export * from "./copilot-journeys.js";
 export * from "./credit-guidance.js";
 export * from "./directory.js";
 export * from "./email-tracking-token.js";
 export * from "./email-unsubscribe-token.js";
 export * from "./error-redaction.js";
+export * from "./hosted-ai.js";
 export * from "./identifiers.js";
 export * from "./knowledge-constants.js";
 export * from "./knowledge-links.js";
 export * from "./knowledge-markdown.js";
 export * from "./knowledge-seed-content.js";
+export * from "./langfuse.js";
+export * from "./linkedin-mentions.js";
 export * from "./linkedin-post-url.js";
 export * from "./linkedin-url.js";
 export * from "./linkedin-sequences.js";
@@ -27,6 +31,11 @@ export * from "./sequence-template.js";
 export * from "./sequences.js";
 export * from "./suppression-entries.js";
 export * from "./log.js";
+// Narrow, deliberate export (ADR 0014): lets telemetry emitters regression-test
+// their field names against the REAL log sanitizer — the unanchored
+// SECRET_KEY_PATTERN redacts any name containing "token", which mocked loggers
+// cannot catch. Not a license to pre-sanitize outside log().
+export { sanitizeLogFields } from "./redaction.js";
 export * from "./provider-request-outcomes.js";
 export * from "./schedule-label.js";
 export * from "./signup-lead-deliveries.js";

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

@@ -0,0 +1,77 @@
+import { Langfuse } from "langfuse";
+type EnvMap = Record<string, string | undefined>;
+export type LlmObservationLevel = "DEBUG" | "DEFAULT" | "WARNING" | "ERROR";
+export type LlmTraceBody = {
+    id: string;
+    name: string;
+    sessionId?: string | null;
+    userId?: string | null;
+    input?: unknown;
+    output?: unknown;
+    metadata?: Record<string, unknown>;
+    tags?: string[];
+};
+export type LlmSpanBody = {
+    id: string;
+    traceId: string;
+    name: string;
+    input?: unknown;
+    output?: unknown;
+    metadata?: Record<string, unknown>;
+    startTime?: Date;
+    endTime?: Date;
+    level?: LlmObservationLevel;
+    statusMessage?: string | null;
+};
+export type LlmGenerationBody = LlmSpanBody & {
+    model?: string | null;
+    completionStartTime?: Date | null;
+    usageDetails?: Record<string, number>;
+    costDetails?: Record<string, number>;
+};
+export type LlmEventBody = {
+    id: string;
+    traceId: string;
+    name: string;
+    input?: unknown;
+    metadata?: Record<string, unknown>;
+    startTime?: Date;
+};
+export type LlmTracingClient = {
+    trace(body: LlmTraceBody): void;
+    span(body: LlmSpanBody): void;
+    generation(body: LlmGenerationBody): void;
+    event(body: LlmEventBody): void;
+    /** Never rejects; bounded at ~5s. */
+    flush(): Promise<void>;
+    /** Flush + stop background timers. Never rejects; bounded at ~5s. */
+    shutdown(): Promise<void>;
+};
+/**
+ * FAIL CLOSED: LLM tracing is on only when OXYGEN_LLM_TRACING_ENABLED is exactly
+ * "1"/"true" (trimmed, case-insensitive) AND both Langfuse keys are present.
+ */
+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;
+};
+/**
+ * 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`).
+ */
+export declare function createLlmTracingClient(env?: EnvMap, options?: {
+    langfuseImpl?: LangfuseLike;
+}): LlmTracingClient | null;
+export declare function getLlmTracingClient(env?: EnvMap): LlmTracingClient | null;
+/** Flush the singleton if it exists. Never rejects. Hang off request/cycle ends. */
+export declare function flushLlmTracing(env?: EnvMap): Promise<void>;
+type FlushScheduler = (task: () => Promise<void>) => void;
+export declare function setLlmTracingFlushScheduler(scheduler: FlushScheduler | null): void;
+/** Request-safe flush trigger: post-response on web, fire-and-forget elsewhere. */
+export declare function scheduleLlmTracingFlush(env?: EnvMap): void;
+/** Shutdown the singleton (worker exit). Never rejects. */
+export declare function shutdownLlmTracing(env?: EnvMap): Promise<void>;
+export declare function __resetLlmTracingForTests(): void;
+export {};

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

@@ -0,0 +1,231 @@
+// 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.
+//
+// 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";
+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.
+const MAX_JSON_FIELD_CHARS = 400_000;
+/**
+ * FAIL CLOSED: LLM tracing is on only when OXYGEN_LLM_TRACING_ENABLED is exactly
+ * "1"/"true" (trimmed, case-insensitive) AND both Langfuse keys are present.
+ */
+export function isLlmTracingEnabled(env = process.env) {
+    const raw = env.OXYGEN_LLM_TRACING_ENABLED;
+    if (typeof raw !== "string")
+        return false;
+    const normalized = raw.trim().toLowerCase();
+    if (normalized !== "1" && normalized !== "true")
+        return false;
+    return ((env.LANGFUSE_PUBLIC_KEY?.trim() ?? "") !== "" &&
+        (env.LANGFUSE_SECRET_KEY?.trim() ?? "") !== "");
+}
+// The Langfuse "environment" dimension separates dev/prod traces inside one
+// project. Explicit LANGFUSE_TRACING_ENVIRONMENT (Doppler, per config) wins.
+// Defaults per runtime: web has VERCEL_ENV; the Fly worker has NO VERCEL_ENV
+// (and NODE_ENV=production on BOTH worker apps), so mirror the worker telemetry
+// convention (apps/worker/src/telemetry.ts): the Fly-injected app name is the
+// ground truth for prod vs dev — the "-dev" suffix marks the dev app; a
+// cross-env Doppler drift cannot fake it (the OXY-1183 lesson) — then
+// FLY_ENVIRONMENT as the softer signal. Everything else → development.
+export function resolveLlmTracingEnvironment(env = process.env) {
+    const explicit = env.LANGFUSE_TRACING_ENVIRONMENT?.trim().toLowerCase();
+    if (explicit)
+        return explicit.replace(/[^a-z0-9_-]/g, "-");
+    if (env.VERCEL_ENV)
+        return env.VERCEL_ENV === "production" ? "production" : "development";
+    const flyApp = env.FLY_APP_NAME ?? env.FLY_APP;
+    if (flyApp)
+        return flyApp.includes("-dev") ? "development" : "production";
+    const flyEnv = env.FLY_ENVIRONMENT?.trim().toLowerCase();
+    if (flyEnv)
+        return flyEnv === "production" ? "production" : "development";
+    return "development";
+}
+// 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),
+    };
+}
+function compact(body) {
+    const out = {};
+    for (const [key, value] of Object.entries(body)) {
+        if (value === undefined)
+            continue;
+        out[key] = key === "input" || key === "output" ? boundJsonField(value) : value;
+    }
+    return out;
+}
+function boundedNever(rejectable, warn) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, FLUSH_TIMEOUT_MS);
+        timer.unref?.();
+        rejectable
+            .catch((error) => warn(error))
+            .finally(() => {
+            clearTimeout(timer);
+            resolve();
+        });
+    });
+}
+/**
+ * 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`).
+ */
+export function createLlmTracingClient(env = process.env, options) {
+    if (!options?.langfuseImpl && !isLlmTracingEnabled(env))
+        return null;
+    let lastWarnAtMs = 0;
+    const warn = (error, context) => {
+        const nowMs = Date.now();
+        if (nowMs - lastWarnAtMs < WARN_THROTTLE_MS)
+            return;
+        lastWarnAtMs = nowMs;
+        log("warn", "llm_tracing.ingest_failed", {
+            provider: "langfuse",
+            error_message: error instanceof Error ? error.message : String(error),
+            ...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 guarded = (fn, stage) => {
+        try {
+            fn();
+        }
+        catch (error) {
+            warn(error, { stage });
+        }
+    };
+    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" })),
+    };
+}
+// --- Process-wide singleton (both runtimes construct at most one client) ------
+let cached = null;
+function cacheKey(env) {
+    return [
+        env.OXYGEN_LLM_TRACING_ENABLED ?? "",
+        env.LANGFUSE_PUBLIC_KEY ?? "",
+        env.LANGFUSE_SECRET_KEY ?? "",
+        env.LANGFUSE_BASE_URL ?? "",
+        resolveLlmTracingEnvironment(env),
+    ].join("|");
+}
+export function getLlmTracingClient(env = process.env) {
+    const key = cacheKey(env);
+    if (cached && cached.key === key)
+        return cached.client;
+    cached = { key, client: createLlmTracingClient(env) };
+    return cached.client;
+}
+/** Flush the singleton if it exists. Never rejects. Hang off request/cycle ends. */
+export function flushLlmTracing(env = process.env) {
+    if (!isLlmTracingEnabled(env))
+        return Promise.resolve();
+    const client = getLlmTracingClient(env);
+    return client ? client.flush() : Promise.resolve();
+}
+// Serverless flush scheduling (the axiom-log-shipper pattern): the web runtime
+// registers next/server's after() here at instrumentation time; emission sites
+// 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.
+//
+// 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
+// module-local set at instrumentation time is invisible to the routes that emit
+// traces — their flushes silently degraded to fire-and-forget, which a Vercel
+// post-response freeze can kill. Same slot pattern as setLogSink and the
+// LinkedIn/WhatsApp quota enforcers. (The `cached` client stays module-local on
+// purpose: each bundle flushing its own client is correct — the run closure
+// below flushes the CALLING bundle's client through the shared scheduler.)
+const FLUSH_SCHEDULER_SLOT = Symbol.for("oxygen.llm_tracing.flush_scheduler");
+export function setLlmTracingFlushScheduler(scheduler) {
+    globalThis[FLUSH_SCHEDULER_SLOT] = scheduler;
+}
+/** Request-safe flush trigger: post-response on web, fire-and-forget elsewhere. */
+export function scheduleLlmTracingFlush(env = process.env) {
+    if (!isLlmTracingEnabled(env))
+        return;
+    const run = () => flushLlmTracing(env);
+    const flushScheduler = globalThis[FLUSH_SCHEDULER_SLOT] ?? null;
+    if (flushScheduler) {
+        try {
+            flushScheduler(run);
+            return;
+        }
+        catch {
+            // Outside a request scope after() throws — degrade to fire-and-forget.
+        }
+    }
+    void run();
+}
+/** Shutdown the singleton (worker exit). Never rejects. */
+export function shutdownLlmTracing(env = process.env) {
+    const client = cached?.client;
+    cached = null;
+    return client ? client.shutdown() : Promise.resolve();
+}
+export function __resetLlmTracingForTests() {
+    cached = null;
+    globalThis[FLUSH_SCHEDULER_SLOT] = null;
+}

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

@@ -0,0 +1,37 @@
+/**
+ * Compile LinkedIn post text + stored mention state into Unipile's post
+ * contract: the outgoing text carries `{{i}}` placeholders and `mentions[i]`
+ * is `{ name, profile_id }`. Anything else (raw `@handle` text next to a
+ * mentions array, Oxygen mention-preview snapshots, unresolved handles) is
+ * NOT a tagged mention on LinkedIn — the provider either posts it literally
+ * or, worse, name-matches entries into the wrong span of text.
+ *
+ * Accepted inputs per entry (both arrays are optional):
+ * - Unipile-shaped: `{ name, profile_id }` (already the wire contract).
+ * - Oxygen preview-shaped (publishing mentions resolve output): uses
+ *   `displayName`/`providerId` (or snake_case), and is only eligible when
+ *   `status === "resolved"` and `semantics` is `"mention"` (links and plain
+ *   references stay as typed).
+ *
+ * Placement: an entry becomes a tagged mention only when its span can be
+ * anchored in the text — an existing `{{i}}` placeholder, the entry's `raw`
+ * occurrence, or `@name`/`@identifier`. Entries that cannot be anchored are
+ * dropped from the outgoing array so the provider can never guess a span.
+ */
+export type UnipileLinkedInMention = {
+    name: string;
+    profile_id: string;
+};
+export type CompiledLinkedInMentions = {
+    text: string;
+    mentions: UnipileLinkedInMention[];
+    dropped: Array<{
+        name: string | null;
+        reason: "unresolved" | "not_in_text" | "invalid";
+    }>;
+};
+export declare function compileLinkedInMentions(input: {
+    text: string;
+    mentions?: unknown;
+    mentionPreviews?: unknown;
+}): CompiledLinkedInMentions;