@oxygen-agent/cli 1.246.0 → 1.263.0

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

@@ -1,5 +1,5 @@
 import { OxygenError } from "./cli-result.js";
-import { renderLinkedInTemplate } from "./linkedin-sequences.js";
+import { hashVariantKey, renderTemplate, templateColumnKeys, } from "./sequence-template.js";
 /**
  * Multichannel sequence DSL — the shared contract validated identically by CLI,
  * MCP, API, and web. A sequence is an ordered list of steps applied to each
@@ -105,6 +105,100 @@ export function recipientEmailFromRow(rowValues) {
     }
     return null;
 }
+/**
+ * ESP (email service provider) MATCHING mode for a sequence (settings.esp_matching).
+ * Deliverability lore: a send lands better when the SENDING mailbox and the
+ * RECIPIENT sit on the same provider (Google→Google, Microsoft→Microsoft), so at
+ * mailbox-pick the dispatcher can bias rotation toward a same-ESP mailbox.
+ *   - "off"    — no ESP bias (default); rotation is pure LRU / domain-spread.
+ *   - "prefer" — pick a same-ESP mailbox when one is available, else fall back to
+ *     any sendable mailbox (never blocks a send).
+ *   - "strict" — require a same-ESP mailbox; when none is available the action is
+ *     DEFERRED with a visible skipped_reason rather than sent cross-provider.
+ */
+export const ESP_MATCHING_MODES = ["off", "prefer", "strict"];
+export const DEFAULT_ESP_MATCHING_MODE = "off";
+export function isEspMatchingMode(value) {
+    return typeof value === "string" && ESP_MATCHING_MODES.includes(value);
+}
+/**
+ * Validate settings.esp_matching before persistence. Absent/null is valid (means
+ * DEFAULT_ESP_MATCHING_MODE "off"); any other value must be one of the three
+ * modes. Pure; throws OxygenError("invalid_sequence_settings") on a bad value so
+ * the CLI / MCP / API report an identical error. Called from the tenant-db
+ * settings validator alongside the budget/prioritization checks.
+ */
+export function validateEspMatchingSetting(value) {
+    if (value === undefined || value === null)
+        return;
+    if (!isEspMatchingMode(value)) {
+        throw new OxygenError("invalid_sequence_settings", `settings.esp_matching must be one of: ${ESP_MATCHING_MODES.join(", ")}.`, { details: { field: "esp_matching", value }, exitCode: 1 });
+    }
+}
+/**
+ * The email-provider FAMILY a recipient (or sending mailbox) routes through. Kept
+ * intentionally aligned with EMAIL_MAILBOX_PROVIDERS in tenant-db so a mailbox's
+ * `provider` and an inferred recipient ESP compare directly.
+ */
+export const RECIPIENT_ESPS = ["google", "microsoft"];
+/** Consumer domains that deterministically route to Google / Microsoft mail. */
+const GOOGLE_CONSUMER_DOMAINS = new Set(["gmail.com", "googlemail.com"]);
+const MICROSOFT_CONSUMER_DOMAINS = new Set(["outlook.com", "hotmail.com", "live.com", "msn.com"]);
+/**
+ * Normalize a recipient domain: lowercase, trim, drop a trailing FQDN dot, and if
+ * a full address is passed take the part after the last '@'. Returns "" for junk.
+ */
+function normalizeRecipientDomain(domain) {
+    if (typeof domain !== "string")
+        return "";
+    let d = domain.trim().toLowerCase();
+    const at = d.lastIndexOf("@");
+    if (at >= 0)
+        d = d.slice(at + 1);
+    return d.replace(/\.+$/, "");
+}
+/**
+ * Infer a recipient's ESP from its email domain, DETERMINISTICALLY, for the
+ * well-known consumer domains (gmail/googlemail → google; outlook/hotmail/live/
+ * msn → microsoft). Returns null for any other domain — the caller then resolves
+ * the ESP via a cached MX lookup (custom domains fronted by Google Workspace /
+ * Microsoft 365 aren't decidable from the domain string alone). Pure and
+ * side-effect-free so it's the single source of truth for the deterministic map.
+ */
+export function inferRecipientEsp(domain) {
+    const d = normalizeRecipientDomain(domain);
+    if (!d)
+        return null;
+    if (GOOGLE_CONSUMER_DOMAINS.has(d))
+        return "google";
+    if (MICROSOFT_CONSUMER_DOMAINS.has(d))
+        return "microsoft";
+    return null;
+}
+/**
+ * Map a domain's resolved MX exchange hostnames to an ESP family, for the MX-cache
+ * path (custom domains on Google Workspace / Microsoft 365). Google MX hosts end
+ * in `google.com` / `googlemail.com` (e.g. aspmx.l.google.com); Microsoft 365 MX
+ * hosts end in `outlook.com` / `protection.outlook.com` (e.g.
+ * acme-com.mail.protection.outlook.com). Returns null when no host matches either
+ * family. Pure so both the resolver and its tests share one mapping.
+ */
+export function espFromMxHosts(hosts) {
+    if (!Array.isArray(hosts))
+        return null;
+    for (const raw of hosts) {
+        if (typeof raw !== "string")
+            continue;
+        const host = raw.trim().toLowerCase().replace(/\.+$/, "");
+        if (!host)
+            continue;
+        if (host.endsWith("google.com") || host.endsWith("googlemail.com"))
+            return "google";
+        if (host.endsWith("outlook.com") || host.endsWith("protection.outlook.com"))
+            return "microsoft";
+    }
+    return null;
+}
 /**
  * row_values keys an enrollment's phone number may live under, in
  * send-precedence order, for WhatsApp sends. The enroll path resolves the FIRST
@@ -151,6 +245,16 @@ export function whatsAppAttendeeIdFromRow(rowValues, phoneColumnKey) {
 }
 /** Base content + up to this many alternates per A/B step (base counts as variant "a"). */
 export const MAX_STEP_VARIANTS = 5;
+/**
+ * Metrics a step's opt-in auto-winner (A/B auto-optimize) can decide on. `reply`
+ * is the only metric today — open/click require tracking domains (a gated,
+ * separate capability), so the reversible auto-winner ships on reply first.
+ */
+export const SEQUENCE_AUTO_OPTIMIZE_METRICS = ["reply"];
+/** Default send floor per variant before the auto-winner may decide. */
+export const DEFAULT_AUTO_OPTIMIZE_MIN_SENDS = 100;
+/** Default conversion (reply) floor per variant before the auto-winner may decide. */
+export const DEFAULT_AUTO_OPTIMIZE_MIN_CONVERSIONS = 5;
 export const SEQUENCE_STEP_KINDS = [
     // linkedin channel (native dispatch)
     "visit_profile",
@@ -158,6 +262,10 @@ export const SEQUENCE_STEP_KINDS = [
     "wait_for_connection",
     "message",
     "inmail",
+    "follow",
+    "like_post",
+    "comment_post",
+    "withdraw_invite",
     // email channel
     "email_send",
     "email_reply",
@@ -180,10 +288,12 @@ export const SEQUENCE_STEP_KINDS = [
  * - already_connected: resolve the lead's current 1st-degree state at entry and
  *   route connected → then_id, not → else_id (no waiting).
  */
-export const SEQUENCE_CONNECTION_BRANCH_CONDITIONS = ["connection_accepted", "already_connected"];
+export const SEQUENCE_CONNECTION_BRANCH_CONDITIONS = ["connection_accepted", "already_connected", "open_profile"];
 const MAX_SEQUENCE_STEPS = 50;
 const MAX_TEMPLATE_LENGTH = 8_000;
 const MAX_NOTE_LENGTH = 300;
+/** Cap on step Cc/Bcc recipients — a handful of fixed addresses (e.g. an AE, a CRM drop), not a list. */
+const MAX_STEP_EMAIL_RECIPIENTS = 10;
 const ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
 /** Which channel a step executes on, or null for channel-agnostic control steps. */
 export function sequenceStepChannel(step) {
@@ -247,8 +357,13 @@ export function validateSequenceDefinition(input, options = {}) {
     // (email_send/email_reply) and is NOT delegated to an Instantly campaign (no
     // email_enroll/email_move/email_stop steps) — that gates a wait_for_signal or
     // signal-branch on those signals would silently always time out / always take
-    // the else arm. Reject it at write time so create/update report the dead gate.
-    reportNativeEngagementGates(normalized, issues);
+    // the else arm. Reject it at write time so create/update report the dead gate --
+    // UNLESS the sequence has native open/click tracking enabled, in which case a
+    // native send DOES accumulate email_opened/email_clicked (from the /api/t/*
+    // pixel + link routes), so those gates are legitimate and permitted.
+    if (!options.nativeTrackingEnabled) {
+        reportNativeEngagementGates(normalized, issues);
+    }
     if (issues.length > 0) {
         throw new OxygenError("invalid_sequence", `Sequence definition is invalid: ${issues.map((i) => `${i.path}: ${i.message}`).join("; ")}`, { details: { issues }, exitCode: 1 });
     }
@@ -372,18 +487,24 @@ raw, index, options, issues) {
         case "message": {
             const template = requiredTemplate(raw.template, `${path}.template`, issues);
             const variants = normalizeVariants(raw.variants, `${path}.variants`, ["template"], issues);
+            const autoOptimize = normalizeAutoOptimize(raw.auto_optimize, `${path}.auto_optimize`, variants, issues);
+            const attachments = normalizeLinkedInAttachments(raw.attachments, `${path}.attachments`, issues);
             return {
                 id, channel: "linkedin", kind: "message", template: template ?? "",
                 ...(variants ? { variants: variants } : {}),
+                ...(autoOptimize ? { auto_optimize: autoOptimize } : {}),
+                ...(attachments ? { attachments } : {}),
             };
         }
         case "inmail": {
             const subject = requiredTemplate(raw.subject_template, `${path}.subject_template`, issues);
             const template = requiredTemplate(raw.template, `${path}.template`, issues);
             const variants = normalizeVariants(raw.variants, `${path}.variants`, ["subject_template", "template"], issues);
+            const autoOptimize = normalizeAutoOptimize(raw.auto_optimize, `${path}.auto_optimize`, variants, issues);
             return {
                 id, channel: "linkedin", kind: "inmail", subject_template: subject ?? "", template: template ?? "",
                 ...(variants ? { variants: variants } : {}),
+                ...(autoOptimize ? { auto_optimize: autoOptimize } : {}),
             };
         }
         case "email_enroll": {
@@ -402,21 +523,37 @@ raw, index, options, issues) {
         case "email_send": {
             const subject = requiredTemplate(raw.subject_template, `${path}.subject_template`, issues);
             const body = requiredTemplate(raw.body_template, `${path}.body_template`, issues);
-            const variants = normalizeVariants(raw.variants, `${path}.variants`, ["subject_template", "body_template"], issues);
+            const bodyHtml = optionalTemplate(raw.body_html_template, `${path}.body_html_template`, MAX_TEMPLATE_LENGTH, issues);
+            const variants = normalizeVariants(raw.variants, `${path}.variants`, ["subject_template", "body_template", "body_html_template"], issues);
+            const autoOptimize = normalizeAutoOptimize(raw.auto_optimize, `${path}.auto_optimize`, variants, issues);
+            const cc = optionalEmailList(raw.cc, `${path}.cc`, issues);
+            const bcc = optionalEmailList(raw.bcc, `${path}.bcc`, issues);
             const sendWindow = normalizeSendWindow(raw.send_window, `${path}.send_window`, issues);
             return {
                 id, channel: "email", kind: "email_send", subject_template: subject ?? "", body_template: body ?? "",
+                ...(bodyHtml !== undefined ? { body_html_template: bodyHtml } : {}),
+                ...(cc ? { cc } : {}),
+                ...(bcc ? { bcc } : {}),
                 ...(variants ? { variants: variants } : {}),
+                ...(autoOptimize ? { auto_optimize: autoOptimize } : {}),
                 ...(sendWindow ? { send_window: sendWindow } : {}),
             };
         }
         case "email_reply": {
             const body = requiredTemplate(raw.body_template, `${path}.body_template`, issues);
-            const variants = normalizeVariants(raw.variants, `${path}.variants`, ["body_template"], issues);
+            const bodyHtml = optionalTemplate(raw.body_html_template, `${path}.body_html_template`, MAX_TEMPLATE_LENGTH, issues);
+            const variants = normalizeVariants(raw.variants, `${path}.variants`, ["body_template", "body_html_template"], issues);
+            const autoOptimize = normalizeAutoOptimize(raw.auto_optimize, `${path}.auto_optimize`, variants, issues);
+            const cc = optionalEmailList(raw.cc, `${path}.cc`, issues);
+            const bcc = optionalEmailList(raw.bcc, `${path}.bcc`, issues);
             const sendWindow = normalizeSendWindow(raw.send_window, `${path}.send_window`, issues);
             return {
                 id, channel: "email", kind: "email_reply", body_template: body ?? "",
+                ...(bodyHtml !== undefined ? { body_html_template: bodyHtml } : {}),
+                ...(cc ? { cc } : {}),
+                ...(bcc ? { bcc } : {}),
                 ...(variants ? { variants: variants } : {}),
+                ...(autoOptimize ? { auto_optimize: autoOptimize } : {}),
                 ...(sendWindow ? { send_window: sendWindow } : {}),
             };
         }
@@ -425,9 +562,11 @@ raw, index, options, issues) {
         case "whatsapp_message": {
             const template = requiredTemplate(raw.template, `${path}.template`, issues);
             const variants = normalizeVariants(raw.variants, `${path}.variants`, ["template"], issues);
+            const autoOptimize = normalizeAutoOptimize(raw.auto_optimize, `${path}.auto_optimize`, variants, issues);
             return {
                 id, channel: "whatsapp", kind: "whatsapp_message", template: template ?? "",
                 ...(variants ? { variants: variants } : {}),
+                ...(autoOptimize ? { auto_optimize: autoOptimize } : {}),
             };
         }
         case "wait": {
@@ -436,11 +575,13 @@ raw, index, options, issues) {
             if ((days ?? 0) + (hours ?? 0) <= 0) {
                 issues.push({ path, message: "A wait step needs days and/or hours totaling at least 1 hour." });
             }
+            const jitterHours = optionalWaitJitterHours(raw.jitter_hours, `${path}.jitter_hours`, issues);
             return {
                 id,
                 kind: "wait",
                 ...(days !== undefined ? { days } : {}),
                 ...(hours !== undefined ? { hours } : {}),
+                ...(jitterHours !== undefined ? { jitter_hours: jitterHours } : {}),
             };
         }
         case "wait_for_signal": {
@@ -494,12 +635,80 @@ raw, index, options, issues) {
                 else: normalizeTargetRef(raw.else ?? raw.else_id, `${path}.else`, issues),
             };
         }
+        case "follow":
+            return { id, channel: "linkedin", kind: "follow" };
+        case "like_post": {
+            const reaction = typeof raw.reaction === "string" && LINKEDIN_POST_REACTION_SET.has(raw.reaction)
+                ? raw.reaction
+                : undefined;
+            if (raw.reaction !== undefined && reaction === undefined) {
+                issues.push({ path: `${path}.reaction`, message: `reaction must be one of: ${[...LINKEDIN_POST_REACTION_SET].join(", ")}.` });
+            }
+            const recency = optionalPostRecencyDays(raw.post_recency_days, `${path}.post_recency_days`, issues);
+            return {
+                id, channel: "linkedin", kind: "like_post",
+                ...(reaction ? { reaction: reaction } : {}),
+                ...(recency !== undefined ? { post_recency_days: recency } : {}),
+                ...(raw.on_no_post === "stop" ? { on_no_post: "stop" } : {}),
+            };
+        }
+        case "comment_post": {
+            // ai_prompt (AI-generated comments) is a planned follow-up; today a
+            // comment_post step needs a text_template (with {{column}} interpolation).
+            const textTemplate = requiredTemplate(raw.text_template, `${path}.text_template`, issues);
+            const recency = optionalPostRecencyDays(raw.post_recency_days, `${path}.post_recency_days`, issues);
+            return {
+                id, channel: "linkedin", kind: "comment_post",
+                text_template: textTemplate ?? "",
+                ...(recency !== undefined ? { post_recency_days: recency } : {}),
+                ...(raw.on_no_post === "stop" ? { on_no_post: "stop" } : {}),
+            };
+        }
+        case "withdraw_invite":
+            return { id, channel: "linkedin", kind: "withdraw_invite" };
         case "stop":
             return { id, kind: "stop" };
         default:
             return null;
     }
 }
+const LINKEDIN_POST_REACTION_SET = new Set(["like", "celebrate", "support", "funny", "love", "insightful"]);
+/** Max attachments per LinkedIn message (kept small — LinkedIn is not a file host). */
+const MAX_LINKEDIN_ATTACHMENTS = 5;
+/**
+ * Normalize the optional `attachments` on a message step into `{url, name?}[]`.
+ * Each needs an http(s) url; a missing/blank url drops the entry. Returns
+ * undefined when there are no valid attachments (field omitted).
+ */
+function normalizeLinkedInAttachments(raw, path, issues) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!Array.isArray(raw)) {
+        issues.push({ path, message: "attachments must be an array of { url, name? }." });
+        return undefined;
+    }
+    const out = [];
+    for (const entry of raw.slice(0, MAX_LINKEDIN_ATTACHMENTS)) {
+        const record = entry && typeof entry === "object" ? entry : {};
+        const url = typeof record.url === "string" ? record.url.trim() : "";
+        // Lenient: silently drop an entry without a valid http(s) url rather than
+        // rejecting the whole sequence for one bad attachment.
+        if (!/^https?:\/\//i.test(url))
+            continue;
+        const name = typeof record.name === "string" && record.name.trim() ? record.name.trim() : undefined;
+        out.push(name ? { url, name } : { url });
+    }
+    return out.length > 0 ? out : undefined;
+}
+/** Optional post-recency window (1..365 days) for like_post / comment_post steps. */
+function optionalPostRecencyDays(raw, path, issues) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    const value = positiveInt(raw, path, issues);
+    if (value === undefined)
+        return undefined;
+    return Math.min(value, 365);
+}
 function channelForKind(kind) {
     if (kind === "wait" || kind === "wait_for_signal" || kind === "branch" || kind === "stop")
         return null;
@@ -599,6 +808,36 @@ function optionalTemplate(value, path, maxLength, issues) {
     }
     return value;
 }
+/**
+ * Validate an optional Cc/Bcc list on an email step: a single address or an array of
+ * addresses, each a single-line address-shaped string (has '@', no whitespace, no
+ * CR/LF — header-injection-safe, mirroring the ad-hoc send route). Lowercased and
+ * de-duplicated; capped at MAX_STEP_EMAIL_RECIPIENTS. Returns undefined when absent or
+ * once every entry is dropped (so an empty list never rides the payload).
+ */
+function optionalEmailList(value, path, issues) {
+    if (value === undefined || value === null)
+        return undefined;
+    const raw = Array.isArray(value) ? value : [value];
+    if (raw.length > MAX_STEP_EMAIL_RECIPIENTS) {
+        issues.push({ path, message: `at most ${MAX_STEP_EMAIL_RECIPIENTS} addresses.` });
+    }
+    const out = [];
+    raw.slice(0, MAX_STEP_EMAIL_RECIPIENTS).forEach((entry, i) => {
+        if (typeof entry !== "string" || !entry.trim()) {
+            issues.push({ path: `${path}[${i}]`, message: "each address must be a non-empty string." });
+            return;
+        }
+        const address = entry.trim().toLowerCase();
+        if (/[\r\n]/.test(address) || /\s/.test(address) || !address.includes("@")) {
+            issues.push({ path: `${path}[${i}]`, message: "must be a single email address (no spaces or line breaks)." });
+            return;
+        }
+        if (!out.includes(address))
+            out.push(address);
+    });
+    return out.length > 0 ? out : undefined;
+}
 function optionalString(value, path, issues) {
     if (value === undefined || value === null)
         return undefined;
@@ -626,26 +865,76 @@ function optionalNonNegativeInt(value, path, issues) {
     }
     return num;
 }
-/** Total delay in milliseconds a wait step introduces. */
+/**
+ * A wait step's optional jitter window in whole hours: a non-negative integer,
+ * capped at MAX_WAIT_JITTER_HOURS. 0 is treated as "no jitter" (field omitted).
+ */
+function optionalWaitJitterHours(value, path, issues) {
+    const hours = optionalNonNegativeInt(value, path, issues);
+    if (hours === undefined || hours === 0)
+        return undefined;
+    if (hours > MAX_WAIT_JITTER_HOURS) {
+        issues.push({ path, message: `must be at most ${MAX_WAIT_JITTER_HOURS} hours.` });
+        return undefined;
+    }
+    return hours;
+}
+/** Upper bound on a wait step's optional jitter window (a week — keep it a nudge, not a reschedule). */
+const MAX_WAIT_JITTER_HOURS = 168;
+/** Total base delay in milliseconds a wait step introduces (no jitter). */
 export function sequenceWaitStepDelayMs(step) {
     const days = step.days ?? 0;
     const hours = step.hours ?? 0;
     return (days * 24 + hours) * 60 * 60 * 1000;
 }
-/** Render a {{column}} template against a row's values (reuses the LinkedIn impl). */
-export function renderSequenceTemplate(template, values) {
-    return renderLinkedInTemplate(template, values);
+/**
+ * Deterministic jitter (ms) a wait step adds for one enrollment, in
+ * [0, jitter_hours) hours. Seeded by the enrollment id + step id through the
+ * shared FNV hash (hashVariantKey) — the SAME (enrollment, step) always resolves
+ * to the same offset, so it's replayable across retries/crash-replays and never
+ * uses Math.random. 0/absent jitter_hours → 0. Resolution is minute-grained so a
+ * batch spreads smoothly across the window rather than landing on the hour.
+ */
+export function sequenceWaitStepJitterMs(step, enrollmentId) {
+    const jitterHours = step.jitter_hours ?? 0;
+    if (jitterHours <= 0)
+        return 0;
+    const windowMinutes = Math.floor(jitterHours * 60);
+    if (windowMinutes <= 0)
+        return 0;
+    const offsetMinutes = hashVariantKey(`${enrollmentId}:${step.id}:wait-jitter`) % windowMinutes;
+    return offsetMinutes * 60 * 1000;
+}
+/**
+ * Full delay (base + deterministic jitter) a wait step introduces for one
+ * enrollment. The dispatch planner uses this to compute a resume time that
+ * spreads a same-instant batch across the jitter window.
+ */
+export function sequenceWaitStepDelayWithJitterMs(step, enrollmentId) {
+    return sequenceWaitStepDelayMs(step) + sequenceWaitStepJitterMs(step, enrollmentId);
+}
+/**
+ * Render a sequence-copy template against a row's values. Delegates to the shared
+ * deterministic engine (sequence-template.ts): `{{column}}` substitution plus
+ * `{{column|fallback}}`, `{{RANDOM|…}}` spintax, and `{% if … %}` conditionals.
+ * Pass `{ seed }` to make spintax choices replayable across retries/crash-replays.
+ */
+export function renderSequenceTemplate(template, values, options) {
+    return renderTemplate(template, values, options);
 }
-/** Column keys referenced by {{...}} placeholders across every step's copy. */
+/**
+ * Column keys referenced across every step's copy — including keys nested inside
+ * spintax options, inline fallbacks, and conditional conditions/branches (via the
+ * shared engine's scanner), so the start preview's variable-resolution check
+ * catches them wherever they appear.
+ */
 export function sequenceTemplateVariables(definition) {
     const vars = new Set();
     const scan = (template) => {
         if (!template)
             return;
-        for (const match of template.matchAll(/\{\{\s*([\w.]+)\s*\}\}/g)) {
-            if (match[1])
-                vars.add(match[1]);
-        }
+        for (const key of templateColumnKeys(template))
+            vars.add(key);
     };
     for (const step of definition.steps) {
         if (step.kind === "invite")
@@ -681,19 +970,19 @@ const VARIANT_ALPHABET = "abcdefghijklmnopqrstuvwxyz";
 export function sequenceVariantLabel(index) {
     return VARIANT_ALPHABET[index % VARIANT_ALPHABET.length] ?? "a";
 }
-/** Deterministic, replayable FNV-1a hash → uint32. Stable across processes. */
-function hashVariantKey(value) {
-    let hash = 0x811c9dc5;
-    for (let i = 0; i < value.length; i += 1) {
-        hash ^= value.charCodeAt(i);
-        hash = Math.imul(hash, 0x01000193);
-    }
-    return hash >>> 0;
-}
 function baseVariantContent(step) {
     switch (step.kind) {
-        case "email_send": return { subject_template: step.subject_template, body_template: step.body_template };
-        case "email_reply": return { body_template: step.body_template };
+        case "email_send": return {
+            subject_template: step.subject_template,
+            body_template: step.body_template,
+            // Include the HTML body so its {{column}} refs are scanned by
+            // sequenceTemplateVariables (the start preview's variable-resolution check).
+            ...(step.body_html_template ? { body_html_template: step.body_html_template } : {}),
+        };
+        case "email_reply": return {
+            body_template: step.body_template,
+            ...(step.body_html_template ? { body_html_template: step.body_html_template } : {}),
+        };
         case "message": return { template: step.template };
         case "whatsapp_message": return { template: step.template };
         case "inmail": return { subject_template: step.subject_template, template: step.template };
@@ -724,15 +1013,78 @@ export function sequenceStepVariantCount(step) {
  * (key, step) always resolves to the same variant — replayable, evenly
  * distributed, and previewable in a dry run before any send. `key` is the
  * enrollment id.
+ *
+ * When `pausedVariantIds` is supplied (the auto-winner's paused set for this
+ * step), those variants are skipped and the deterministic split is RE-NORMALIZED
+ * over the remaining active variants — so pausing a losing variant shifts its
+ * share onto the survivors, still deterministically. If every variant would be
+ * paused (never expected — the winner is never paused), it fails safe by ignoring
+ * the paused set rather than stranding the step with nothing to send.
  */
-export function selectStepVariant(step, key) {
+export function selectStepVariant(step, key, options) {
     const contents = sequenceStepVariantContents(step);
     if (contents.length === 0)
         return { variantId: "a", index: 0, content: {} };
-    const index = contents.length > 1 ? hashVariantKey(`${key}:${step.id}`) % contents.length : 0;
+    const paused = options?.pausedVariantIds ? new Set(options.pausedVariantIds) : null;
+    let activeIndices = contents.map((_, i) => i);
+    if (paused && paused.size > 0) {
+        const survivors = activeIndices.filter((i) => !paused.has(sequenceVariantLabel(i)));
+        if (survivors.length > 0)
+            activeIndices = survivors;
+    }
+    const pick = activeIndices.length > 1
+        ? activeIndices[hashVariantKey(`${key}:${step.id}`) % activeIndices.length]
+        : activeIndices[0];
+    const index = pick ?? 0;
     const content = contents[index] ?? contents[0] ?? {};
     return { variantId: sequenceVariantLabel(index), index, content };
 }
+/** The step's opt-in auto-winner config, or null when it carries none. */
+export function stepAutoOptimizeConfig(step) {
+    return step.auto_optimize ?? null;
+}
+/**
+ * Decide the A/B auto-winner for one step from per-variant conversion counts.
+ * Pure. Returns null (no decision yet) unless: at least two variants are still
+ * active (not already paused), EVERY active variant has cleared BOTH thresholds
+ * (min_sends_per_variant AND min_conversions — the min-conversion floor), and the
+ * best conversion rate is strictly ahead of at least one other variant (a tie
+ * pauses nothing). When it decides, it pauses every active variant below the best
+ * rate and stamps evidence. Reversible: a manual reset reactivates a paused
+ * variant, and this re-decides from the survivors on the next pass.
+ */
+export function decideVariantAutoWinner(stats, config, decidedAt, alreadyPaused = []) {
+    const paused = new Set(alreadyPaused);
+    const active = stats.filter((s) => !paused.has(s.variantId));
+    if (active.length < 2)
+        return null;
+    const ready = active.every((s) => s.sends >= config.min_sends_per_variant && s.conversions >= config.min_conversions);
+    if (!ready)
+        return null;
+    const withRate = active.map((s) => ({ ...s, rate: s.sends > 0 ? s.conversions / s.sends : 0 }));
+    const bestRate = Math.max(...withRate.map((s) => s.rate));
+    const winner = withRate.find((s) => s.rate === bestRate);
+    if (!winner)
+        return null;
+    const pause = withRate.filter((s) => s.rate < bestRate).map((s) => s.variantId);
+    if (pause.length === 0)
+        return null; // a tie at the top — nothing to pause yet
+    return {
+        pause,
+        winnerId: winner.variantId,
+        evidence: {
+            metric: config.metric,
+            variants: withRate.map((s) => ({
+                variant_id: s.variantId,
+                sends: s.sends,
+                conversions: s.conversions,
+                rate: Number(s.rate.toFixed(4)),
+            })),
+            winner_id: winner.variantId,
+            decided_at: decidedAt,
+        },
+    };
+}
 // ===== Send windows =====
 function hhmmToMinutes(value) {
     const match = /^(\d{1,2}):(\d{2})$/.exec(value.trim());
@@ -841,6 +1193,49 @@ function normalizeVariants(raw, path, fields, issues) {
     });
     return out.length > 0 ? out : undefined;
 }
+/** Upper bounds on the auto-optimize thresholds (guard against fat-finger values). */
+const MAX_AUTO_OPTIMIZE_MIN_SENDS = 100_000;
+const MAX_AUTO_OPTIMIZE_MIN_CONVERSIONS = 100_000;
+/**
+ * Validate + normalize a step's optional `auto_optimize` config. Only meaningful
+ * on a step that actually has A/B alternates (variants.length >= 1, i.e. ≥ 2 total
+ * variants) — configuring it on a single-variant step is a dead knob, so reject
+ * it. `metric` must be a supported metric (reply today); the thresholds default to
+ * DEFAULT_AUTO_OPTIMIZE_* and must be positive integers within sane bounds.
+ * Returns undefined when absent (field omitted).
+ */
+function normalizeAutoOptimize(raw, path, variants, issues) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!isRecord(raw)) {
+        issues.push({ path, message: "auto_optimize must be an object." });
+        return undefined;
+    }
+    if (!variants || variants.length === 0) {
+        issues.push({ path, message: "auto_optimize needs at least one A/B alternate (2+ variants) to pick a winner from." });
+        return undefined;
+    }
+    const metric = raw.metric;
+    if (typeof metric !== "string" || !SEQUENCE_AUTO_OPTIMIZE_METRICS.includes(metric)) {
+        issues.push({ path: `${path}.metric`, message: `metric must be one of: ${SEQUENCE_AUTO_OPTIMIZE_METRICS.join(", ")}.` });
+        return undefined;
+    }
+    const minSends = raw.min_sends_per_variant === undefined || raw.min_sends_per_variant === null
+        ? DEFAULT_AUTO_OPTIMIZE_MIN_SENDS
+        : positiveInt(raw.min_sends_per_variant, `${path}.min_sends_per_variant`, issues) ?? DEFAULT_AUTO_OPTIMIZE_MIN_SENDS;
+    const minConversions = raw.min_conversions === undefined || raw.min_conversions === null
+        ? DEFAULT_AUTO_OPTIMIZE_MIN_CONVERSIONS
+        : positiveInt(raw.min_conversions, `${path}.min_conversions`, issues) ?? DEFAULT_AUTO_OPTIMIZE_MIN_CONVERSIONS;
+    if (minSends > MAX_AUTO_OPTIMIZE_MIN_SENDS) {
+        issues.push({ path: `${path}.min_sends_per_variant`, message: `must be at most ${MAX_AUTO_OPTIMIZE_MIN_SENDS}.` });
+        return undefined;
+    }
+    if (minConversions > MAX_AUTO_OPTIMIZE_MIN_CONVERSIONS) {
+        issues.push({ path: `${path}.min_conversions`, message: `must be at most ${MAX_AUTO_OPTIMIZE_MIN_CONVERSIONS}.` });
+        return undefined;
+    }
+    return { metric: metric, min_sends_per_variant: minSends, min_conversions: minConversions };
+}
 function normalizeSendWindowConfiguredTimezone(raw, path, issues) {
     const timezone = typeof raw.timezone === "string" && raw.timezone.trim() ? raw.timezone.trim() : undefined;
     if (!timezone)

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

@@ -1,2 +1,2 @@
-export declare const OXYGEN_VERSION = "1.246.0";
+export declare const OXYGEN_VERSION = "1.263.0";
 export declare const OXYGEN_MINIMUM_CLI_VERSION = "1.181.0";

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

@@ -1,4 +1,4 @@
-export const OXYGEN_VERSION = "1.246.0";
+export const OXYGEN_VERSION = "1.263.0";
 // Bump this only when deployed CLI/API contracts require a newer CLI.
 // 1.181.0: paid table action runs and background columns run require
 // approved=true in addition to max_credits; older CLIs cannot send the flag.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxygen-agent/cli",
-  "version": "1.246.0",
+  "version": "1.263.0",
   "private": false,
   "license": "UNLICENSED",
   "type": "module",