@oxygen-agent/cli 1.246.0 → 1.263.0

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

@@ -1,3 +1,4 @@
+import { type RenderTemplateOptions } 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
@@ -67,6 +68,54 @@ export declare const SEQUENCE_EMAIL_COLUMN_KEYS: readonly ["email", "email_addre
  * Returns the trimmed raw value (callers normalize/lowercase as needed) or null.
  */
 export declare function recipientEmailFromRow(rowValues: Record<string, unknown> | null | undefined): string | 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 declare const ESP_MATCHING_MODES: readonly ["off", "prefer", "strict"];
+export type EspMatchingMode = (typeof ESP_MATCHING_MODES)[number];
+export declare const DEFAULT_ESP_MATCHING_MODE: EspMatchingMode;
+export declare function isEspMatchingMode(value: unknown): value is EspMatchingMode;
+/**
+ * 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 declare function validateEspMatchingSetting(value: unknown): void;
+/**
+ * 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 declare const RECIPIENT_ESPS: readonly ["google", "microsoft"];
+export type RecipientEsp = (typeof RECIPIENT_ESPS)[number];
+/**
+ * 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 declare function inferRecipientEsp(domain: string | null | undefined): RecipientEsp | 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 declare function espFromMxHosts(hosts: readonly string[] | null | undefined): RecipientEsp | 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
@@ -118,7 +167,32 @@ export type SequenceSendWindow = {
 };
 /** Base content + up to this many alternates per A/B step (base counts as variant "a"). */
 export declare const MAX_STEP_VARIANTS = 5;
-export declare const SEQUENCE_STEP_KINDS: readonly ["visit_profile", "invite", "wait_for_connection", "message", "inmail", "email_send", "email_reply", "email_enroll", "email_move", "email_stop", "whatsapp_message", "wait", "wait_for_signal", "branch", "stop"];
+/**
+ * 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 declare const SEQUENCE_AUTO_OPTIMIZE_METRICS: readonly ["reply"];
+export type SequenceAutoOptimizeMetric = (typeof SEQUENCE_AUTO_OPTIMIZE_METRICS)[number];
+/** Default send floor per variant before the auto-winner may decide. */
+export declare const DEFAULT_AUTO_OPTIMIZE_MIN_SENDS = 100;
+/** Default conversion (reply) floor per variant before the auto-winner may decide. */
+export declare const DEFAULT_AUTO_OPTIMIZE_MIN_CONVERSIONS = 5;
+/**
+ * Opt-in auto-winner config on a variant-bearing step. When present, once EVERY
+ * still-active variant of the step has cleared BOTH thresholds
+ * (min_sends_per_variant sends AND min_conversions conversions), the worker's
+ * auto-winner pass pauses the statistically-losing variant(s) on `metric`,
+ * reversibly, stamping evidence. Absent → the step's A/B test runs forever (no
+ * auto pause). The pause is written to ox_sequencer.sequence_variant_state and
+ * can be undone by a manual reset.
+ */
+export type SequenceAutoOptimizeConfig = {
+    metric: SequenceAutoOptimizeMetric;
+    min_sends_per_variant: number;
+    min_conversions: number;
+};
+export declare const SEQUENCE_STEP_KINDS: readonly ["visit_profile", "invite", "wait_for_connection", "message", "inmail", "follow", "like_post", "comment_post", "withdraw_invite", "email_send", "email_reply", "email_enroll", "email_move", "email_stop", "whatsapp_message", "wait", "wait_for_signal", "branch", "stop"];
 export type SequenceStepKind = (typeof SEQUENCE_STEP_KINDS)[number];
 export type SequenceLinkedInVisitProfileStep = {
     id: string;
@@ -139,6 +213,11 @@ export type SequenceLinkedInWaitForConnectionStep = {
     timeout_days: number;
     on_timeout: "stop" | "continue";
 };
+/** A file to attach to a LinkedIn message (image / document), fetched at send time. */
+export type SequenceLinkedInAttachment = {
+    url: string;
+    name?: string;
+};
 export type SequenceLinkedInMessageStep = {
     id: string;
     channel: "linkedin";
@@ -148,6 +227,10 @@ export type SequenceLinkedInMessageStep = {
     variants?: {
         template?: string;
     }[];
+    /** Opt-in reversible auto-winner over the variants (reply metric). */
+    auto_optimize?: SequenceAutoOptimizeConfig;
+    /** Files attached to the message (≤ a few, fetched at dispatch). */
+    attachments?: SequenceLinkedInAttachment[];
 };
 export type SequenceLinkedInInMailStep = {
     id: string;
@@ -160,6 +243,35 @@ export type SequenceLinkedInInMailStep = {
         subject_template?: string;
         template?: string;
     }[];
+    /** Opt-in reversible auto-winner over the variants (reply metric). */
+    auto_optimize?: SequenceAutoOptimizeConfig;
+};
+export type SequenceLinkedInFollowStep = {
+    id: string;
+    channel: "linkedin";
+    kind: "follow";
+};
+export type SequenceLinkedInLikePostStep = {
+    id: string;
+    channel: "linkedin";
+    kind: "like_post";
+    reaction?: "like" | "celebrate" | "support" | "funny" | "love" | "insightful";
+    post_recency_days?: number;
+    on_no_post?: "stop";
+};
+export type SequenceLinkedInCommentPostStep = {
+    id: string;
+    channel: "linkedin";
+    kind: "comment_post";
+    text_template?: string;
+    ai_prompt?: string;
+    post_recency_days?: number;
+    on_no_post?: "stop";
+};
+export type SequenceLinkedInWithdrawInviteStep = {
+    id: string;
+    channel: "linkedin";
+    kind: "withdraw_invite";
 };
 export type SequenceEmailEnrollStep = {
     id: string;
@@ -190,13 +302,21 @@ export type SequenceEmailSendStep = {
     kind: "email_send";
     /** Subject line. Supports {{column}} interpolation. */
     subject_template: string;
-    /** Body. Supports {{column}} interpolation. */
+    /** Body (plain text). Supports {{column}} interpolation. */
     body_template: string;
-    /** A/B alternates over subject/body; the base is variant "a". */
+    /** Optional HTML body (B-W2): renders the send as multipart/alternative. Supports {{column}}. */
+    body_html_template?: string;
+    /** Static Cc / Bcc recipients (fixed addresses, not templated). */
+    cc?: string[];
+    bcc?: string[];
+    /** A/B alternates over subject/body/html; the base is variant "a". */
     variants?: {
         subject_template?: string;
         body_template?: string;
+        body_html_template?: string;
     }[];
+    /** Opt-in reversible auto-winner over the variants (reply metric). */
+    auto_optimize?: SequenceAutoOptimizeConfig;
     /** Per-step send window (overrides the sequence-level email_send_window). */
     send_window?: SequenceSendWindow;
 };
@@ -205,12 +325,20 @@ export type SequenceEmailReplyStep = {
     id: string;
     channel: "email";
     kind: "email_reply";
-    /** Reply body. Supports {{column}} interpolation. */
+    /** Reply body (plain text). Supports {{column}} interpolation. */
     body_template: string;
-    /** A/B alternates over the reply body; the base is variant "a". */
+    /** Optional HTML reply body (B-W2): renders the reply as multipart/alternative. Supports {{column}}. */
+    body_html_template?: string;
+    /** Static Cc / Bcc recipients (fixed addresses, not templated). */
+    cc?: string[];
+    bcc?: string[];
+    /** A/B alternates over the reply body/html; the base is variant "a". */
     variants?: {
         body_template?: string;
+        body_html_template?: string;
     }[];
+    /** Opt-in reversible auto-winner over the variants (reply metric). */
+    auto_optimize?: SequenceAutoOptimizeConfig;
     /** Per-step send window (overrides the sequence-level email_send_window). */
     send_window?: SequenceSendWindow;
 };
@@ -230,12 +358,23 @@ export type SequenceWhatsAppMessageStep = {
     variants?: {
         template?: string;
     }[];
+    /** Opt-in reversible auto-winner over the variants (reply metric). */
+    auto_optimize?: SequenceAutoOptimizeConfig;
 };
 export type SequenceWaitStep = {
     id: string;
     kind: "wait";
     days?: number;
     hours?: number;
+    /**
+     * Optional deterministic jitter: spread the resume time of otherwise-identical
+     * enrollments across a [0, jitter_hours) window so a batch enrolled at the same
+     * instant doesn't fire its next step in a detectable synchronized burst
+     * (EmailBison/Instantly "randomize delay" parity). Seeded by the enrollment id
+     * (via the shared FNV hash), so it's replayable across retries/crash-replays and
+     * previewable — never Math.random. 0/absent → no jitter.
+     */
+    jitter_hours?: number;
 };
 export type SequenceWaitForSignalStep = {
     id: string;
@@ -254,7 +393,7 @@ export type SequenceWaitForSignalStep = {
  * - already_connected: resolve the lead's current 1st-degree state at entry and
  *   route connected → then_id, not → else_id (no waiting).
  */
-export declare const SEQUENCE_CONNECTION_BRANCH_CONDITIONS: readonly ["connection_accepted", "already_connected"];
+export declare const SEQUENCE_CONNECTION_BRANCH_CONDITIONS: readonly ["connection_accepted", "already_connected", "open_profile"];
 export type SequenceConnectionBranchCondition = (typeof SEQUENCE_CONNECTION_BRANCH_CONDITIONS)[number];
 /**
  * A branch has two flavors, discriminated by the runtime type of `condition`:
@@ -313,7 +452,7 @@ export type SequenceSignalCondition = {
 } | {
     not: SequenceSignalCondition;
 };
-export type SequenceStep = SequenceLinkedInVisitProfileStep | SequenceLinkedInInviteStep | SequenceLinkedInWaitForConnectionStep | SequenceLinkedInMessageStep | SequenceLinkedInInMailStep | SequenceEmailSendStep | SequenceEmailReplyStep | SequenceEmailEnrollStep | SequenceEmailMoveStep | SequenceEmailStopStep | SequenceWhatsAppMessageStep | SequenceWaitStep | SequenceWaitForSignalStep | SequenceBranchStep | SequenceStopStep;
+export type SequenceStep = SequenceLinkedInVisitProfileStep | SequenceLinkedInInviteStep | SequenceLinkedInWaitForConnectionStep | SequenceLinkedInMessageStep | SequenceLinkedInInMailStep | SequenceLinkedInFollowStep | SequenceLinkedInLikePostStep | SequenceLinkedInCommentPostStep | SequenceLinkedInWithdrawInviteStep | SequenceEmailSendStep | SequenceEmailReplyStep | SequenceEmailEnrollStep | SequenceEmailMoveStep | SequenceEmailStopStep | SequenceWhatsAppMessageStep | SequenceWaitStep | SequenceWaitForSignalStep | SequenceBranchStep | SequenceStopStep;
 export type SequenceDefinition = {
     steps: SequenceStep[];
 };
@@ -328,6 +467,16 @@ export type SequenceLintIssue = {
 export type ValidateSequenceOptions = {
     /** When provided, every channel-bearing step must use one of these channels. */
     allowedChannels?: SequenceChannel[];
+    /**
+     * Whether this sequence has NATIVE open/click tracking enabled (a verified
+     * tracking domain + EMAIL_TRACKING_SECRET, so the dispatcher injects a pixel +
+     * rewrites links). Default false. When true, the native-email engagement-gate
+     * guard is relaxed: email_opened/email_clicked wait/branch gates are PERMITTED
+     * because a natively-tracked send DOES accumulate those signals. When false the
+     * guard still rejects them (a native send with no tracking never fires them, so
+     * the gate would silently dead-end).
+     */
+    nativeTrackingEnabled?: boolean;
 };
 /**
  * Validate + normalize a raw sequence definition. Assigns stable ids to steps
@@ -338,11 +487,36 @@ export type ValidateSequenceOptions = {
 export declare function validateSequenceDefinition(input: unknown, options?: ValidateSequenceOptions): SequenceDefinition;
 /** Non-throwing variant for lint surfaces. */
 export declare function lintSequenceDefinition(input: unknown, options?: ValidateSequenceOptions): SequenceLintIssue[];
-/** Total delay in milliseconds a wait step introduces. */
+/** Total base delay in milliseconds a wait step introduces (no jitter). */
 export declare function sequenceWaitStepDelayMs(step: SequenceWaitStep): number;
-/** Render a {{column}} template against a row's values (reuses the LinkedIn impl). */
-export declare function renderSequenceTemplate(template: string, values: Record<string, unknown>): string;
-/** Column keys referenced by {{...}} placeholders across every step's copy. */
+/**
+ * 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 declare function sequenceWaitStepJitterMs(step: SequenceWaitStep, enrollmentId: string): number;
+/**
+ * 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 declare function sequenceWaitStepDelayWithJitterMs(step: SequenceWaitStep, enrollmentId: string): number;
+/**
+ * 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 declare function renderSequenceTemplate(template: string, values: Record<string, unknown>, options?: RenderTemplateOptions): string;
+/**
+ * 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 declare function sequenceTemplateVariables(definition: SequenceDefinition): string[];
 /**
  * Evaluate a condition against the set of signals an enrollment has fired.
@@ -366,12 +540,60 @@ export declare function sequenceStepVariantCount(step: SequenceStep): number;
  * (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 declare function selectStepVariant(step: SequenceStep, key: string): {
+export declare function selectStepVariant(step: SequenceStep, key: string, options?: {
+    pausedVariantIds?: Iterable<string>;
+}): {
     variantId: string;
     index: number;
     content: StepVariantContent;
 };
+/** The step's opt-in auto-winner config, or null when it carries none. */
+export declare function stepAutoOptimizeConfig(step: SequenceStep): SequenceAutoOptimizeConfig | null;
+/** Per-variant conversion counts the auto-winner decides over (sends + conversions on the chosen metric). */
+export type VariantConversionStat = {
+    variantId: string;
+    sends: number;
+    conversions: number;
+};
+/** Stamped justification for an auto-winner pause — written onto each paused variant's state. */
+export type VariantAutoWinnerEvidence = {
+    metric: SequenceAutoOptimizeMetric;
+    variants: {
+        variant_id: string;
+        sends: number;
+        conversions: number;
+        rate: number;
+    }[];
+    winner_id: string;
+    decided_at: string;
+};
+export type VariantAutoWinnerDecision = {
+    /** Variant ids to pause (every still-active variant whose rate is strictly below the winner's). */
+    pause: string[];
+    /** The winning variant id (highest conversion rate). */
+    winnerId: string;
+    /** Evidence stamped onto each paused variant. */
+    evidence: VariantAutoWinnerEvidence;
+};
+/**
+ * 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 declare function decideVariantAutoWinner(stats: VariantConversionStat[], config: SequenceAutoOptimizeConfig, decidedAt: string, alreadyPaused?: Iterable<string>): VariantAutoWinnerDecision | null;
 /**
  * Resolve which IANA timezone a send window evaluates in for a given lead row.
  * "recipient" mode reads the lead's tz from `recipient_timezone_column`, falling