@oxygen-agent/cli 1.233.8 → 1.244.2

package/dist/local-custom-http-column.d.ts

@@ -1,8 +1,10 @@
+import { type CustomHttpResolveHostname } from "@oxygen/shared/custom-http-safety";
 type LocalColumnRunOptions = {
     rowId: string | null;
     limit?: number;
     concurrency?: number;
     force: boolean;
+    resolveHostname?: CustomHttpResolveHostname;
 };
 export declare function runLocalCustomHttpColumn(table: string, columnKeyOrId: string, options: LocalColumnRunOptions): Promise<Record<string, unknown>>;
 export {};

package/dist/local-custom-http-column.js

@@ -1,6 +1,6 @@
 import { Buffer } from "node:buffer";
-import { isIP } from "node:net";
 import { OxygenError } from "@oxygen/shared";
+import { CustomHttpUrlSafetyError, assertCustomHttpPublicUrlSyntax, assertCustomHttpResolvedHostAllowed, } from "@oxygen/shared/custom-http-safety";
 import { requestOxygen } from "./http-client.js";
 const LOCAL_CUSTOM_HTTP_TIMEOUT_MS = 10_000;
 const LOCAL_CUSTOM_HTTP_MAX_RESPONSE_BYTES = 1_000_000;
@@ -28,11 +28,13 @@ export async function runLocalCustomHttpColumn(table, columnKeyOrId, options) {
         row,
         secrets,
         force: options.force,
+        ...(options.resolveHostname ? { resolveHostname: options.resolveHostname } : {}),
     }));
     const { completedCount, failedCount, skippedCount } = countLocalCustomHttpResults(results);
     return {
         status: localCustomHttpRunStatus({ completedCount, failedCount, skippedCount }),
         table: described.table ?? queried.table ?? null,
+        web_url: localCustomHttpTableWebUrl(table, described.table, queried.table),
         column,
         toolId: "custom_http",
         requestedRowCount: rows.length,
@@ -56,7 +58,7 @@ async function runLocalCustomHttpRow(input) {
         };
     }
     try {
-        const execution = await executeLocalCustomHttpColumn(input.definition, input.row, input.secrets);
+        const execution = await executeLocalCustomHttpColumn(input.definition, input.row, input.secrets, input.resolveHostname);
         return await persistLocalCustomHttpSuccess({ ...input, rowId, execution });
     }
     catch (error) {
@@ -145,6 +147,20 @@ function localFirstRowFields(first) {
         fields.run = first.run;
     return fields;
 }
+function localCustomHttpTableWebUrl(table, described, queried) {
+    const identifier = readLocalTableIdentifier(described) ?? readLocalTableIdentifier(queried) ?? table;
+    return `https://oxygen-agent.com/tables/${encodeURIComponent(identifier)}`;
+}
+function readLocalTableIdentifier(table) {
+    if (!isRecord(table))
+        return null;
+    for (const key of ["id", "slug", "key"]) {
+        const value = table[key];
+        if (typeof value === "string" && value.trim())
+            return value.trim();
+    }
+    return null;
+}
 function findLocalColumn(columns, columnKeyOrId) {
     const column = columns.find((entry) => entry.id === columnKeyOrId || entry.key === columnKeyOrId);
     if (!column) {
@@ -318,13 +334,13 @@ async function mapLocalConcurrent(values, concurrency, action) {
     }));
     return results;
 }
-async function executeLocalCustomHttpColumn(definition, row, secrets) {
+async function executeLocalCustomHttpColumn(definition, row, secrets, resolveHostname) {
     const prepared = prepareLocalCustomHttpRequest(definition, row, secrets);
-    const response = await fetchLocalCustomHttpResponse(prepared);
+    const response = await fetchLocalCustomHttpResponse(prepared, resolveHostname);
     return await readLocalCustomHttpExecution(response, prepared, definition.outputPath ?? null);
 }
 function prepareLocalCustomHttpRequest(definition, row, secrets) {
-    const secretValues = Object.values(secrets);
+    const secretValues = expandLocalSecretValues(secrets);
     const method = definition.request.method;
     const url = resolveLocalHttpUrl(definition.request.url, row, secrets, secretValues);
     const headers = resolveLocalHeaders(definition.request.headers ?? {}, row, secrets);
@@ -333,6 +349,27 @@ function prepareLocalCustomHttpRequest(definition, row, secrets) {
     const body = bodyValue === undefined ? undefined : serializeLocalHttpBody(bodyValue, headers);
     return { method, url, headers, bodyValue, body, secretValues };
 }
+function expandLocalSecretValues(secrets) {
+    const values = new Set();
+    for (const secret of Object.values(secrets)) {
+        if (!secret)
+            continue;
+        values.add(secret);
+        try {
+            values.add(encodeURIComponent(secret));
+        }
+        catch {
+            // Ignore values that cannot be URL-encoded.
+        }
+        try {
+            values.add(encodeURI(secret));
+        }
+        catch {
+            // Ignore values that cannot be URL-encoded.
+        }
+    }
+    return [...values];
+}
 function resolveLocalHttpUrl(template, row, secrets, secretValues) {
     const resolvedUrl = resolveLocalTemplateString(template, row, secrets, "request.url");
     if (typeof resolvedUrl === "string" && resolvedUrl.trim())
@@ -355,7 +392,8 @@ function assertLocalHttpBodyAllowed(method, bodyValue) {
         });
     }
 }
-async function fetchLocalCustomHttpResponse(prepared) {
+async function fetchLocalCustomHttpResponse(prepared, resolveHostname) {
+    await assertLocalResolvedHttpUrlAllowed(prepared, resolveHostname);
     return await fetch(prepared.url, {
         method: prepared.method,
         headers: prepared.headers,
@@ -371,6 +409,32 @@ async function fetchLocalCustomHttpResponse(prepared) {
         });
     });
 }
+async function assertLocalResolvedHttpUrlAllowed(prepared, resolveHostname) {
+    try {
+        await assertCustomHttpResolvedHostAllowed({
+            url: prepared.url,
+            ...(resolveHostname ? { resolveHostname } : {}),
+        });
+    }
+    catch (error) {
+        if (!(error instanceof CustomHttpUrlSafetyError))
+            throw error;
+        if (error.reason === "dns_lookup_failed") {
+            throw new OxygenError("custom_http_network_error", "Custom HTTP request failed before receiving a response.", {
+                details: {
+                    reason: redactLocalSecrets(error.message, prepared.secretValues),
+                },
+                exitCode: 1,
+            });
+        }
+        throw new OxygenError("invalid_column_run", "Custom HTTP request url is invalid.", {
+            details: {
+                reason: redactLocalSecrets(error.message, prepared.secretValues),
+            },
+            exitCode: 1,
+        });
+    }
+}
 async function readLocalCustomHttpExecution(response, prepared, outputPath) {
     assertLocalNoRedirect(response, prepared.secretValues);
     const responseBody = await readLocalHttpResponseBody(response, LOCAL_CUSTOM_HTTP_MAX_RESPONSE_BYTES);
@@ -435,111 +499,14 @@ function validateLocalHttpUrl(rawUrl, secretValues) {
     }
 }
 function validateLocalPublicHttpsUrl(parsed) {
-    if (parsed.protocol !== "https:")
-        throw new Error("Custom HTTP URLs must use https.");
-    if (parsed.username || parsed.password)
-        throw new Error("Custom HTTP URLs cannot contain username or password credentials.");
-    const host = normalizeLocalUrlHost(parsed.hostname);
-    if (isBlockedLocalCustomHttpHost(host))
-        throw new Error("Custom HTTP URL host is not allowed.");
-}
-function normalizeLocalUrlHost(hostname) {
-    const host = hostname.toLowerCase().replace(/\.+$/, "");
-    return host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
-}
-function isBlockedLocalCustomHttpHost(host) {
-    return host === "localhost"
-        || host.endsWith(".localhost")
-        || host === "metadata.google.internal"
-        || isBlockedLocalIpv4Address(host)
-        || isBlockedLocalIpv6Address(host);
-}
-function isBlockedLocalIpv4Address(host) {
-    const address = isIP(host) === 4 ? host : readLeadingLocalIpv4Label(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] = 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 >= 224;
-}
-function readLeadingLocalIpv4Label(host) {
-    const match = /^(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})(?:\.|$)/.exec(host);
-    return match?.[1] ?? null;
-}
-function isBlockedLocalIpv6Address(host) {
-    if (isIP(host) !== 6)
-        return false;
-    const groups = expandLocalIpv6Groups(host);
-    if (!groups)
-        return true;
-    const mappedIpv4 = localIpv4FromIpv6(groups);
-    if (mappedIpv4 && isBlockedLocalIpv4Address(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 expandLocalIpv6Groups(host) {
-    const address = host.toLowerCase();
-    const doubleColonParts = address.split("::");
-    if (doubleColonParts.length > 2)
-        return null;
-    const head = splitLocalIpv6Part(doubleColonParts[0] ?? "");
-    const tail = splitLocalIpv6Part(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 splitLocalIpv6Part(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));
+    try {
+        assertCustomHttpPublicUrlSyntax(parsed);
+    }
+    catch (error) {
+        if (error instanceof CustomHttpUrlSafetyError)
+            throw new Error(error.message);
+        throw error;
     }
-    return values;
-}
-function localIpv4FromIpv6(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(".");
 }
 function resolveLocalHeaders(headers, row, secrets) {
     const resolved = {};

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

@@ -0,0 +1,18 @@
+export type CustomHttpResolvedAddress = {
+    address: string;
+    family?: number;
+};
+export type CustomHttpResolveHostname = (hostname: string) => Promise<CustomHttpResolvedAddress[]>;
+export type CustomHttpUrlSafetyErrorReason = "blocked_host" | "blocked_resolved_address" | "credentials" | "dns_lookup_failed" | "protocol";
+export declare class CustomHttpUrlSafetyError extends Error {
+    readonly reason: CustomHttpUrlSafetyErrorReason;
+    readonly details: Record<string, unknown>;
+    constructor(reason: CustomHttpUrlSafetyErrorReason, message: string, details?: Record<string, unknown>);
+}
+export declare function assertCustomHttpPublicUrlSyntax(url: string | URL): URL;
+export declare function assertCustomHttpResolvedHostAllowed(input: {
+    url: string | URL;
+    resolveHostname?: CustomHttpResolveHostname;
+}): Promise<CustomHttpResolvedAddress[]>;
+export declare function normalizeCustomHttpUrlHost(hostname: string): string;
+export declare function isBlockedCustomHttpHost(host: string): boolean;

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

@@ -0,0 +1,194 @@
+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);
+    // Literal IP hosts were already validated by assertCustomHttpPublicUrlSyntax and
+    // need no DNS resolution (nor connection pinning) — return an empty answer set.
+    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 });
+        }
+    }
+    // Return the validated addresses so callers can pin the connection to a checked
+    // IP and close the DNS-rebinding TOCTOU (fetch would otherwise re-resolve).
+    return addresses;
+}
+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 (let index = 0; index < groups.length; index += 1) {
+        const group = groups[index] ?? "";
+        // A trailing dotted-decimal group (e.g. `8.8.8.8` in `::ffff:8.8.8.8`) is a
+        // valid IPv4-in-IPv6 literal; fold it into its two 16-bit words so mapped/
+        // compatible addresses parse instead of fail-closing as "blocked".
+        if (index === groups.length - 1 && group.includes(".")) {
+            const octets = customHttpDottedIpv4Octets(group);
+            if (!octets)
+                return null;
+            values.push((octets[0] << 8) | octets[1], (octets[2] << 8) | octets[3]);
+            continue;
+        }
+        if (!/^[0-9a-f]{1,4}$/.test(group))
+            return null;
+        values.push(Number.parseInt(group, 16));
+    }
+    return values;
+}
+function customHttpDottedIpv4Octets(value) {
+    if (isIP(value) !== 4)
+        return null;
+    const octets = value.split(".").map((octet) => Number(octet));
+    return [octets[0] ?? 0, octets[1] ?? 0, octets[2] ?? 0, octets[3] ?? 0];
+}
+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);
+    // NAT64/DNS64 well-known prefix 64:ff9b::/96 embeds the IPv4 in the last 32 bits.
+    const nat64WellKnownPrefix = groups[0] === 0x0064
+        && groups[1] === 0xff9b
+        && groups.slice(2, 6).every((group) => group === 0);
+    if (mappedPrefix || compatiblePrefix || nat64WellKnownPrefix) {
+        return customHttpIpv4FromIpv6Pair(groups[6], groups[7]);
+    }
+    // 6to4 prefix 2002::/16 embeds the gateway IPv4 in the two groups after the prefix.
+    if (groups[0] === 0x2002) {
+        return customHttpIpv4FromIpv6Pair(groups[1], groups[2]);
+    }
+    return null;
+}
+function customHttpIpv4FromIpv6Pair(high = 0, low = 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.js

@@ -14,31 +14,21 @@ export function signUnsubscribeToken(payload, secret) {
     const signature = createHmac("sha256", secret).update(body).digest("base64url");
     return `${body}.${signature}`;
 }
-/**
- * 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);
+/** 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 null;
+        return false;
     }
     // Equal-length guard before timingSafeEqual (it throws on length mismatch).
-    if (provided.length !== expected.length || !timingSafeEqual(provided, expected))
-        return null;
+    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"));
@@ -65,6 +55,24 @@ export function verifyUnsubscribeToken(token, secret) {
         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

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];