@oxygen-agent/cli 1.152.15 → 1.160.18

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

@@ -0,0 +1,501 @@
+import { OxygenError } from "./index.js";
+import { renderLinkedInTemplate } from "./linkedin-sequences.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
+ * enrolled lead, spanning LinkedIn (executed natively by the sequencer dispatch
+ * engine) and email (native send through a mailbox, or delegated to a bound
+ * Instantly campaign). Three control kinds make it cross-channel:
+ *
+ * - wait_for_signal — gate until a provider signal fires (LinkedIn connection
+ *   accepted, email opened/replied, ...) or timeout_days elapse; generalizes
+ *   the LinkedIn-only wait_for_connection gate.
+ * - branch — evaluate a condition over the signals an enrollment has
+ *   accumulated and jump to a target step (then) or fall through (else).
+ * - stop — explicit terminal step, the only way to give a branch's two arms
+ *   genuinely distinct endings.
+ *
+ * A LinkedIn-only sequence (channels = ['linkedin'], no email steps) is exactly
+ * the behavior of the original LinkedIn sequencer, so the same engine and tables
+ * back both. This module is the single home for the schema; the legacy
+ * `linkedin-sequences.ts` validator remains for back-compat reads of stored
+ * LinkedIn-only definitions.
+ *
+ * Email steps: email_send/email_reply send natively through one of the
+ * sequence's mailboxes (Gmail API / Microsoft Graph) — Oxygen owns the send.
+ * email_enroll/move/stop delegate to a bound Instantly campaign (legacy, removed
+ * once native send fully replaces them); Instantly owns send cadence, warmup,
+ * and inbox rotation while Oxygen owns the cross-channel timeline + reply
+ * suppression.
+ */
+export const SEQUENCE_CHANNELS = ["linkedin", "email"];
+/**
+ * Signals an enrollment accumulates from provider webhooks. wait_for_signal gates
+ * and signal-branch conditions read these. linkedin_connected also advances the
+ * legacy wait_for_connection gate. (The lead's current connection *degree* is NOT
+ * a signal — it's resolved on demand by the dispatcher via a connection branch,
+ * `condition: "already_connected"`.)
+ */
+export const SEQUENCE_SIGNALS = [
+    "linkedin_connected",
+    "linkedin_replied",
+    "email_sent",
+    "email_opened",
+    "email_clicked",
+    "email_replied",
+    "email_bounced",
+];
+/**
+ * row_values keys an enrollment's email may live under, in send-precedence order.
+ * The dispatcher picks the FIRST present key as the recipient address; the
+ * enrollment-lookup queries OR across all of them (order-independent there).
+ * 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"];
+export const SEQUENCE_STEP_KINDS = [
+    // linkedin channel (native dispatch)
+    "visit_profile",
+    "invite",
+    "wait_for_connection",
+    "message",
+    "inmail",
+    // email channel
+    "email_send",
+    "email_reply",
+    "email_enroll",
+    "email_move",
+    "email_stop",
+    // control (channel-agnostic)
+    "wait",
+    "wait_for_signal",
+    "branch",
+    "stop",
+];
+/**
+ * Conditions a connection branch routes on. Both need live LinkedIn access, so
+ * the dispatcher (not the planner) resolves them over time:
+ * - connection_accepted: wait until the invite is accepted (or timeout_days) then
+ *   route accepted → then_id, timeout → else_id.
+ * - 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"];
+const MAX_SEQUENCE_STEPS = 50;
+const MAX_TEMPLATE_LENGTH = 8_000;
+const MAX_NOTE_LENGTH = 300;
+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) {
+    return channelForKind(step.kind);
+}
+/** Distinct channels a sequence touches (drives the sequence's channels[] tag). */
+export function sequenceChannels(definition) {
+    const channels = new Set();
+    for (const step of definition.steps) {
+        const channel = sequenceStepChannel(step);
+        if (channel)
+            channels.add(channel);
+    }
+    return [...channels];
+}
+/**
+ * Validate + normalize a raw sequence definition. Assigns stable ids to steps
+ * that omit one (s{index}), verifies branch/gate targets resolve, and enforces
+ * per-step shapes + channel restrictions. Returns the normalized definition or
+ * throws OxygenError("invalid_sequence") with per-step issues. Pure.
+ */
+export function validateSequenceDefinition(input, options = {}) {
+    const issues = [];
+    const rawSteps = collectSteps(input, issues);
+    // Pass 1: normalize each step + assign ids.
+    const normalized = [];
+    const usedIds = new Set();
+    rawSteps.forEach((rawStep, index) => {
+        const step = normalizeStep(rawStep, index, options, issues);
+        if (!step)
+            return;
+        if (usedIds.has(step.id)) {
+            issues.push({ path: `steps[${index}].id`, message: `Duplicate step id '${step.id}'.` });
+        }
+        usedIds.add(step.id);
+        normalized.push(step);
+    });
+    // Pass 2: branch targets must resolve to an existing step id (connection
+    // branches route by then_id/else_id, signal branches by then/else).
+    normalized.forEach((step, index) => {
+        if (step.kind !== "branch")
+            return;
+        if (typeof step.condition === "string") {
+            for (const [key, target] of [["then_id", step.then_id], ["else_id", step.else_id]]) {
+                if (target && !usedIds.has(target)) {
+                    issues.push({ path: `steps[${index}].${key}`, message: `branch target '${target}' is not a step id.` });
+                }
+            }
+        }
+        else {
+            for (const [key, target] of [["then", step.then], ["else", step.else]]) {
+                if (target !== null && !usedIds.has(target)) {
+                    issues.push({ path: `steps[${index}].${key}`, message: `branch target '${target}' is not a step id.` });
+                }
+            }
+        }
+    });
+    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 });
+    }
+    return { steps: normalized };
+}
+/** Non-throwing variant for lint surfaces. */
+export function lintSequenceDefinition(input, options = {}) {
+    try {
+        validateSequenceDefinition(input, options);
+        return [];
+    }
+    catch (error) {
+        if (error instanceof OxygenError && error.details && typeof error.details === "object") {
+            const issues = error.details.issues;
+            if (Array.isArray(issues))
+                return issues;
+        }
+        return [{ path: "steps", message: error instanceof Error ? error.message : "Invalid sequence." }];
+    }
+}
+function collectSteps(input, issues) {
+    const record = isRecord(input) ? input : null;
+    const steps = record?.steps;
+    if (!Array.isArray(steps)) {
+        issues.push({ path: "steps", message: "steps must be an array." });
+        return [];
+    }
+    if (steps.length === 0) {
+        issues.push({ path: "steps", message: "A sequence needs at least one step." });
+    }
+    if (steps.length > MAX_SEQUENCE_STEPS) {
+        issues.push({ path: "steps", message: `A sequence may have at most ${MAX_SEQUENCE_STEPS} steps.` });
+    }
+    return steps;
+}
+function normalizeStep(// skipcq: JS-R1005 -- discriminated DSL: one normalizer per step kind.
+raw, index, options, issues) {
+    const path = `steps[${index}]`;
+    if (!isRecord(raw)) {
+        issues.push({ path, message: "Each step must be an object." });
+        return null;
+    }
+    const kind = raw.kind;
+    if (typeof kind !== "string" || !SEQUENCE_STEP_KINDS.includes(kind)) {
+        issues.push({ path: `${path}.kind`, message: `kind must be one of: ${SEQUENCE_STEP_KINDS.join(", ")}.` });
+        return null;
+    }
+    const id = normalizeId(raw.id, index, path, issues);
+    const stepKind = kind;
+    const channel = channelForKind(stepKind);
+    if (channel && options.allowedChannels && !options.allowedChannels.includes(channel)) {
+        issues.push({ path: `${path}.channel`, message: `channel '${channel}' is not enabled for this sequence.` });
+    }
+    switch (stepKind) {
+        case "visit_profile":
+            return { id, channel: "linkedin", kind: "visit_profile" };
+        case "invite": {
+            const note = optionalTemplate(raw.note_template, `${path}.note_template`, MAX_NOTE_LENGTH, issues);
+            return note !== undefined
+                ? { id, channel: "linkedin", kind: "invite", note_template: note }
+                : { id, channel: "linkedin", kind: "invite" };
+        }
+        case "wait_for_connection": {
+            const timeoutDays = raw.timeout_days === undefined || raw.timeout_days === null
+                ? 14
+                : positiveInt(raw.timeout_days, `${path}.timeout_days`, issues) ?? 14;
+            return {
+                id,
+                channel: "linkedin",
+                kind: "wait_for_connection",
+                timeout_days: timeoutDays,
+                on_timeout: raw.on_timeout === "continue" ? "continue" : "stop",
+            };
+        }
+        case "message": {
+            const template = requiredTemplate(raw.template, `${path}.template`, issues);
+            return { id, channel: "linkedin", kind: "message", template: template ?? "" };
+        }
+        case "inmail": {
+            const subject = requiredTemplate(raw.subject_template, `${path}.subject_template`, issues);
+            const template = requiredTemplate(raw.template, `${path}.template`, issues);
+            return { id, channel: "linkedin", kind: "inmail", subject_template: subject ?? "", template: template ?? "" };
+        }
+        case "email_enroll": {
+            const subsequenceId = optionalString(raw.subsequence_id, `${path}.subsequence_id`, issues);
+            return subsequenceId !== undefined
+                ? { id, channel: "email", kind: "email_enroll", subsequence_id: subsequenceId }
+                : { id, channel: "email", kind: "email_enroll" };
+        }
+        case "email_move": {
+            const subsequenceId = optionalString(raw.subsequence_id, `${path}.subsequence_id`, issues);
+            if (subsequenceId === undefined) {
+                issues.push({ path: `${path}.subsequence_id`, message: "email_move requires subsequence_id." });
+            }
+            return { id, channel: "email", kind: "email_move", subsequence_id: subsequenceId ?? "" };
+        }
+        case "email_send": {
+            const subject = requiredTemplate(raw.subject_template, `${path}.subject_template`, issues);
+            const body = requiredTemplate(raw.body_template, `${path}.body_template`, issues);
+            return { id, channel: "email", kind: "email_send", subject_template: subject ?? "", body_template: body ?? "" };
+        }
+        case "email_reply": {
+            const body = requiredTemplate(raw.body_template, `${path}.body_template`, issues);
+            return { id, channel: "email", kind: "email_reply", body_template: body ?? "" };
+        }
+        case "email_stop":
+            return { id, channel: "email", kind: "email_stop" };
+        case "wait": {
+            const days = optionalNonNegativeInt(raw.days, `${path}.days`, issues);
+            const hours = optionalNonNegativeInt(raw.hours, `${path}.hours`, issues);
+            if ((days ?? 0) + (hours ?? 0) <= 0) {
+                issues.push({ path, message: "A wait step needs days and/or hours totaling at least 1 hour." });
+            }
+            return {
+                id,
+                kind: "wait",
+                ...(days !== undefined ? { days } : {}),
+                ...(hours !== undefined ? { hours } : {}),
+            };
+        }
+        case "wait_for_signal": {
+            const signal = normalizeSignal(raw.signal, `${path}.signal`, issues);
+            const timeoutDays = raw.timeout_days === undefined || raw.timeout_days === null
+                ? 7
+                : positiveInt(raw.timeout_days, `${path}.timeout_days`, issues) ?? 7;
+            return {
+                id,
+                kind: "wait_for_signal",
+                signal: signal ?? "email_replied",
+                timeout_days: timeoutDays,
+                on_timeout: raw.on_timeout === "continue" ? "continue" : "stop",
+            };
+        }
+        case "branch": {
+            // String condition → LinkedIn connection branch (preserve verbatim; the
+            // dispatcher resolves accept-wait / degree over time, routing then_id/else_id).
+            if (typeof raw.condition === "string") {
+                if (!SEQUENCE_CONNECTION_BRANCH_CONDITIONS.includes(raw.condition)) {
+                    issues.push({
+                        path: `${path}.condition`,
+                        message: `string condition must be one of: ${SEQUENCE_CONNECTION_BRANCH_CONDITIONS.join(", ")} (or a signal-condition object).`,
+                    });
+                    return null;
+                }
+                const conditionStr = raw.condition;
+                const timeoutDays = raw.timeout_days === undefined || raw.timeout_days === null
+                    ? undefined
+                    : positiveInt(raw.timeout_days, `${path}.timeout_days`, issues);
+                const thenId = normalizeTargetRef(raw.then_id ?? raw.then, `${path}.then_id`, issues);
+                const elseId = normalizeTargetRef(raw.else_id ?? raw.else, `${path}.else_id`, issues);
+                return {
+                    id,
+                    kind: "branch",
+                    condition: conditionStr,
+                    ...(timeoutDays !== undefined
+                        ? { timeout_days: timeoutDays }
+                        : conditionStr === "connection_accepted" ? { timeout_days: 14 } : {}),
+                    ...(thenId !== null ? { then_id: thenId } : {}),
+                    ...(elseId !== null ? { else_id: elseId } : {}),
+                };
+            }
+            // Object condition → signal branch. Accept then_id/else_id as aliases.
+            const condition = normalizeCondition(raw.condition, `${path}.condition`, issues);
+            return {
+                id,
+                kind: "branch",
+                condition: condition ?? { signal: "email_replied", present: true },
+                then: normalizeTargetRef(raw.then ?? raw.then_id, `${path}.then`, issues),
+                else: normalizeTargetRef(raw.else ?? raw.else_id, `${path}.else`, issues),
+            };
+        }
+        case "stop":
+            return { id, kind: "stop" };
+        default:
+            return null;
+    }
+}
+function channelForKind(kind) {
+    if (kind === "wait" || kind === "wait_for_signal" || kind === "branch" || kind === "stop")
+        return null;
+    if (kind === "email_send" || kind === "email_reply" ||
+        kind === "email_enroll" || kind === "email_move" || kind === "email_stop")
+        return "email";
+    return "linkedin";
+}
+function normalizeId(value, index, path, issues) {
+    if (value === undefined || value === null)
+        return `s${index}`;
+    if (typeof value !== "string" || !ID_PATTERN.test(value)) {
+        issues.push({ path: `${path}.id`, message: "id must match [A-Za-z0-9_-]{1,64}." });
+        return `s${index}`;
+    }
+    return value;
+}
+function normalizeSignal(value, path, issues) {
+    if (typeof value !== "string" || !SEQUENCE_SIGNALS.includes(value)) {
+        issues.push({ path, message: `signal must be one of: ${SEQUENCE_SIGNALS.join(", ")}.` });
+        return undefined;
+    }
+    return value;
+}
+function normalizeTargetRef(value, path, issues) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== "string" || !ID_PATTERN.test(value)) {
+        issues.push({ path, message: "must be a step id or null." });
+        return null;
+    }
+    return value;
+}
+function normalizeCondition(raw, path, issues, depth = 0) {
+    if (depth > 6) {
+        issues.push({ path, message: "condition nests too deeply." });
+        return undefined;
+    }
+    if (!isRecord(raw)) {
+        issues.push({ path, message: "condition must be an object." });
+        return undefined;
+    }
+    if (typeof raw.signal === "string") {
+        const signal = normalizeSignal(raw.signal, `${path}.signal`, issues);
+        if (!signal)
+            return undefined;
+        return { signal, present: raw.present === false ? false : true };
+    }
+    if (Array.isArray(raw.all)) {
+        return { all: normalizeConditionList(raw.all, `${path}.all`, issues, depth) };
+    }
+    if (Array.isArray(raw.any)) {
+        return { any: normalizeConditionList(raw.any, `${path}.any`, issues, depth) };
+    }
+    if (raw.not !== undefined) {
+        const inner = normalizeCondition(raw.not, `${path}.not`, issues, depth + 1);
+        return inner ? { not: inner } : undefined;
+    }
+    issues.push({ path, message: "condition must be {signal}, {all}, {any}, or {not}." });
+    return undefined;
+}
+function normalizeConditionList(raw, path, issues, depth) {
+    if (raw.length === 0) {
+        issues.push({ path, message: "must have at least one condition." });
+    }
+    const out = [];
+    raw.forEach((entry, index) => {
+        const condition = normalizeCondition(entry, `${path}[${index}]`, issues, depth + 1);
+        if (condition)
+            out.push(condition);
+    });
+    return out;
+}
+function requiredTemplate(value, path, issues) {
+    if (typeof value !== "string" || !value.trim()) {
+        issues.push({ path, message: "is required and must be a non-empty string." });
+        return undefined;
+    }
+    if (value.length > MAX_TEMPLATE_LENGTH) {
+        issues.push({ path, message: `must be at most ${MAX_TEMPLATE_LENGTH} characters.` });
+        return undefined;
+    }
+    return value;
+}
+function optionalTemplate(value, path, maxLength, issues) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string") {
+        issues.push({ path, message: "must be a string." });
+        return undefined;
+    }
+    if (value.length > maxLength) {
+        issues.push({ path, message: `must be at most ${maxLength} characters.` });
+        return undefined;
+    }
+    return value;
+}
+function optionalString(value, path, issues) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string" || !value.trim()) {
+        issues.push({ path, message: "must be a non-empty string." });
+        return undefined;
+    }
+    return value;
+}
+function positiveInt(value, path, issues) {
+    const num = Number(value);
+    if (!Number.isInteger(num) || num <= 0) {
+        issues.push({ path, message: "must be a positive integer." });
+        return undefined;
+    }
+    return num;
+}
+function optionalNonNegativeInt(value, path, issues) {
+    if (value === undefined || value === null)
+        return undefined;
+    const num = Number(value);
+    if (!Number.isInteger(num) || num < 0) {
+        issues.push({ path, message: "must be a non-negative integer." });
+        return undefined;
+    }
+    return num;
+}
+/** Total delay in milliseconds a wait step introduces. */
+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);
+}
+/** Column keys referenced by {{...}} placeholders across every step's copy. */
+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 step of definition.steps) {
+        if (step.kind === "invite")
+            scan(step.note_template);
+        if (step.kind === "message")
+            scan(step.template);
+        if (step.kind === "inmail") {
+            scan(step.subject_template);
+            scan(step.template);
+        }
+        if (step.kind === "email_send") {
+            scan(step.subject_template);
+            scan(step.body_template);
+        }
+        if (step.kind === "email_reply")
+            scan(step.body_template);
+    }
+    return [...vars];
+}
+/**
+ * Evaluate a condition against the set of signals an enrollment has fired.
+ * Used by the dispatch planner for branch steps. Pure.
+ */
+export function evaluateSequenceCondition(condition, firedSignals) {
+    const fired = firedSignals instanceof Set ? firedSignals : new Set(firedSignals);
+    if ("signal" in condition) {
+        const present = fired.has(condition.signal);
+        return condition.present === false ? !present : present;
+    }
+    if ("all" in condition)
+        return condition.all.every((c) => evaluateSequenceCondition(c, fired));
+    if ("any" in condition)
+        return condition.any.some((c) => evaluateSequenceCondition(c, fired));
+    return !evaluateSequenceCondition(condition.not, fired);
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/node_modules/@oxygen/shared/dist/sql-error.d.ts

@@ -0,0 +1,43 @@
+/** Normalized failure category, derived from SQLSTATE first, then errno/message. */
+export type SqlErrorCause = "connect_timeout" | "connection" | "statement_timeout" | "admin_shutdown" | "too_many_connections" | "insufficient_resources" | "auth" | "schema_drift" | "data_exception" | "integrity_constraint" | "serialization" | "deadlock" | "transaction_rollback" | "syntax_or_access" | "internal" | "unknown";
+export type SqlErrorAttribution = {
+    /** Postgres SQLSTATE (5 chars) when present; null for connection-level errnos. */
+    pgCode: string | null;
+    cause: SqlErrorCause;
+    /** Leading SQL verb (select/insert/update/...) parsed from parameter-free SQL. */
+    queryKind: string | null;
+    /** Schema-qualified table identifier (schema metadata, never row data). */
+    table: string | null;
+    /** True when a retry on the next tick could plausibly succeed. */
+    transient: boolean;
+    /** pg severity keyword (ERROR/FATAL/PANIC/WARNING); null when absent. */
+    severity: string | null;
+    /** Schema name from the pg error (schema metadata, never row data). */
+    schema: string | null;
+    /** Column name implicated by the failure (NOT NULL / type violations). */
+    column: string | null;
+    /** Constraint name implicated by the failure (unique/foreign-key/check). */
+    constraint: string | null;
+    /** Neon/HTTP transport status code (numeric) when the failure carries one. */
+    statusCode: number | null;
+};
+/**
+ * Classifies a pg/drizzle error into structured, non-secret attribution.
+ * Returns null when the error carries no SQL/connection signal at all (so
+ * non-DB errors never gain spurious `db.*` attributes). Never throws.
+ */
+export declare function describeSqlError(error: unknown): SqlErrorAttribution | null;
+/** Log-field shape (snake_case) for merging into `errorFields(error)` payloads. */
+export declare function sqlErrorFields(error: unknown): Record<string, unknown>;
+/**
+ * Strips drizzle's `\nparams: <values>` segment from an error message or stack
+ * so SQL parameter values never reach logs/telemetry (OXY-46). Preserves the SQL
+ * text itself and any following stack frames; a no-op on non-drizzle text.
+ *
+ * drizzle's DrizzleQueryError carries the parameter array inside its `.message`
+ * (and therefore its `.stack`) as `Failed query: <sql>\nparams: <values>`, so
+ * the generic error serializers would otherwise emit those values verbatim.
+ */
+export declare function redactSqlParameters(text: string): string;
+/** Telemetry-attribute shape (dotted keys) for span error attribution. */
+export declare function sqlErrorTelemetryAttributes(error: unknown): Record<string, unknown>;