@oxygen-agent/cli 1.365.3 → 1.575.19

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

@@ -77,9 +77,57 @@ export const HOSTED_AI_MODEL_REGISTRY = {
             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,
+        },
+    },
+};
+/**
+ * What a MANAGED AI column's reasoning tier is called in front of a customer.
+ *
+ * A managed customer buys an Oxygen tier at a fixed credit price, not a specific
+ * third-party model — which is why the web editor shows these names and never the
+ * vendor model id. The names live here, beside the registry that decides which
+ * model each tier resolves to, so every surface says the same word: a blind user
+ * eval found the web UI offering "Oxygen Balanced" while the CLI's dry-run
+ * reported only `deepseek/deepseek-v4-pro`, leaving a customer to guess whether
+ * they were the same thing.
+ *
+ * BYOK is deliberately excluded: there the user picks real OpenRouter models on
+ * their own key, so the real model id is the correct thing to show.
+ */
+export const MANAGED_AI_TIER_LABELS = {
+    low: "Oxygen Fast",
+    medium: "Oxygen Balanced",
+    high: "Oxygen Max",
 };
 /** 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",
@@ -134,12 +182,13 @@ export function findHostedAiModelSpec(model, preferredUseCase) {
 }
 export function resolveHostedAiModel(input) {
     const base = HOSTED_AI_MODEL_REGISTRY[input.useCase][input.level];
-    if (input.useCase !== "copilot")
+    if (input.useCase === "ai_column")
         return base;
     const env = input.env ?? process.env;
     const suffix = LEVEL_ENV_SUFFIX[input.level];
-    const modelOverride = readTrimmedEnv(env, `OXYGEN_COPILOT_MODEL_${suffix}`);
-    const rawFallback = readTrimmedEnv(env, `OXYGEN_COPILOT_FALLBACK_${suffix}`);
+    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;

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

@@ -2,11 +2,15 @@ export { MANAGED_INBOX_MINIMUM_CLI_VERSION, OXYGEN_MINIMUM_CLI_VERSION, OXYGEN_V
 export { WORKFLOW_TRIGGER_AUTO_PAUSE_METADATA_KEYS, clearWorkflowTriggerAutoPauseMetadata, } from "./workflow-trigger-metadata.js";
 export { WORKFLOW_STATUS_CHANGE_METADATA_KEY, type WorkflowStatusChange, type WorkflowStatusChangeActor, type WorkflowStatusChangeSource, describeWorkflowStatusChange, formatWorkflowStatusChangeTimestamp, parseWorkflowStatusChange, readWorkflowStatusChange, } from "./workflow-status-change.js";
 export * from "./billing.js";
+export * from "./billing-anchors.js";
 export * from "./budget-scopes.js";
+export * from "./plan-limits.js";
+export * from "./spend-safety.js";
 export * from "./cell-format.js";
 export * from "./cli-envelope.js";
 export * from "./cli-login-code.js";
 export * from "./cli-result.js";
+export * from "./crm-reply-events.js";
 export * from "./column-types.js";
 export * from "./copilot-journeys.js";
 export * from "./credit-guidance.js";
@@ -20,16 +24,23 @@ 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-quota-denial.js";
 export * from "./linkedin-url.js";
 export * from "./linkedin-sequences.js";
+export * from "./microsoft-consent-url.js";
 export * from "./networks.js";
 export * from "./recipes.js";
 export * from "./sequence-template.js";
+export * from "./sequence-crm-events.js";
+export * from "./call-outcomes.js";
+export * from "./dial-guardrail-overrides.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

@@ -2,11 +2,15 @@ export { MANAGED_INBOX_MINIMUM_CLI_VERSION, OXYGEN_MINIMUM_CLI_VERSION, OXYGEN_V
 export { WORKFLOW_TRIGGER_AUTO_PAUSE_METADATA_KEYS, clearWorkflowTriggerAutoPauseMetadata, } from "./workflow-trigger-metadata.js";
 export { WORKFLOW_STATUS_CHANGE_METADATA_KEY, describeWorkflowStatusChange, formatWorkflowStatusChangeTimestamp, parseWorkflowStatusChange, readWorkflowStatusChange, } from "./workflow-status-change.js";
 export * from "./billing.js";
+export * from "./billing-anchors.js";
 export * from "./budget-scopes.js";
+export * from "./plan-limits.js";
+export * from "./spend-safety.js";
 export * from "./cell-format.js";
 export * from "./cli-envelope.js";
 export * from "./cli-login-code.js";
 export * from "./cli-result.js";
+export * from "./crm-reply-events.js";
 export * from "./column-types.js";
 export * from "./copilot-journeys.js";
 export * from "./credit-guidance.js";
@@ -20,16 +24,27 @@ 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-quota-denial.js";
 export * from "./linkedin-url.js";
 export * from "./linkedin-sequences.js";
+export * from "./microsoft-consent-url.js";
 export * from "./networks.js";
 export * from "./recipes.js";
 export * from "./sequence-template.js";
+export * from "./sequence-crm-events.js";
+export * from "./call-outcomes.js";
+export * from "./dial-guardrail-overrides.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-quota-denial.d.ts

@@ -0,0 +1,31 @@
+/**
+ * How a LinkedIn 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,
+ * and it lives here because the consumers are spread across the worker, the web
+ * app, and the integrations package — three copies of "is this a denial, and
+ * until when" is exactly how the inbox sync and the publishing metrics sync ended
+ * up with different behavior for the same condition.
+ *
+ * The pattern (established in v1.423.0 for `linkedin.inbox_sync_failed`, which
+ * emitted 158,882 warn lines in 31h for one account): a denial is logged at
+ * `info`, not `warn` — a rate budget doing its job is normal operation, and at
+ * background cadence it buries the real warnings — and the account is parked
+ * until its budget resets rather than re-denied on every tenant tick.
+ */
+import { OxygenError } from "./cli-result.js";
+/** Was this thrown error the quota chokepoint refusing the call? */
+export declare function isLinkedInQuotaDenial(error: unknown): error is OxygenError;
+/**
+ * When a quota-denied caller may try again — the denial's own `resets_at` when it
+ * carries a usable one, else a flat hour. Null for anything that is NOT a quota
+ * denial: an ordinary failure (provider timeout, malformed payload) has no reset
+ * instant and must keep retrying on its caller's normal cadence.
+ */
+export declare function linkedInQuotaBackoffUntil(error: unknown, now: Date): Date | null;
+/**
+ * Epoch-ms a sender's park — written under `key` in the freeform
+ * `sender_accounts.metadata` jsonb — expires; 0 when it is not parked.
+ */
+export declare function linkedInQuotaParkedUntil(metadata: unknown, key: string): number;

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

@@ -0,0 +1,56 @@
+/**
+ * How a LinkedIn 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,
+ * and it lives here because the consumers are spread across the worker, the web
+ * app, and the integrations package — three copies of "is this a denial, and
+ * until when" is exactly how the inbox sync and the publishing metrics sync ended
+ * up with different behavior for the same condition.
+ *
+ * The pattern (established in v1.423.0 for `linkedin.inbox_sync_failed`, which
+ * emitted 158,882 warn lines in 31h for one account): a denial is logged at
+ * `info`, not `warn` — a rate budget doing its job is normal operation, and at
+ * background cadence it buries the real warnings — and the account is parked
+ * until its budget resets rather than re-denied on every tenant tick.
+ */
+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"]);
+/** 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? */
+export function isLinkedInQuotaDenial(error) {
+    return error instanceof OxygenError && QUOTA_DENIED_CODES.has(error.code);
+}
+/**
+ * When a quota-denied caller may try again — the denial's own `resets_at` when it
+ * carries a usable one, else a flat hour. Null for anything that is NOT a quota
+ * denial: an ordinary failure (provider timeout, malformed payload) has no reset
+ * instant and must keep retrying on its caller's normal cadence.
+ */
+export function linkedInQuotaBackoffUntil(error, now) {
+    if (!isLinkedInQuotaDenial(error))
+        return null;
+    const raw = isRecord(error.details) ? error.details.resets_at : undefined;
+    if (typeof raw === "string") {
+        const ms = Date.parse(raw);
+        if (!Number.isNaN(ms) && ms > now.getTime())
+            return new Date(ms);
+    }
+    return new Date(now.getTime() + QUOTA_FALLBACK_BACKOFF_MS);
+}
+/**
+ * Epoch-ms a sender's park — written under `key` in the freeform
+ * `sender_accounts.metadata` jsonb — expires; 0 when it is not parked.
+ */
+export function linkedInQuotaParkedUntil(metadata, key) {
+    const raw = isRecord(metadata) ? metadata[key] : undefined;
+    if (typeof raw !== "string")
+        return 0;
+    const ms = Date.parse(raw);
+    return Number.isNaN(ms) ? 0 : ms;
+}

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

@@ -144,10 +144,11 @@ export declare function waitStepDelayMs(step: LinkedInWaitStep): number;
 /**
  * Render a sequence-copy template against a row's values. Delegates to the shared
  * deterministic engine, so beyond `{{column}}` substitution it also handles
- * `{{column|fallback}}`, `{{RANDOM|…}}` spintax, and `{% if … %}` conditionals.
- * Unknown `{{column}}` placeholders render empty. Used by the dispatch engine to
- * produce the final message text. Pass `{ seed }` to make spintax choices
- * replayable (crash-safe); with no seed a stable template+values seed is derived.
+ * `{{column|fallback}}`, `{{RANDOM|…}}` and bare `{a|b|c}` spintax (nestable), and
+ * `{% if … %}` conditionals. Unknown `{{column}}` placeholders render empty. Used
+ * by the dispatch engine to produce the final message text. Pass `{ seed }` to make
+ * spintax choices replayable (crash-safe); with no seed a stable template+values
+ * seed is derived.
  */
 export declare function renderLinkedInTemplate(template: string, values: Record<string, unknown>, options?: RenderTemplateOptions): string;
 export {};

package/node_modules/@oxygen/shared/dist/linkedin-sequences.js

@@ -64,10 +64,11 @@ export function waitStepDelayMs(step) {
 /**
  * Render a sequence-copy template against a row's values. Delegates to the shared
  * deterministic engine, so beyond `{{column}}` substitution it also handles
- * `{{column|fallback}}`, `{{RANDOM|…}}` spintax, and `{% if … %}` conditionals.
- * Unknown `{{column}}` placeholders render empty. Used by the dispatch engine to
- * produce the final message text. Pass `{ seed }` to make spintax choices
- * replayable (crash-safe); with no seed a stable template+values seed is derived.
+ * `{{column|fallback}}`, `{{RANDOM|…}}` and bare `{a|b|c}` spintax (nestable), and
+ * `{% if … %}` conditionals. Unknown `{{column}}` placeholders render empty. Used
+ * by the dispatch engine to produce the final message text. Pass `{ seed }` to make
+ * spintax choices replayable (crash-safe); with no seed a stable template+values
+ * seed is derived.
  */
 export function renderLinkedInTemplate(template, values, options) {
     return renderTemplate(template, values, options);

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

@@ -1,6 +1,28 @@
 export type LinkedinUrlNormalization = {
+    /**
+     * Lowercase canonical URL — the stable MATCH key (CRM `linkedin_url_v1`
+     * identities, suppression entries). Lowercasing is what makes two spellings of
+     * the same profile compare equal, so this must stay case-folded forever: a
+     * suppression key that changed case would stop matching every row already
+     * stored under the old spelling, and someone who opted out would be contacted.
+     */
     normalized: string;
+    /** Lowercase handle — the stable match key. Same contract as `normalized`. */
     handle: string;
+    /**
+     * The handle with its ORIGINAL case, for anything that hands the identifier
+     * back to a provider or stores it on a record.
+     *
+     * A public slug is lowercase by construction, so this equals `handle` for it.
+     * An `ACoAA…` provider id is base64url of a member URN — its case is
+     * significant, and folding it is irreversible data loss: the id then resolves
+     * at neither Unipile nor HarvestAPI (which answers HTTP 400 "You need to
+     * provide at least one valid argument"). Reach for this whenever the value
+     * leaves Oxygen; reach for `handle`/`normalized` whenever it is compared.
+     */
+    dispatchHandle: string;
+    /** Canonical URL built from `dispatchHandle` — what we store on a record. */
+    dispatchUrl: string;
 } | null;
 export declare function normalizeLinkedinProfileUrl(raw: string | null | undefined): LinkedinUrlNormalization;
 /**

package/node_modules/@oxygen/shared/dist/linkedin-url.js

@@ -48,18 +48,21 @@ export function normalizeLinkedinProfileUrl(raw) {
     const rawHandle = parts[markerIndex + 1];
     if (!rawHandle)
         return null;
-    let handle;
+    let decoded;
     try {
-        handle = decodeURIComponent(rawHandle).trim().toLowerCase();
+        decoded = decodeURIComponent(rawHandle).trim();
     }
     catch {
-        handle = rawHandle.trim().toLowerCase();
+        decoded = rawHandle.trim();
     }
-    if (!handle)
+    if (!decoded)
         return null;
+    const handle = decoded.toLowerCase();
     return {
         normalized: `https://www.linkedin.com/in/${handle}`,
         handle,
+        dispatchHandle: decoded,
+        dispatchUrl: `https://www.linkedin.com/in/${decoded}`,
     };
 }
 // A LinkedIn post URL carries the numeric activity id we address the post by: