@oxygen-agent/cli 1.226.15 → 1.242.6

package/node_modules/@oxygen/shared/dist/custom-http-safety.js

@@ -0,0 +1,162 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+export class CustomHttpUrlSafetyError extends Error {
+    reason;
+    details;
+    constructor(reason, message, details = {}) {
+        super(message);
+        this.name = "CustomHttpUrlSafetyError";
+        this.reason = reason;
+        this.details = details;
+    }
+}
+export function assertCustomHttpPublicUrlSyntax(url) {
+    const parsed = typeof url === "string" ? new URL(url) : url;
+    if (parsed.protocol !== "https:") {
+        throw new CustomHttpUrlSafetyError("protocol", "Custom HTTP URLs must use https.", {
+            url: safeUrlForDetails(parsed),
+        });
+    }
+    if (parsed.username || parsed.password) {
+        throw new CustomHttpUrlSafetyError("credentials", "Custom HTTP URLs cannot contain username or password credentials.", { url: safeUrlForDetails(parsed) });
+    }
+    const host = normalizeCustomHttpUrlHost(parsed.hostname);
+    if (isBlockedCustomHttpHost(host)) {
+        throw new CustomHttpUrlSafetyError("blocked_host", "Custom HTTP URL host is not allowed.", { host });
+    }
+    return parsed;
+}
+export async function assertCustomHttpResolvedHostAllowed(input) {
+    const parsed = assertCustomHttpPublicUrlSyntax(input.url);
+    const host = normalizeCustomHttpUrlHost(parsed.hostname);
+    if (isIP(host))
+        return;
+    const resolveHostname = input.resolveHostname ?? defaultResolveHostname;
+    let addresses;
+    try {
+        addresses = await resolveHostname(host);
+    }
+    catch (error) {
+        throw new CustomHttpUrlSafetyError("dns_lookup_failed", "Custom HTTP URL host could not be resolved.", {
+            host,
+            reason: error instanceof Error ? error.message : String(error),
+        });
+    }
+    if (addresses.length === 0) {
+        throw new CustomHttpUrlSafetyError("dns_lookup_failed", "Custom HTTP URL host did not resolve to any address.", {
+            host,
+        });
+    }
+    for (const address of addresses) {
+        const normalizedAddress = normalizeCustomHttpUrlHost(address.address);
+        if (isBlockedCustomHttpHost(normalizedAddress)) {
+            throw new CustomHttpUrlSafetyError("blocked_resolved_address", "Custom HTTP URL host resolved to a non-public address.", { host, address: normalizedAddress, family: address.family ?? null });
+        }
+    }
+}
+export function normalizeCustomHttpUrlHost(hostname) {
+    const host = hostname.toLowerCase().replace(/\.+$/, "");
+    return host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+}
+export function isBlockedCustomHttpHost(host) {
+    return host === "localhost"
+        || host.endsWith(".localhost")
+        || host === "metadata.google.internal"
+        || isBlockedCustomHttpIpv4Address(host)
+        || isBlockedCustomHttpIpv6Address(host);
+}
+function safeUrlForDetails(parsed) {
+    return `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+}
+async function defaultResolveHostname(hostname) {
+    return await lookup(hostname, { all: true, verbatim: true });
+}
+function isBlockedCustomHttpIpv4Address(host) {
+    const address = isIP(host) === 4 ? host : readLeadingCustomHttpIpv4Label(host);
+    if (!address)
+        return false;
+    const parts = address.split(".").map((part) => Number(part));
+    if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255))
+        return true;
+    const [a = 0, b = 0, c = 0] = parts;
+    return a === 0
+        || a === 10
+        || a === 127
+        || (a === 169 && b === 254)
+        || (a === 172 && b >= 16 && b <= 31)
+        || (a === 192 && b === 168)
+        || (a === 100 && b >= 64 && b <= 127)
+        || (a === 192 && b === 0)
+        || (a === 198 && (b === 18 || b === 19))
+        || (a === 198 && b === 51 && c === 100)
+        || (a === 203 && b === 0 && c === 113)
+        || a >= 224;
+}
+function readLeadingCustomHttpIpv4Label(host) {
+    const match = /^(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})(?:\.|$)/.exec(host);
+    return match?.[1] ?? null;
+}
+function isBlockedCustomHttpIpv6Address(host) {
+    if (isIP(host) !== 6)
+        return false;
+    const groups = expandCustomHttpIpv6Groups(host);
+    if (!groups)
+        return true;
+    const mappedIpv4 = customHttpIpv4FromIpv6(groups);
+    if (mappedIpv4 && isBlockedCustomHttpIpv4Address(mappedIpv4))
+        return true;
+    const [first = 0, second = 0] = groups;
+    const isUnspecified = groups.every((group) => group === 0);
+    const isLoopback = groups.slice(0, 7).every((group) => group === 0) && groups[7] === 1;
+    return isUnspecified
+        || isLoopback
+        || (first & 0xfe00) === 0xfc00
+        || (first & 0xffc0) === 0xfe80
+        || (first & 0xff00) === 0xff00
+        || (first === 0x2001 && second === 0x0db8);
+}
+function expandCustomHttpIpv6Groups(host) {
+    const address = host.toLowerCase();
+    const doubleColonParts = address.split("::");
+    if (doubleColonParts.length > 2)
+        return null;
+    const head = splitCustomHttpIpv6Part(doubleColonParts[0] ?? "");
+    const tail = splitCustomHttpIpv6Part(doubleColonParts[1] ?? "");
+    if (!head || !tail)
+        return null;
+    const fill = doubleColonParts.length === 2 ? 8 - head.length - tail.length : 0;
+    if (fill < 0)
+        return null;
+    const groups = doubleColonParts.length === 2
+        ? [...head, ...Array.from({ length: fill }, () => 0), ...tail]
+        : head;
+    return groups.length === 8 ? groups : null;
+}
+function splitCustomHttpIpv6Part(part) {
+    if (!part)
+        return [];
+    const groups = part.split(":");
+    const values = [];
+    for (const group of groups) {
+        if (!/^[0-9a-f]{1,4}$/.test(group))
+            return null;
+        values.push(Number.parseInt(group, 16));
+    }
+    return values;
+}
+function customHttpIpv4FromIpv6(groups) {
+    const mappedPrefix = groups.slice(0, 5).every((group) => group === 0) && groups[5] === 0xffff;
+    const compatiblePrefix = groups.slice(0, 6).every((group) => group === 0);
+    if (!mappedPrefix && !compatiblePrefix)
+        return null;
+    const high = groups[6] ?? 0;
+    const low = groups[7] ?? 0;
+    if (high === 0 && low === 0)
+        return null;
+    return [
+        high >> 8,
+        high & 0xff,
+        low >> 8,
+        low & 0xff,
+    ].join(".");
+}

package/node_modules/@oxygen/shared/dist/email-unsubscribe-token.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Signed token for the RFC 8058 one-click List-Unsubscribe link on native cold
+ * email. The worker MINTS the token at send time and bakes the URL into the
+ * List-Unsubscribe header; the public web webhook VERIFIES it. The token is the
+ * ONLY credential the anonymous unsubscribe endpoint trusts, so it must bind the
+ * recipient address — never let the caller pass an arbitrary email. The signing
+ * key (EMAIL_UNSUBSCRIBE_SECRET) lives in Doppler oxygen-shared so both the
+ * worker (mint) and web (verify) read the same value.
+ *
+ * Layering: this lives in @oxygen/shared because neither the worker nor the
+ * integrations send path can import apps/web, and the web route cannot import the
+ * worker. Pure + stateless: crypto only, no env policy (the route decides what a
+ * null verify means — a 401).
+ */
+export type UnsubscribeTokenPayload = {
+    /** Schema version; only v1 is accepted. */
+    v: 1;
+    /** Organization id (also the webhook path segment; the route re-checks it). */
+    org: string;
+    /** The recipient address to suppress (normalized trim+lowercase, = the suppression key). */
+    email: string;
+    /** Sequence id, for provenance on the suppression row. */
+    seq?: string;
+    /** Enrollment id, so a one-click stop can halt the exact journey. */
+    enr?: string;
+    /** Sending mailbox id, for provenance. */
+    mbx?: string;
+    /** Issued-at (epoch ms), recorded as provenance. */
+    iat: number;
+};
+type EnvLike = Record<string, string | undefined>;
+/**
+ * Sign a payload into `<base64url(json)>.<base64url(hmac-sha256)>`. The HMAC is
+ * computed over the encoded body, so any tamper to the payload invalidates the
+ * signature. Normalizes the email to the stored suppression form so the webhook
+ * write and the pre-send gate key on the identical string.
+ */
+export declare function signUnsubscribeToken(payload: UnsubscribeTokenPayload, secret: string): string;
+/**
+ * Verify a token's signature (constant-time) and shape. Returns the payload only
+ * when the signature matches AND it is a well-formed v1 payload with a non-empty
+ * org + a plausible email; returns null on ANY problem (bad shape, wrong/blank
+ * secret, tampered body, replayed garbage). Pure: the route maps null -> 401.
+ */
+export declare function verifyUnsubscribeToken(token: string, secret: string): UnsubscribeTokenPayload | null;
+/**
+ * The HMAC signing secret for unsubscribe tokens, or null when unset. The send
+ * path treats null as "omit the header" (a send with no one-click link still
+ * delivers); the webhook route treats null as fail-closed (reject everything).
+ */
+export declare function unsubscribeSigningSecret(env?: EnvLike): string | null;
+/**
+ * The public app base URL the unsubscribe link points at, trailing slash
+ * stripped. Prefers NEXT_PUBLIC_APP_URL, then OXYGEN_APP_URL, then the prod host.
+ */
+export declare function oxygenAppBaseUrl(env?: EnvLike): string;
+/**
+ * The canonical one-click unsubscribe URL: org id in the path (the route
+ * re-checks it against the token), token in the `token` query param.
+ */
+export declare function buildUnsubscribeUrl(orgId: string, token: string, baseUrl: string): string;
+export {};

package/node_modules/@oxygen/shared/dist/email-unsubscribe-token.js

@@ -0,0 +1,99 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+function base64urlEncode(value) {
+    return Buffer.from(value, "utf8").toString("base64url");
+}
+/**
+ * Sign a payload into `<base64url(json)>.<base64url(hmac-sha256)>`. The HMAC is
+ * computed over the encoded body, so any tamper to the payload invalidates the
+ * signature. Normalizes the email to the stored suppression form so the webhook
+ * write and the pre-send gate key on the identical string.
+ */
+export function signUnsubscribeToken(payload, secret) {
+    const normalized = { ...payload, email: payload.email.trim().toLowerCase() };
+    const body = base64urlEncode(JSON.stringify(normalized));
+    const signature = createHmac("sha256", secret).update(body).digest("base64url");
+    return `${body}.${signature}`;
+}
+/** Constant-time HMAC-SHA256 check; false on any error (bad base64, length mismatch). */
+function verifySignature(body, providedSig, secret) {
+    const expected = createHmac("sha256", secret).update(body).digest();
+    let provided;
+    try {
+        provided = Buffer.from(providedSig, "base64url");
+    }
+    catch {
+        return false;
+    }
+    // Equal-length guard before timingSafeEqual (it throws on length mismatch).
+    return provided.length === expected.length && timingSafeEqual(provided, expected);
+}
+/** Decode and validate the base64url body; returns typed payload or null on any problem. */
+function parseTokenPayload(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const candidate = parsed;
+    if (candidate.v !== 1)
+        return null;
+    const org = typeof candidate.org === "string" ? candidate.org.trim() : "";
+    const email = typeof candidate.email === "string" ? candidate.email.trim().toLowerCase() : "";
+    if (!org || !email || !email.includes("@"))
+        return null;
+    return {
+        v: 1,
+        org,
+        email,
+        ...(typeof candidate.seq === "string" && candidate.seq ? { seq: candidate.seq } : {}),
+        ...(typeof candidate.enr === "string" && candidate.enr ? { enr: candidate.enr } : {}),
+        ...(typeof candidate.mbx === "string" && candidate.mbx ? { mbx: candidate.mbx } : {}),
+        iat: typeof candidate.iat === "number" && Number.isFinite(candidate.iat) ? candidate.iat : 0,
+    };
+}
+/**
+ * Verify a token's signature (constant-time) and shape. Returns the payload only
+ * when the signature matches AND it is a well-formed v1 payload with a non-empty
+ * org + a plausible email; returns null on ANY problem (bad shape, wrong/blank
+ * secret, tampered body, replayed garbage). Pure: the route maps null -> 401.
+ */
+export function verifyUnsubscribeToken(token, secret) {
+    if (typeof token !== "string" || typeof secret !== "string" || !secret)
+        return null;
+    const dot = token.indexOf(".");
+    if (dot <= 0 || dot === token.length - 1)
+        return null;
+    const body = token.slice(0, dot);
+    const providedSig = token.slice(dot + 1);
+    if (!verifySignature(body, providedSig, secret))
+        return null;
+    return parseTokenPayload(body);
+}
+/**
+ * The HMAC signing secret for unsubscribe tokens, or null when unset. The send
+ * path treats null as "omit the header" (a send with no one-click link still
+ * delivers); the webhook route treats null as fail-closed (reject everything).
+ */
+export function unsubscribeSigningSecret(env = process.env) {
+    const secret = env.EMAIL_UNSUBSCRIBE_SECRET?.trim();
+    return secret ? secret : null;
+}
+/**
+ * The public app base URL the unsubscribe link points at, trailing slash
+ * stripped. Prefers NEXT_PUBLIC_APP_URL, then OXYGEN_APP_URL, then the prod host.
+ */
+export function oxygenAppBaseUrl(env = process.env) {
+    const raw = (env.NEXT_PUBLIC_APP_URL || env.OXYGEN_APP_URL || "https://oxygen-agent.com").trim();
+    return raw.replace(/\/+$/, "");
+}
+/**
+ * The canonical one-click unsubscribe URL: org id in the path (the route
+ * re-checks it against the token), token in the `token` query param.
+ */
+export function buildUnsubscribeUrl(orgId, token, baseUrl) {
+    return `${baseUrl}/api/webhooks/email/unsubscribe/${encodeURIComponent(orgId)}?token=${token}`;
+}

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

@@ -7,6 +7,7 @@ export * from "./cli-envelope.js";
 export * from "./cli-result.js";
 export * from "./column-types.js";
 export * from "./credit-guidance.js";
+export * from "./email-unsubscribe-token.js";
 export * from "./linkedin-post-url.js";
 export * from "./linkedin-sequences.js";
 export * from "./networks.js";

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

@@ -7,6 +7,7 @@ export * from "./cli-envelope.js";
 export * from "./cli-result.js";
 export * from "./column-types.js";
 export * from "./credit-guidance.js";
+export * from "./email-unsubscribe-token.js";
 export * from "./linkedin-post-url.js";
 export * from "./linkedin-sequences.js";
 export * from "./networks.js";

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

@@ -1,4 +1,5 @@
 const LINKEDIN_HOST = "linkedin.com";
+const CANONICAL_LINKEDIN_HOST = `www.${LINKEDIN_HOST}`;
 const URL_LIKE_PATTERN = /^[a-z][a-z\d+.-]*:\/\//i;
 function normalizeHostname(hostname) {
     return hostname.toLowerCase().replace(/\.+$/, "");
@@ -19,6 +20,9 @@ function isLinkedInPostPath(pathname) {
     const path = safelyDecodePath(pathname).toLowerCase();
     return /^\/posts\/[^/]+\/?$/.test(path) || /^\/feed\/update\/urn:li:activity:[^/]+\/?$/.test(path);
 }
+function canonicalizePostPath(pathname) {
+    return pathname.replace(/\/+$/, "") || pathname;
+}
 export function isLinkedInPostUrlLike(value) {
     const trimmed = value.trim();
     return URL_LIKE_PATTERN.test(trimmed) || trimmed.toLowerCase().includes("linkedin.com");
@@ -42,7 +46,8 @@ export function normalizeLinkedInPostUrl(value) {
     if (!isLinkedInPostPath(url.pathname))
         return null;
     url.protocol = "https:";
-    url.hostname = hostname;
+    url.hostname = CANONICAL_LINKEDIN_HOST;
+    url.pathname = canonicalizePostPath(url.pathname);
     url.username = "";
     url.password = "";
     url.search = "";

package/node_modules/@oxygen/shared/dist/select-options.d.ts

@@ -15,6 +15,15 @@ export declare function isStatusSemantic(semanticType: string | null | undefined
  * transcripts all use this.
  */
 export declare function isMarkdownColumnSemantic(semanticType: string | null | undefined): boolean;
+/**
+ * `image` is a semantic over a `text` dataType holding an image URL (e.g. a
+ * LinkedIn profile picture): the grid renders the cell as a round avatar instead
+ * of a link, with initials/empty fallback. Storage stays text — no new dataType.
+ * `avatar`/`photo` are accepted as aliases so URLs landed by enrichment/CRM
+ * still render; the editor writes the canonical `IMAGE_COLUMN_SEMANTIC`.
+ */
+export declare const IMAGE_COLUMN_SEMANTIC = "image";
+export declare function isImageColumnSemantic(semanticType: string | null | undefined): boolean;
 export type SelectOption = {
     id: string;
     value: string;

package/node_modules/@oxygen/shared/dist/select-options.js

@@ -55,6 +55,17 @@ export function isStatusSemantic(semanticType) {
 export function isMarkdownColumnSemantic(semanticType) {
     return semanticType === "markdown";
 }
+/**
+ * `image` is a semantic over a `text` dataType holding an image URL (e.g. a
+ * LinkedIn profile picture): the grid renders the cell as a round avatar instead
+ * of a link, with initials/empty fallback. Storage stays text — no new dataType.
+ * `avatar`/`photo` are accepted as aliases so URLs landed by enrichment/CRM
+ * still render; the editor writes the canonical `IMAGE_COLUMN_SEMANTIC`.
+ */
+export const IMAGE_COLUMN_SEMANTIC = "image";
+export function isImageColumnSemantic(semanticType) {
+    return semanticType === "image" || semanticType === "avatar" || semanticType === "photo";
+}
 const MAX_OPTIONS = 200;
 // Normalize a raw options array (from a column `definition.options`, CLI/MCP, or
 // the editor) into canonical SelectOptions: dedupe by value, default colors,

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

@@ -37,6 +37,17 @@ export type SequenceChannel = (typeof SEQUENCE_CHANNELS)[number];
  */
 export declare const SEQUENCE_SIGNALS: readonly ["linkedin_connected", "linkedin_replied", "email_sent", "email_opened", "email_clicked", "email_replied", "email_bounced", "company_hiring", "company_raised_funds", "job_change", "new_hire", "web_visit", "intent"];
 export type SequenceSignal = (typeof SEQUENCE_SIGNALS)[number];
+/**
+ * Email engagement signals that ONLY arrive via the Instantly webhook
+ * (email_opened/email_clicked). Native email sends (Gmail API / Microsoft Graph)
+ * produce no open/click tracking, so a sequence that sends email natively can
+ * never accumulate these — gating a wait_for_signal or signal-branch on them
+ * silently always times out / always takes the else arm. validateSequenceDefinition
+ * rejects that misconfiguration. (email_replied/email_bounced DO arrive natively
+ * via the inbound-message + bounce paths, so they are not listed here.)
+ */
+export declare const SEQUENCE_NATIVE_UNTRACKED_SIGNALS: readonly ["email_opened", "email_clicked"];
+export type SequenceNativeUntrackedSignal = (typeof SEQUENCE_NATIVE_UNTRACKED_SIGNALS)[number];
 /** External GTM signals (the non-engagement subset of SEQUENCE_SIGNALS). */
 export declare const SEQUENCE_EXTERNAL_SIGNALS: readonly ["company_hiring", "company_raised_funds", "job_change", "new_hire", "web_visit", "intent"];
 export type SequenceExternalSignal = (typeof SEQUENCE_EXTERNAL_SIGNALS)[number];
@@ -48,6 +59,14 @@ export declare function isExternalSequenceSignal(value: string): value is Sequen
  * Single source of truth so the send path and the lookup path can't drift.
  */
 export declare const SEQUENCE_EMAIL_COLUMN_KEYS: readonly ["email", "email_address", "work_email", "primary_email", "Email"];
+/**
+ * Resolve an enrollment's recipient email from its row_values, taking the first
+ * present SEQUENCE_EMAIL_COLUMN_KEYS value that looks like an address. Single
+ * source of truth for both the send path (the dispatcher's `to`) and the
+ * complaint loop (the address a bounce/opt-out suppresses), so they can't drift.
+ * Returns the trimmed raw value (callers normalize/lowercase as needed) or null.
+ */
+export declare function recipientEmailFromRow(rowValues: Record<string, unknown> | null | undefined): string | 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

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

@@ -58,6 +58,19 @@ export const SEQUENCE_SIGNALS = [
     "web_visit",
     "intent",
 ];
+/**
+ * Email engagement signals that ONLY arrive via the Instantly webhook
+ * (email_opened/email_clicked). Native email sends (Gmail API / Microsoft Graph)
+ * produce no open/click tracking, so a sequence that sends email natively can
+ * never accumulate these — gating a wait_for_signal or signal-branch on them
+ * silently always times out / always takes the else arm. validateSequenceDefinition
+ * rejects that misconfiguration. (email_replied/email_bounced DO arrive natively
+ * via the inbound-message + bounce paths, so they are not listed here.)
+ */
+export const SEQUENCE_NATIVE_UNTRACKED_SIGNALS = ["email_opened", "email_clicked"];
+function isNativeUntrackedSignal(value) {
+    return SEQUENCE_NATIVE_UNTRACKED_SIGNALS.includes(value);
+}
 /** External GTM signals (the non-engagement subset of SEQUENCE_SIGNALS). */
 export const SEQUENCE_EXTERNAL_SIGNALS = [
     "company_hiring",
@@ -77,6 +90,21 @@ export function isExternalSequenceSignal(value) {
  * Single source of truth so the send path and the lookup path can't drift.
  */
 export const SEQUENCE_EMAIL_COLUMN_KEYS = ["email", "email_address", "work_email", "primary_email", "Email"];
+/**
+ * Resolve an enrollment's recipient email from its row_values, taking the first
+ * present SEQUENCE_EMAIL_COLUMN_KEYS value that looks like an address. Single
+ * source of truth for both the send path (the dispatcher's `to`) and the
+ * complaint loop (the address a bounce/opt-out suppresses), so they can't drift.
+ * Returns the trimmed raw value (callers normalize/lowercase as needed) or null.
+ */
+export function recipientEmailFromRow(rowValues) {
+    for (const key of SEQUENCE_EMAIL_COLUMN_KEYS) {
+        const value = rowValues?.[key];
+        if (typeof value === "string" && value.includes("@"))
+            return value.trim();
+    }
+    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
@@ -213,6 +241,14 @@ export function validateSequenceDefinition(input, options = {}) {
             }
         }
     });
+    // Pass 3: native-email engagement-gate guard. Native email sends produce no
+    // open/click signals (email_opened/email_clicked arrive only from the Instantly
+    // webhook). A sequence that sends email natively — has native email steps
+    // (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);
     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 });
     }
@@ -233,6 +269,52 @@ export function lintSequenceDefinition(input, options = {}) {
         return [{ path: "steps", message: error instanceof Error ? error.message : "Invalid sequence." }];
     }
 }
+/**
+ * Push an issue for every wait_for_signal / signal-branch that gates on a
+ * natively-untracked engagement signal (email_opened/email_clicked) inside a
+ * sequence that sends email natively. "Native email" = at least one
+ * email_send/email_reply step and NO Instantly-delegated email step
+ * (email_enroll/email_move/email_stop); an Instantly-bound sequence DOES receive
+ * those webhook signals, so it is left alone. Mutates `issues` in place.
+ */
+function reportNativeEngagementGates(steps, issues) {
+    const hasNativeEmail = steps.some((s) => s.kind === "email_send" || s.kind === "email_reply");
+    const hasInstantlyEmail = steps.some((s) => s.kind === "email_enroll" || s.kind === "email_move" || s.kind === "email_stop");
+    if (!hasNativeEmail || hasInstantlyEmail)
+        return;
+    steps.forEach((step, index) => {
+        if (step.kind === "wait_for_signal" && isNativeUntrackedSignal(step.signal)) {
+            issues.push({
+                path: `steps[${index}].signal`,
+                message: `step '${step.id}' waits for '${step.signal}', but this sequence sends email natively (no Instantly binding), which produces no open/click signals — the gate would always time out. Use email_replied/email_bounced, or bind an Instantly campaign to track opens/clicks.`,
+            });
+            return;
+        }
+        if (step.kind === "branch" && typeof step.condition !== "string") {
+            const referenced = new Set();
+            collectConditionSignals(step.condition, referenced);
+            for (const signal of SEQUENCE_NATIVE_UNTRACKED_SIGNALS) {
+                if (referenced.has(signal)) {
+                    issues.push({
+                        path: `steps[${index}].condition`,
+                        message: `step '${step.id}' branches on '${signal}', but this sequence sends email natively (no Instantly binding), which produces no open/click signals — the branch would always take the else arm. Use email_replied/email_bounced, or bind an Instantly campaign to track opens/clicks.`,
+                    });
+                }
+            }
+        }
+    });
+}
+/** Collect every signal name referenced anywhere in a signal-branch condition. */
+function collectConditionSignals(condition, out) {
+    if ("signal" in condition)
+        out.add(condition.signal);
+    else if ("all" in condition)
+        condition.all.forEach((c) => collectConditionSignals(c, out));
+    else if ("any" in condition)
+        condition.any.forEach((c) => collectConditionSignals(c, out));
+    else
+        collectConditionSignals(condition.not, out);
+}
 function collectSteps(input, issues) {
     const record = isRecord(input) ? input : null;
     const steps = record?.steps;
@@ -759,18 +841,13 @@ function normalizeVariants(raw, path, fields, issues) {
     });
     return out.length > 0 ? out : undefined;
 }
-function normalizeSendWindow(raw, path, issues) {
-    if (raw === undefined || raw === null)
-        return undefined;
-    if (!isRecord(raw)) {
-        issues.push({ path, message: "send_window must be an object." });
-        return undefined;
-    }
+function normalizeSendWindowConfiguredTimezone(raw, path, issues) {
     const timezone = typeof raw.timezone === "string" && raw.timezone.trim() ? raw.timezone.trim() : undefined;
     if (!timezone)
         issues.push({ path: `${path}.timezone`, message: "timezone (IANA, e.g. America/New_York) is required." });
-    const start = normalizeHhmm(raw.start, `${path}.start`, issues);
-    const end = normalizeHhmm(raw.end, `${path}.end`, issues);
+    return timezone ?? "UTC";
+}
+function validateSendWindowBounds(start, end, path, issues) {
     // A zero-width window (start === end) is never open — isWithinSendWindow
     // returns false for every instant — so a step carrying it defers
     // (outside_send_window) on every dispatch and the enrollment silently stalls
@@ -779,7 +856,8 @@ function normalizeSendWindow(raw, path, issues) {
     if (start !== undefined && end !== undefined && hhmmToMinutes(start) === hhmmToMinutes(end)) {
         issues.push({ path: `${path}.end`, message: "must differ from start — a zero-width send_window never sends." });
     }
-    const days = normalizeWeekdays(raw.days, `${path}.days`, issues);
+}
+function normalizeSendWindowTimezoneMode(raw, path, issues) {
     const mode = raw.timezone_mode === "recipient" ? "recipient" : "fixed";
     const column = mode === "recipient"
         ? optionalString(raw.recipient_timezone_column, `${path}.recipient_timezone_column`, issues)
@@ -787,8 +865,23 @@ function normalizeSendWindow(raw, path, issues) {
     if (mode === "recipient" && !column) {
         issues.push({ path: `${path}.recipient_timezone_column`, message: 'recipient_timezone_column is required when timezone_mode is "recipient".' });
     }
+    return { mode, column };
+}
+function normalizeSendWindow(raw, path, issues) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!isRecord(raw)) {
+        issues.push({ path, message: "send_window must be an object." });
+        return undefined;
+    }
+    const timezone = normalizeSendWindowConfiguredTimezone(raw, path, issues);
+    const start = normalizeHhmm(raw.start, `${path}.start`, issues);
+    const end = normalizeHhmm(raw.end, `${path}.end`, issues);
+    validateSendWindowBounds(start, end, path, issues);
+    const days = normalizeWeekdays(raw.days, `${path}.days`, issues);
+    const { mode, column } = normalizeSendWindowTimezoneMode(raw, path, issues);
     return {
-        timezone: timezone ?? "UTC",
+        timezone,
         ...(days ? { days } : {}),
         start: start ?? "09:00",
         end: end ?? "17:00",

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

@@ -1,2 +1,2 @@
-export declare const OXYGEN_VERSION = "1.226.15";
+export declare const OXYGEN_VERSION = "1.242.6";
 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.226.15";
+export const OXYGEN_VERSION = "1.242.6";
 // 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/node_modules/@oxygen/shared/package.json

@@ -15,6 +15,11 @@
       "types": "./dist/file-import.d.ts",
       "import": "./dist/file-import.js",
       "default": "./dist/file-import.js"
+    },
+    "./custom-http-safety": {
+      "types": "./dist/custom-http-safety.d.ts",
+      "import": "./dist/custom-http-safety.js",
+      "default": "./dist/custom-http-safety.js"
     }
   },
   "dependencies": {}

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

@@ -44,6 +44,7 @@ export type WorkflowTriggerManifest = {
     type: "cron";
     cron: string;
     timezone?: string | null;
+    metadata?: Record<string, unknown>;
     status?: WorkflowStatus;
 } | {
     type: "event";

package/package.json

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