@oxygen-agent/cli 1.142.4 → 1.152.15

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

@@ -1,12 +1,15 @@
 export { OXYGEN_MINIMUM_CLI_VERSION, OXYGEN_VERSION } from "./version.js";
+export { WORKFLOW_TRIGGER_AUTO_PAUSE_METADATA_KEYS, clearWorkflowTriggerAutoPauseMetadata, } from "./workflow-trigger-metadata.js";
 export * from "./billing.js";
 export * from "./cell-format.js";
 export * from "./column-types.js";
 export * from "./credit-guidance.js";
+export * from "./linkedin-sequences.js";
 export * from "./log.js";
 export * from "./provider-request-outcomes.js";
 export * from "./signup-lead-deliveries.js";
 export * from "./telemetry.js";
+export declare const MAX_ROW_LOOP_WRITE_ROWS = 500;
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
@@ -46,3 +49,24 @@ export declare function failure(command: string, error: {
     details?: unknown;
 }, version?: string, minimumCliVersion?: string): CliFailure;
 export declare function toFailure(command: string, error: unknown, version?: string): CliFailure;
+export type SemanticVersion = {
+    major: number;
+    minor: number;
+    patch: number;
+};
+/**
+ * Parse a three-segment semantic version (e.g. `1.142.17`). Pre-release and
+ * build metadata suffixes (`-rc.1`, `+build`) are tolerated but ignored.
+ * Returns `null` when the input is not a parseable `major.minor.patch` string.
+ */
+export declare function parseSemver(version: string): SemanticVersion | null;
+/**
+ * Compare two semantic versions. Returns -1 when `a < b`, 1 when `a > b`, and
+ * 0 when they are equal. Unparseable inputs compare as equal (0) so callers
+ * fail open rather than misordering garbage.
+ */
+export declare function compareSemver(a: string, b: string): -1 | 0 | 1;
+/** True when `a` is a strictly greater semantic version than `b`. */
+export declare function isVersionGreater(a: string, b: string): boolean;
+/** True when `a` is a strictly lesser semantic version than `b`. */
+export declare function isVersionLess(a: string, b: string): boolean;

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

@@ -1,13 +1,21 @@
 import { OXYGEN_MINIMUM_CLI_VERSION, OXYGEN_VERSION } from "./version.js";
 export { OXYGEN_MINIMUM_CLI_VERSION, OXYGEN_VERSION } from "./version.js";
+export { WORKFLOW_TRIGGER_AUTO_PAUSE_METADATA_KEYS, clearWorkflowTriggerAutoPauseMetadata, } from "./workflow-trigger-metadata.js";
 export * from "./billing.js";
 export * from "./cell-format.js";
 export * from "./column-types.js";
 export * from "./credit-guidance.js";
+export * from "./linkedin-sequences.js";
 export * from "./log.js";
 export * from "./provider-request-outcomes.js";
 export * from "./signup-lead-deliveries.js";
 export * from "./telemetry.js";
+// Maximum rows a single row-loop write (insert/upsert/preview) may process. The
+// row-loop engine issues one DB round-trip per row, so a 500-row write already
+// approaches request timeouts (~50s observed in prod); larger batches must use
+// the COPY-based bulk engine. Tenant-db enforces this and the CLI/API row caps
+// reference it so they never advertise a batch the row-loop will reject.
+export const MAX_ROW_LOOP_WRITE_ROWS = 500;
 export class OxygenError extends Error {
     code;
     details;
@@ -51,3 +59,44 @@ export function toFailure(command, error, version = OXYGEN_VERSION) {
     }
     return failure(command, { code: "unexpected_error", message: "An unexpected error occurred." }, version);
 }
+/**
+ * Parse a three-segment semantic version (e.g. `1.142.17`). Pre-release and
+ * build metadata suffixes (`-rc.1`, `+build`) are tolerated but ignored.
+ * Returns `null` when the input is not a parseable `major.minor.patch` string.
+ */
+export function parseSemver(version) {
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(version);
+    if (!match)
+        return null;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+    };
+}
+/**
+ * Compare two semantic versions. Returns -1 when `a < b`, 1 when `a > b`, and
+ * 0 when they are equal. Unparseable inputs compare as equal (0) so callers
+ * fail open rather than misordering garbage.
+ */
+export function compareSemver(a, b) {
+    const left = parseSemver(a);
+    const right = parseSemver(b);
+    if (!left || !right)
+        return 0;
+    for (const key of ["major", "minor", "patch"]) {
+        if (left[key] > right[key])
+            return 1;
+        if (left[key] < right[key])
+            return -1;
+    }
+    return 0;
+}
+/** True when `a` is a strictly greater semantic version than `b`. */
+export function isVersionGreater(a, b) {
+    return compareSemver(a, b) > 0;
+}
+/** True when `a` is a strictly lesser semantic version than `b`. */
+export function isVersionLess(a, b) {
+    return compareSemver(a, b) < 0;
+}

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

@@ -0,0 +1,83 @@
+/**
+ * LinkedIn sequence step schema — the shared contract validated identically by
+ * CLI, MCP, API, and web. A sequence is an ordered list of steps applied to
+ * each enrolled lead; the worker dispatch engine materializes one
+ * sequence_action per step as it comes due.
+ *
+ * Step kinds:
+ * - visit_profile        — view the lead's profile (warms up before an invite)
+ * - invite               — send a connection request, optional note_template
+ * - wait_for_connection  — gate: wait until the invite is accepted (new_relation
+ *                          webhook) or timeout_days elapses; on timeout stop or
+ *                          continue per on_timeout
+ * - wait                 — fixed delay (days/hours) before the next step
+ * - message              — send a message (opens a chat if none exists);
+ *                          template supports {{column}} interpolation
+ * - inmail               — send an InMail (works on non-connections); subject +
+ *                          template
+ */
+export declare const LINKEDIN_SEQUENCE_STEP_KINDS: readonly ["visit_profile", "invite", "wait_for_connection", "wait", "message", "inmail"];
+export type LinkedInSequenceStepKind = typeof LINKEDIN_SEQUENCE_STEP_KINDS[number];
+export type LinkedInVisitProfileStep = {
+    kind: "visit_profile";
+};
+export type LinkedInInviteStep = {
+    kind: "invite";
+    /** Optional connection-request note. Supports {{column}} interpolation. ~300 char max on LinkedIn. */
+    note_template?: string;
+};
+export type LinkedInWaitForConnectionStep = {
+    kind: "wait_for_connection";
+    /** Days to wait for the invite to be accepted before acting on on_timeout. */
+    timeout_days: number;
+    /** What to do if the invite is never accepted. Defaults to "stop". */
+    on_timeout?: "stop" | "continue";
+};
+export type LinkedInWaitStep = {
+    kind: "wait";
+    /** Fixed delay before the next step. Provide days and/or hours (>= 1 total). */
+    days?: number;
+    hours?: number;
+};
+export type LinkedInMessageStep = {
+    kind: "message";
+    /** Message body. Supports {{column}} interpolation from the source-table row. */
+    template: string;
+};
+export type LinkedInInMailStep = {
+    kind: "inmail";
+    subject_template: string;
+    template: string;
+};
+export type LinkedInSequenceStep = LinkedInVisitProfileStep | LinkedInInviteStep | LinkedInWaitForConnectionStep | LinkedInWaitStep | LinkedInMessageStep | LinkedInInMailStep;
+export type LinkedInSequenceDefinition = {
+    steps: LinkedInSequenceStep[];
+};
+/**
+ * The dispatch-queue action kind a step produces (matches the
+ * ox_linkedin.sequence_actions.action_kind enum), or null for gate/wait steps
+ * that dispatch nothing. NOTE: this is the *action* kind, not the *quota* kind
+ * — visit_profile maps to the quota kind profile_view downstream.
+ */
+export declare const LINKEDIN_STEP_ACTION_KIND: Record<LinkedInSequenceStepKind, "visit_profile" | "invite" | "message" | "inmail" | null>;
+export type LinkedInSequenceLintIssue = {
+    path: string;
+    message: string;
+};
+/**
+ * Validate a raw sequence definition. Returns the normalized definition or
+ * throws OxygenError("invalid_linkedin_sequence") with per-step issues. Pure —
+ * safe to call from any surface.
+ */
+export declare function validateLinkedInSequenceDefinition(input: unknown): LinkedInSequenceDefinition;
+/** Non-throwing variant for lint surfaces. */
+export declare function lintLinkedInSequenceDefinition(input: unknown): LinkedInSequenceLintIssue[];
+/** Total delay in milliseconds a `wait` step introduces. */
+export declare function waitStepDelayMs(step: LinkedInWaitStep): number;
+/**
+ * Render a {{column}} template against a row's values. Unknown placeholders
+ * render empty. Used by the dispatch engine to produce the final message text.
+ */
+export declare function renderLinkedInTemplate(template: string, values: Record<string, unknown>): string;
+/** Column keys referenced by {{...}} placeholders across all steps. */
+export declare function linkedInTemplateVariables(definition: LinkedInSequenceDefinition): string[];

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

@@ -0,0 +1,268 @@
+import { OxygenError } from "./index.js";
+/**
+ * LinkedIn sequence step schema — the shared contract validated identically by
+ * CLI, MCP, API, and web. A sequence is an ordered list of steps applied to
+ * each enrolled lead; the worker dispatch engine materializes one
+ * sequence_action per step as it comes due.
+ *
+ * Step kinds:
+ * - visit_profile        — view the lead's profile (warms up before an invite)
+ * - invite               — send a connection request, optional note_template
+ * - wait_for_connection  — gate: wait until the invite is accepted (new_relation
+ *                          webhook) or timeout_days elapses; on timeout stop or
+ *                          continue per on_timeout
+ * - wait                 — fixed delay (days/hours) before the next step
+ * - message              — send a message (opens a chat if none exists);
+ *                          template supports {{column}} interpolation
+ * - inmail               — send an InMail (works on non-connections); subject +
+ *                          template
+ */
+export const LINKEDIN_SEQUENCE_STEP_KINDS = [
+    "visit_profile",
+    "invite",
+    "wait_for_connection",
+    "wait",
+    "message",
+    "inmail",
+];
+/**
+ * The dispatch-queue action kind a step produces (matches the
+ * ox_linkedin.sequence_actions.action_kind enum), or null for gate/wait steps
+ * that dispatch nothing. NOTE: this is the *action* kind, not the *quota* kind
+ * — visit_profile maps to the quota kind profile_view downstream.
+ */
+export const LINKEDIN_STEP_ACTION_KIND = {
+    visit_profile: "visit_profile",
+    invite: "invite",
+    wait_for_connection: null,
+    wait: null,
+    message: "message",
+    inmail: "inmail",
+};
+const MAX_STEPS = 25;
+const MAX_TEMPLATE_LENGTH = 8_000;
+const MAX_NOTE_LENGTH = 300;
+/**
+ * Validate a raw sequence definition. Returns the normalized definition or
+ * throws OxygenError("invalid_linkedin_sequence") with per-step issues. Pure —
+ * safe to call from any surface.
+ */
+export function validateLinkedInSequenceDefinition(input) {
+    const issues = [];
+    const steps = collectSteps(input, issues);
+    const normalized = [];
+    steps.forEach((rawStep, index) => {
+        const step = normalizeStep(rawStep, index, issues);
+        if (step)
+            normalized.push(step);
+    });
+    validateStructure(normalized, issues);
+    if (issues.length > 0) {
+        throw new OxygenError("invalid_linkedin_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 lintLinkedInSequenceDefinition(input) {
+    try {
+        validateLinkedInSequenceDefinition(input);
+        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_STEPS) {
+        issues.push({ path: "steps", message: `A sequence may have at most ${MAX_STEPS} steps.` });
+    }
+    return steps;
+}
+function normalizeStep(// skipcq: JS-R1005 -- step normalization validates a discriminated sequence DSL with per-step fields.
+raw, index, 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" || !LINKEDIN_SEQUENCE_STEP_KINDS.includes(kind)) {
+        issues.push({
+            path: `${path}.kind`,
+            message: `kind must be one of: ${LINKEDIN_SEQUENCE_STEP_KINDS.join(", ")}.`,
+        });
+        return null;
+    }
+    switch (kind) {
+        case "visit_profile":
+            return { kind: "visit_profile" };
+        case "invite": {
+            const note = optionalTemplate(raw.note_template, `${path}.note_template`, MAX_NOTE_LENGTH, issues);
+            return note !== undefined ? { kind: "invite", note_template: note } : { kind: "invite" };
+        }
+        case "wait_for_connection": {
+            // timeout_days is optional (defaults to 14); only validate when provided.
+            const timeoutDays = raw.timeout_days === undefined || raw.timeout_days === null
+                ? undefined
+                : positiveInt(raw.timeout_days, `${path}.timeout_days`, issues);
+            const onTimeout = raw.on_timeout;
+            if (onTimeout !== undefined && onTimeout !== "stop" && onTimeout !== "continue") {
+                issues.push({ path: `${path}.on_timeout`, message: "on_timeout must be 'stop' or 'continue'." });
+            }
+            return {
+                kind: "wait_for_connection",
+                timeout_days: timeoutDays ?? 14,
+                on_timeout: onTimeout === "continue" ? "continue" : "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 {
+                kind: "wait",
+                ...(days !== undefined ? { days } : {}),
+                ...(hours !== undefined ? { hours } : {}),
+            };
+        }
+        case "message": {
+            const template = requiredTemplate(raw.template, `${path}.template`, issues);
+            return { 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 { kind: "inmail", subject_template: subject ?? "", template: template ?? "" };
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * Structural rules across steps:
+ * - The first send step must be invite or visit_profile (you can't message a
+ *   stranger without connecting); a message before any invite/wait_for_connection
+ *   is valid for warm lists whose leads are already 1st-degree connections.
+ * - wait_for_connection must be preceded by an invite.
+ * - Two consecutive wait/wait_for_connection steps are pointless.
+ */
+function validateStructure(steps, issues) {
+    let sawInvite = false;
+    steps.forEach((step, index) => {
+        if (step.kind === "invite")
+            sawInvite = true;
+        if (step.kind === "wait_for_connection" && !sawInvite) {
+            issues.push({
+                path: `steps[${index}]`,
+                message: "wait_for_connection must come after an invite step.",
+            });
+        }
+        if (step.kind === "message" && !sawInvite && !steps.slice(0, index).some((s) => s.kind === "wait_for_connection")) {
+            // A message before connecting only works for existing 1st-degree
+            // connections. This is valid for warm lists; do not add a fatal issue
+            // until the API has a separate warning channel.
+        }
+    });
+}
+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 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 waitStepDelayMs(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. Unknown placeholders
+ * render empty. Used by the dispatch engine to produce the final message text.
+ */
+export function renderLinkedInTemplate(template, values) {
+    return template.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_match, key) => {
+        const value = values[key];
+        if (value === null || value === undefined)
+            return "";
+        return typeof value === "string" ? value : String(value);
+    });
+}
+/** Column keys referenced by {{...}} placeholders across all steps. */
+export function linkedInTemplateVariables(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);
+        }
+    }
+    return [...vars];
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

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

@@ -1,5 +1,8 @@
 export type TelemetryAttributes = Record<string, unknown>;
-export declare function withTelemetrySpan<T>(tracerName: string, name: string, attributes: TelemetryAttributes | undefined, fn: () => Promise<T>): Promise<T>;
+export type WithTelemetrySpanOptions = {
+    isTransient?: (error: unknown) => boolean;
+};
+export declare function withTelemetrySpan<T>(tracerName: string, name: string, attributes: TelemetryAttributes | undefined, fn: () => Promise<T>, options?: WithTelemetrySpanOptions): Promise<T>;
 export declare function setActiveTelemetryAttributes(attributes: TelemetryAttributes): void;
 export declare function markActiveTelemetryError(message: string, attributes?: TelemetryAttributes): void;
 export declare function addTelemetryEvent(name: string, attributes?: TelemetryAttributes): void;

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

@@ -4,7 +4,7 @@ import { normalizeTelemetryAttributes } from "./redaction.js";
 import { OXYGEN_VERSION } from "./version.js";
 const counterCache = new Map();
 const histogramCache = new Map();
-export async function withTelemetrySpan(tracerName, name, attributes, fn) {
+export async function withTelemetrySpan(tracerName, name, attributes, fn, options) {
     const tracer = trace.getTracer(tracerName, OXYGEN_VERSION);
     return tracer.startActiveSpan(name, { attributes: normalizeTelemetryAttributes(commonTelemetryAttributes(attributes)) }, async (span) => {
         try {
@@ -12,8 +12,16 @@ export async function withTelemetrySpan(tracerName, name, attributes, fn) {
         }
         catch (error) {
             span.recordException(error instanceof Error ? error : new Error(String(error)));
-            span.setStatus({ code: SpanStatusCode.ERROR });
-            span.setAttributes(normalizeTelemetryAttributes(errorTelemetryAttributes(error)));
+            if (options?.isTransient?.(error) === true) {
+                span.setAttributes(normalizeTelemetryAttributes({
+                    ...errorTelemetryAttributes(error),
+                    outcome: "transient_error",
+                }));
+            }
+            else {
+                span.setStatus({ code: SpanStatusCode.ERROR });
+                span.setAttributes(normalizeTelemetryAttributes(errorTelemetryAttributes(error)));
+            }
             throw error;
         }
         finally {
@@ -97,14 +105,18 @@ function getHistogram(name) {
 }
 function errorTelemetryAttributes(error) {
     if (error instanceof Error) {
+        // pg connect timeouts (and some driver errors) surface with an empty
+        // message; fall back to the error name so spans are never message-less.
+        const message = error.message.trim() ? error.message : error.name || "unknown_error";
         return {
             "error.id": errorId(error),
             "error.name": error.name,
-            "error.message": error.message,
+            "error.message": message,
         };
     }
+    const text = String(error).trim();
     return {
         "error.id": "non_error",
-        "error.message": String(error),
+        "error.message": text || "unknown_error",
     };
 }

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

@@ -1,2 +1,2 @@
-export declare const OXYGEN_VERSION = "1.142.4";
+export declare const OXYGEN_VERSION = "1.152.15";
 export declare const OXYGEN_MINIMUM_CLI_VERSION = "1.135.0";

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

@@ -1,3 +1,3 @@
-export const OXYGEN_VERSION = "1.142.4";
+export const OXYGEN_VERSION = "1.152.15";
 // Bump this only when deployed CLI/API contracts require a newer CLI.
 export const OXYGEN_MINIMUM_CLI_VERSION = "1.135.0";

package/node_modules/@oxygen/shared/dist/workflow-trigger-metadata.d.ts

@@ -0,0 +1,2 @@
+export declare const WORKFLOW_TRIGGER_AUTO_PAUSE_METADATA_KEYS: readonly ["consecutive_failure_count", "last_failure_code", "last_failure_at", "auto_paused_at", "auto_pause_reason"];
+export declare function clearWorkflowTriggerAutoPauseMetadata(metadata: Record<string, unknown>): Record<string, unknown>;

package/node_modules/@oxygen/shared/dist/workflow-trigger-metadata.js

@@ -0,0 +1,14 @@
+export const WORKFLOW_TRIGGER_AUTO_PAUSE_METADATA_KEYS = [
+    "consecutive_failure_count",
+    "last_failure_code",
+    "last_failure_at",
+    "auto_paused_at",
+    "auto_pause_reason",
+];
+export function clearWorkflowTriggerAutoPauseMetadata(metadata) {
+    const next = { ...metadata };
+    for (const key of WORKFLOW_TRIGGER_AUTO_PAUSE_METADATA_KEYS) {
+        delete next[key];
+    }
+    return next;
+}

package/package.json

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