@oxygen-agent/cli 1.1014.985 → 1.1014.1087

package/dist/command-families/tables/send.js

@@ -0,0 +1,111 @@
+import { readPositiveInt } from "../../cli-values.js";
+import { readCsvOption } from "../../command-support.js";
+import { readOption, isRecord } from "../../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+// Assemble the `tables send` request: --map pairs (headline sugar) become
+// column-copy mapping entries; --mapping JSON is the literal/path escape hatch;
+// --automap asks the server to resolve the mapping (echoed back). Exactly one
+// mapping source must be chosen, locally, so the error names CLI flags instead
+// of API fields.
+export function buildTablesSendRequest(source, target, options) {
+    const mapping = parseTablesSendMapping(options);
+    if (mapping && options.automap) {
+        throw new OxygenError("invalid_send", "Pass either a mapping (--map/--mapping) or --automap, not both.", { exitCode: 1 });
+    }
+    if (!mapping && !options.automap) {
+        throw new OxygenError("invalid_send", "Pass --map target=source pairs, --mapping <json>, or --automap.", { exitCode: 1 });
+    }
+    const mode = normalizeTablesSendMode(options.mode);
+    const upsertKey = readOption(options.upsertKey);
+    if (mode === "upsert" && !upsertKey) {
+        throw new OxygenError("invalid_send", "--mode upsert requires --upsert-key <target column>.", { exitCode: 1 });
+    }
+    if (mode === "insert" && upsertKey) {
+        throw new OxygenError("invalid_send", "--upsert-key is only valid with --mode upsert.", { exitCode: 1 });
+    }
+    const flattenColumn = readOption(options.flatten);
+    const flattenPath = readOption(options.flattenPath);
+    if (flattenPath && !flattenColumn) {
+        throw new OxygenError("invalid_send", "--flatten-path requires --flatten <column>.", { exitCode: 1 });
+    }
+    const filters = parseTablesSendFilters(options.filter);
+    const pageSize = readPositiveInt(options.pageSize);
+    return {
+        source,
+        target,
+        ...(mapping ? { mapping } : {}),
+        ...(options.automap ? { automap: true } : {}),
+        ...(flattenColumn ? { flatten: { column: flattenColumn, ...(flattenPath ? { path: flattenPath } : {}) } } : {}),
+        ...(filters ? { filters } : {}),
+        mode,
+        ...(upsertKey ? { upsert_key: upsertKey } : {}),
+        ...(pageSize ? { page_size: pageSize } : {}),
+        ...(options.dryRun ? { dry_run: true } : {}),
+    };
+}
+export function parseTablesSendMapping(options) {
+    const pairs = (options.map ?? []).flatMap((entry) => readCsvOption(entry));
+    const mappingJson = readOption(options.mapping);
+    if (pairs.length > 0 && mappingJson) {
+        throw new OxygenError("invalid_send", "Pass either --map pairs or --mapping <json>, not both.", { exitCode: 1 });
+    }
+    if (mappingJson) {
+        let parsed;
+        try {
+            parsed = JSON.parse(mappingJson);
+        }
+        catch {
+            throw new OxygenError("invalid_send", "--mapping is not valid JSON.", { details: { mapping: mappingJson }, exitCode: 1 });
+        }
+        if (!Array.isArray(parsed) || parsed.length === 0 || !parsed.every(isRecord)) {
+            throw new OxygenError("invalid_send", "--mapping must be a non-empty JSON array of { target, source, path? } entries.", { exitCode: 1 });
+        }
+        return parsed;
+    }
+    if (pairs.length === 0)
+        return null;
+    return pairs.map((entry) => {
+        const separator = entry.indexOf("=");
+        if (separator <= 0 || separator === entry.length - 1) {
+            throw new OxygenError("invalid_send", "--map entries must be target=source column pairs, e.g. company=company_name,website=domain.", { details: { entry }, exitCode: 1 });
+        }
+        return {
+            target: entry.slice(0, separator).trim(),
+            source: { type: "column", key: entry.slice(separator + 1).trim() },
+        };
+    });
+}
+export function parseTablesSendFilters(value) {
+    const raw = readOption(value);
+    if (!raw)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new OxygenError("invalid_send", "--filter is not valid JSON.", { details: { filter: raw }, exitCode: 1 });
+    }
+    const entries = Array.isArray(parsed) ? parsed : [parsed];
+    if (entries.length === 0 || !entries.every(isRecord)) {
+        throw new OxygenError("invalid_send", "--filter must be a JSON array of { column, op, value? } objects.", { exitCode: 1 });
+    }
+    return entries;
+}
+export function normalizeTablesSendMode(value) {
+    const normalized = (readOption(value) ?? "insert").toLowerCase();
+    if (normalized === "insert" || normalized === "upsert")
+        return normalized;
+    throw new OxygenError("invalid_send", "--mode must be insert or upsert.", {
+        details: { mode: value },
+        exitCode: 1,
+    });
+}
+// After a live send starts, point the terminal at the durable run's inspection
+// surfaces (stderr, so the machine-read stdout envelope stays clean).
+export function writeTablesSendHint(data) {
+    if (!isRecord(data) || typeof data.ingestion_run_id !== "string")
+        return;
+    const runUrl = typeof data.run_web_url === "string" ? ` (or open ${data.run_web_url})` : "";
+    process.stderr.write(`hint: watch the copy with oxygen table-ingestions wait ${data.ingestion_run_id}${runUrl}\n`);
+}

package/dist/command-manifest.js

@@ -262,6 +262,7 @@ const PREVIEW_BY_DEFAULT_COMMANDS = new Set([
     "domains dns apply",
     "mailboxes warmup enable",
     "mailboxes warmup google",
+    "deliverability workspace-test run",
     "deliverability placement-test run",
     "deliverability placement-test send",
     "managed-inboxes recover",

package/dist/commands/copilot.js

@@ -483,6 +483,7 @@ export function registerCopilotFamily(program, handleAsyncAction) {
         .option("--no-wait", "Post the turn and return immediately without streaming the reply.")
         .option("--context <json>", "Optional JSON object of surface context to attach to the turn.")
         .option("--attach <path>", "Attach a file to this message (repeatable). Spreadsheets become tables the copilot can import and enrich; text documents ground the conversation. Uploaded straight to object storage, so large files are fine.", collectRepeatable, [])
+        .option("--interrupt", "In a Copilot chat, stop a still-working turn and send this message as the next turn instead of being refused. Not with --attach or in an Oxygent chat.")
         .option("--timeout-seconds <n>", "Maximum time to wait for the turn to finish. Defaults to 300.")
         .option("--interval-seconds <n>", "Polling interval while streaming. Defaults to 2.")
         .option("--json", "Print a JSON envelope.")
@@ -501,11 +502,18 @@ export function registerCopilotFamily(program, handleAsyncAction) {
                     message,
                     ...(context ? { context } : {}),
                     ...(attachmentIds.length > 0 ? { attachment_ids: attachmentIds } : {}),
+                    ...(options.interrupt ? { interrupt: true } : {}),
                 },
             });
             // Commander maps --no-wait to `wait: false` (default true).
             if (options.wait === false)
                 return posted;
+            // Held for the turn being stopped: the message becomes the next turn
+            // once that stop lands, so there is no turn of its own to wait on yet.
+            if (posted.queued_after_interrupt === true) {
+                process.stderr.write(`Stopping the current turn; your message runs next. Follow it with \`oxygen copilot get ${sessionId}\`.\n`);
+                return posted;
+            }
             const turn = isRecord(posted.turn) ? posted.turn : {};
             const turnId = typeof turn.id === "string" ? turn.id : "";
             const latestSeq = posted.latest_seq;

package/dist/commands/deliverability.js

@@ -1,3 +1,4 @@
+import { registerWorkspacePlacementCommands } from "../workspace-placement-commands.js";
 import { requestOxygen } from "../http-client.js";
 import { readOption } from "../util.js";
 import { Command, CommanderError, Option } from "commander";
@@ -71,7 +72,7 @@ export function registerDeliverabilityFamily(program, handleAsyncAction) {
         }));
     }))
         .addCommand(new Command("list")
-        .description("Inspect directional inbox-placement tests. Use --view summary for inventory, --status to filter, and pass next_cursor as --cursor until null. count is this page; total and status_counts cover all matches before the cursor. creditsUsed is the original charge; results.refund (summary: refund) records restoration. Plus `pricing`: OXYGEN deliverability monitoring credits per inbox-month, two included tests per inbox per cycle, and the managed extra-test price in force. Covered tests cost no extra credits. The allowance resets each UTC calendar month; unused tests do not roll over. Own-key tests pay the quoted OXYGEN platform fee separately from provider charges. The returned web link opens Accounts; use get for an exact result link. Costs 0 credits and never creates or sends a test; active tests may refresh their observations.")
+        .description("Inspect directional inbox-placement tests. Use --view summary for inventory, --status to filter, and pass next_cursor as --cursor until null. count is this page; total and status_counts cover all matches before the cursor. creditsUsed is recorded original cost; results.refund (summary: refund) records credit or allowance restoration. Credit refunds follow the actual captured charge; test rows do not establish net wallet spend. Plus `pricing`: OXYGEN deliverability monitoring credits per inbox-month, two included tests per inbox per cycle, and the managed extra-test price in force. Covered tests cost no extra credits. The allowance resets each UTC calendar month; unused tests do not roll over. Own-key tests pay the quoted OXYGEN platform fee separately from provider charges. The returned web link opens Accounts; use get for an exact result link. Costs 0 credits and never creates or sends a test; active tests may refresh their observations.")
         .option("--limit <n>", "Max rows (default 50, cap 200).")
         .option("--status <status>", "Filter: pending_send, sending, awaiting_results, completed, incomplete, failed.")
         .option("--cursor <cursor>", "Continue from next_cursor with the same status filter.")
@@ -89,10 +90,11 @@ export function registerDeliverabilityFamily(program, handleAsyncAction) {
         });
     }))
         .addCommand(new Command("get")
-        .description("Inspect one saved directional inbox-placement test by id: status, seed counts, per-provider results, and a web result link. creditsUsed is the original charge; results.refund records any restoration. Costs 0 credits and never creates or sends a test; active tests may refresh their observations. Zapmail results land async (2-24h); keep polling while status is awaiting_results.")
+        .description("Inspect a saved directional placement report and refund receipt; recorded cost is not net wallet spend. creditsUsed retains recorded cost; results.refund records credit or allowance restoration. Credit refunds follow the actual captured charge. Includes status, seed counts, per-provider results and a web result link. Costs 0 credits and never creates or sends a test; active tests may refresh their observations. Zapmail results land async (2-24h); keep polling while status is awaiting_results.")
         .argument("<id>", "Placement test id.")
         .option("--json", "Print a JSON envelope.")
         .action(async (id, options) => {
         await handleAsyncAction("deliverability placement-test get", options, () => requestOxygen(`/api/cli/deliverability/placement-tests/${encodeURIComponent(id)}`));
     }))));
+    registerWorkspacePlacementCommands(program.commands.find(c => c.name() === "deliverability"), handleAsyncAction);
 }

package/dist/commands/sequences.js

@@ -1593,6 +1593,7 @@ export function registerSequencesFamily(program, handleAsyncAction) {
         .option("--senders <ids>", "Comma-separated LinkedIn or WhatsApp sender account ids (or connection / Unipile ids; `senders list` / `whatsapp accounts` list them). Optional at create; enroll and start require at least one when the journey has LinkedIn or WhatsApp steps (attach later with `sequences update --senders`).")
         .option("--table <id>", "Source table id or slug whose rows supply {{column}} template values.")
         .option("--activation-id <id>", "Guided authored LinkedIn draft: bind the creator's activation and exact First leads Table. Free; retries reuse the native draft.")
+        .option("--activation-revision <n>", "Reviewed current activation revision, a positive safe integer; requires --activation-id. Native first creation checks it before mutation.")
         .option("--from-table <id>", "Alias of --table: the source table id or slug this sequence draws its leads and {{column}} values from.")
         .option("--enroll", "After creating the sequence, immediately enroll every row of the bound table (same as running `sequences enroll --from-table` next). Requires --table/--from-table. Enrolling spends no credits and sends nothing.")
         .option("--url-column <key>", "Column key holding each lead's LinkedIn URL/provider id.")
@@ -1649,6 +1650,11 @@ export function registerSequencesFamily(program, handleAsyncAction) {
             // so it names the same thing here rather than being a second
             // concept; `--table` stays for every existing script.
             const sourceTable = readOption(options.fromTable) ?? readOption(options.table);
+            const activationId = readOption(options.activationId);
+            const activationRevision = readPositiveInt(options.activationRevision);
+            if (options.activationRevision !== undefined && (!activationId || !Number.isSafeInteger(activationRevision))) {
+                throw new OxygenError("invalid_input", "--activation-revision needs --activation-id and a positive safe integer from current onboarding.", { exitCode: 1 });
+            }
             if (options.enroll && !sourceTable) {
                 throw new Error("--enroll needs a source table: pass --from-table <table> (or --table <table>).");
             }
@@ -1662,7 +1668,8 @@ export function registerSequencesFamily(program, handleAsyncAction) {
                     ...(senders.length > 0 ? { senders } : {}),
                     ...(tags.length > 0 ? { tags } : {}),
                     ...(sourceTable ? { source_table_id: sourceTable } : {}),
-                    ...(readOption(options.activationId) ? { activation_id: readOption(options.activationId) } : {}),
+                    ...(activationId ? { activation_id: activationId } : {}),
+                    ...(activationRevision !== undefined ? { activation_revision: activationRevision } : {}),
                     ...(options.enroll ? { enroll_from_table: true } : {}),
                     ...(readOption(options.urlColumn) ? { linkedin_url_column_key: readOption(options.urlColumn) } : {}),
                     ...(email ? { email } : {}),
@@ -1709,6 +1716,9 @@ export function registerSequencesFamily(program, handleAsyncAction) {
         .description("Update a sequence. Journey structure/channels/email binding are draft-only so revised scope receives a fresh launch approval; a started sequence may only re-time waits it already has (clear a delay by zeroing it, never by deleting the step — enrollments track position by index); sender pools can change while draft or paused; launch caps change through `sequences start` after first start. Name, throttles, the sending schedule, tags, the unsubscribe option (off by default), and open/click tracking toggles remain editable as allowed by the server. Pass only the fields you want to change.")
         .addHelpText("after", "\nSenders: email_send.sender_profile_id sends one email from any inbox of a selected person (a lead already assigned to that person keeps its own inbox), and email_send.sender_mailbox_id from one exact inbox of a selected sender; a LinkedIn step's sender_profile_id sends it from a selected person (invite, message, inmail and withdraw_invite share one or none). Omit both to use the lead's assigned person. An email whose From changes needs its own subject_template. `sequences start <sequence>` without --approved shows who sends each step; nothing changes.\n")
         .argument("<sequence>", "Sequence id or slug.")
+        .option("--expected-revision <revision>", "Exact sequence_revision from sequences get; stale edits refuse. Not launch approval.")
+        .option("--activation-id <id>", "Guided activation UUID; requires --activation-revision and --expected-revision.")
+        .option("--activation-revision <revision>", "Current guided activation revision; requires --activation-id and --expected-revision.")
         .option("--name <name>", "New human-readable sequence name.")
         .option("--steps-file <path>", "Path to a JSON file: { \"steps\": [...] } replacing the journey. Once started, only wait timing may change: same steps, same order (zero a delay, never delete its step). Copy supports {{column}} interpolation; every step also takes {{sender_first_name}} / {{sender_last_name}} / {{sender_full_name}} for the person who sends it, and email adds {{sender_email}} (a same-named row column wins). A `branch` can also route on the lead's data with a data leaf { has_column: \"email\" } (true when that row_values column is non-empty; present:false for \"missing\").")
         .option("--channels <list>", "Draft only: comma-separated channels: linkedin,email,whatsapp,call,crm.")
@@ -1771,6 +1781,18 @@ export function registerSequencesFamily(program, handleAsyncAction) {
         .action(async (sequence, options) => {
         await handleAsyncAction("sequences update", options, () => {
             const body = {};
+            const expectedRevision = options.expectedRevision;
+            const activationId = options.activationId;
+            const activationRevision = readPositiveInt(options.activationRevision);
+            if (options.activationRevision !== undefined && activationRevision === undefined) {
+                throw new OxygenError("invalid_number", "Expected a positive activation revision.", { exitCode: 1 });
+            }
+            if (expectedRevision !== undefined)
+                body.expected_revision = expectedRevision;
+            if (activationId !== undefined)
+                body.activation_id = activationId;
+            if (activationRevision !== undefined)
+                body.activation_revision = activationRevision;
             const name = readOption(options.name);
             if (name)
                 body.name = name;
@@ -1834,9 +1856,15 @@ export function registerSequencesFamily(program, handleAsyncAction) {
         .description("Get a sequence's definition, senders, status, and credit usage. --readiness adds the launch check — whether it CAN go live, why not, and the mailbox pool it would send from — without touching it; `sequences preview <sequence>` (a read; 0 credits) shows who sends each step (sender_journey).")
         .argument("<sequence>", "Sequence id or slug.")
         .option("--readiness", "Add launch_readiness: blockers (e.g. a missing send cap), warnings, and the resolved sending mailboxes. Read-only — sends nothing, changes nothing, spends nothing. Skips the LinkedIn rendered-copy scan, which stays in `sequences start` without --approved.")
+        .addOption(new Option("--include <fields>", "Add readiness or your retained guided_proposal, comma-separated. Reading a proposal does not apply it or start the campaign.")
+        .choices(["readiness", "guided_proposal", "readiness,guided_proposal", "guided_proposal,readiness"]))
         .option("--json", "Print a JSON envelope.")
         .action(async (sequence, options) => {
-        await handleAsyncAction("sequences get", options, () => requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}${options.readiness ? "?include=readiness" : ""}`));
+        const include = new Set(options.include?.split(",") ?? []);
+        if (options.readiness)
+            include.add("readiness");
+        const query = include.size ? `?include=${[...include].join(",")}` : "";
+        await handleAsyncAction("sequences get", options, () => requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}${query}`));
     }))
         .addCommand(new Command("enroll")
         .description("Enroll leads into a sequence. Enrolling spends no credits. An active sequence contacts the new leads on its next dispatch tick; a draft or paused one holds them until `sequences start`. --from-table enrolls every not-yet-enrolled row of the sequence's bound source table (up to 500 per run; the response's from_table.has_more says whether to run again) — for a LinkedIn sequence the profile is read from the bound table's URL column, where a full /in/ URL and a bare public handle carrying a hyphen or digit (ada-lovelace) both work, so no pre-resolved provider ids are needed; each handle Oxygen canonicalized is echoed in linkedin_handles_canonicalized (value + url) to check before start, and every row that still cannot be resolved is named in unresolved_linkedin_lead_details (row, value, reason) rather than only counted in unresolved_linkedin_leads. In a LinkedIn + email sequence a row with no usable profile but a recipient email is still enrolled for the email steps (its LinkedIn steps are skipped as no_linkedin_profile, a connection wait passes at once and a connection branch takes its not-connected path) and is listed in linkedin_unavailable_lead_details instead; unresolved_linkedin_leads names only rows that were not enrolled. --leads-file enrolls an explicit JSON list { leads: [...] }: for an email/WhatsApp sequence a lead identified only by an email (row_values.email) or phone (row_values.phone) is auto-filed as a row in the sequence's leads table (auto-creating and binding one if there is none), deduped by email/phone, so no table has to exist first (the table is returned as leads_table with a web_url); a LinkedIn + email sequence auto-files an email-only lead the same way; a LinkedIn lead needs a lead_provider_id, a lead_profile_url (a /in/ URL or a bare public handle with a hyphen or digit), or a table_row_id whose row carries one of those. A CRM-only lead needs a stable table_row_id or lead_provider_id in addition to mapped row_values; a HubSpot contact id used in crm_task associations identifies the destination record, not the Oxygen enrollment. When the sequence is bound to a source table, a lead's table_row_id auto-snapshots that row's columns (incl. AI/tool outputs) into row_values for {{column}} copy — explicit row_values win. Idempotent per table row (and per email/phone for auto-filed leads). WhatsApp-only campaigns also enroll each normalized number once across all source rows and enrollment statuses; mixed campaigns keep other channels and skip duplicate WhatsApp actions. Duplicate protection defaults to this campaign; --whatsapp-duplicate-scope on create/update can additionally block identical copy across all campaigns. The org do-not-contact list is always enforced; --exclude-contacted and --suppress-list add further opt-in skips (reported under skipped_by_reason). Leads already owned by a sender account (from an earlier real send) are routed back to that same account; a lead owned by a sender NOT on this sequence is skipped (bound_to_other_sender) unless --ignore-sender-bindings. This enrolls into an OXYGEN Sequence; to put the same rows into a campaign you already run in Smartlead, Instantly, lemlist or HeyReach, use `sequences push-external`. esp.pool_scope identifies the active workspace inventory used for routing and strict_deferred_leads estimates; these estimates omit sequence sender restrictions, readiness and daily limits. A zero estimate does not guarantee readiness. Review sequences preview before launch.")

package/dist/commands/tables.d.ts

@@ -1,3 +1 @@
-import { ExtractedCommandActionHandler } from "../command-support.js";
-import { Command } from "commander";
-export declare function registerTablesFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler, binaryName: any): void;
+export { registerTablesFamily } from "../command-families/tables/registration.js";