@oxygen-agent/cli 1.883.2 → 1.886.3

package/README.md

@@ -34,4 +34,4 @@ oxygen update
 
 For product documentation, visit https://oxygen-agent.com/docs. For support, visit https://oxygen-agent.com.
 
-Version: 1.883.2
+Version: 1.886.3

package/dist/index.js

@@ -1836,15 +1836,23 @@ function writeSequenceDraftPreview(data) {
         lines.push("Drafted email sequence (preview — not saved):");
     }
     let emailNumber = 0;
+    // The subject the next threaded email continues under. A drafted follow-up
+    // deliberately has no subject of its own — that is what keeps it in the first
+    // email's thread — so show what it actually goes out under rather than the
+    // "(no subject)" that reads like a drafting failure.
+    let threadSubject = null;
     for (const step of steps) {
         if (!step || typeof step !== "object" || Array.isArray(step))
             continue;
         const entry = step;
         if (entry.kind === "email_send") {
             emailNumber += 1;
-            const subject = typeof entry.subject_template === "string" && entry.subject_template.trim()
+            const own = typeof entry.subject_template === "string" && entry.subject_template.trim()
                 ? entry.subject_template.trim()
-                : "(no subject)";
+                : null;
+            if (own)
+                threadSubject = own;
+            const subject = own ?? (threadSubject ? `Re: ${threadSubject} (same thread)` : "(no subject)");
             const variantCount = Array.isArray(entry.variants) ? entry.variants.length : 0;
             lines.push(`  Email ${emailNumber}: ${subject}${variantCount > 0 ? ` (+${variantCount} A/B variant${variantCount === 1 ? "" : "s"})` : ""}`);
         }
@@ -9495,6 +9503,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--journey <slug>", "Optional journey slug to seed the session's goal and context.")
         .option("--title <text>", "Optional human title for the session.")
         .option("--auto-approve", "Start with auto-approve ON for paid, workspace-internal actions (cards are still created and decided automatically within each action's credit cap). External sends, enrollments, publishes, DNS, and external CRM pushes always stay human-gated.")
+        .option("--no-follow", "Start with screen-follow OFF. On by default: while the session is open in the browser, your screen opens onto whatever the copilot creates or changes, with the live session docked beside it. Change it later with `copilot follow`.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("copilot start", options, () => {
@@ -9520,6 +9529,10 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                 body.title = title;
             if (options.autoApprove)
                 body.auto_approve = true;
+            // Commander maps --no-follow to `follow: false` (default true), and
+            // the server already defaults to following, so only the opt-out ships.
+            if (options.follow === false)
+                body.surface_policy = "off";
             return requestOxygen("/api/cli/copilot/sessions", { method: "POST", body });
         });
     }))
@@ -9547,6 +9560,17 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             const suffix = query.toString() ? `?${query.toString()}` : "";
             return requestOxygen(`/api/cli/copilot/sessions/${encodeURIComponent(sessionId)}${suffix}`);
         });
+    }))
+        .addCommand(new Command("follow")
+        .description("Turn screen-follow ON (or, with --off, OFF) for an open Workspace Copilot session: while it is open in the browser, your screen opens onto whatever the copilot creates or changes, with the live session docked beside it. Same switch as the web composer's \"Show me\" toggle; changes nothing about what the session is allowed to do.")
+        .argument("<sessionId>", "Copilot session id.")
+        .option("--off", "Stop following: the copilot keeps working, your screen just stays where it is.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sessionId, options) => {
+        await handleAsyncAction("copilot follow", options, () => requestOxygen(`/api/cli/copilot/sessions/${encodeURIComponent(sessionId)}`, {
+            method: "PATCH",
+            body: { surface_policy: options.off ? "off" : "follow" },
+        }));
     }))
         .addCommand(new Command("send")
         .description("Send a message to a Workspace Copilot session and stream the reply to stderr. Waits for the turn to finish (or pause for an approval) unless --no-wait. Inference bills credits at 5x the actual model cost within the session budget.")
@@ -12354,7 +12378,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .description("Create a draft multichannel sequence from a steps JSON file. Supports LinkedIn, email, WhatsApp, human call_task, and connected-CRM crm_task journeys. Assign LinkedIn senders with --senders (optional at create — a draft can sit senderless, but enroll/start require at least one for LinkedIn journeys); bind an Instantly email track with --email-*. Install/read the oxygen-sequencer skill for complete mapped CRM task examples.")
         .requiredOption("--name <name>", "Human-readable sequence name.")
         .requiredOption("--slug <slug>", "Unique slug for the sequence.")
-        .requiredOption("--steps-file <path>", "Path to a JSON file: { \"steps\": [...] }. LinkedIn steps (visit_profile | invite | wait_for_connection | message | inmail | follow | like_post | comment_post | withdraw_invite), email steps (email_send | email_reply | email_enroll | email_move | email_stop), WhatsApp (whatsapp_message), human call tasks (call_task), connected-CRM tasks (crm_task; channel crm; exact identity record_mappings + explicit create/update policy + record_links + dynamic task property_mappings/associations), and control steps (wait | wait_for_signal | branch | stop), each with an `id`. Copy templates support {{column}} interpolation from the lead's row, {{column|fallback}} inline fallbacks, deterministic spintax — {{RANDOM|a|b|c}} or industry-standard bare {Hi|Hey|Hello}, nestable like {Would {Tuesday|Thursday} work|next week?} — and {% if column %}…{% endif %} conditionals; a bare {…} region is spintax only when it contains a top-level |, so literal braces (CSS/JSON) pass through. Native email sends (email_send/email_reply) also expose three reserved sender variables from the sending mailbox: {{sender_name}} (mailbox display name), {{sender_first_name}} (its first word), and {{sender_email}} (the from address); a row column of the same name WINS on collision, and a missing display name renders empty. comment_post takes text_template and/or ai_prompt — a KG-grounded comment generated at send time (a paid AI call) that falls back to text_template if generation fails. A `branch` routes on signals (then/else) or the legacy connection_accepted/already_connected/open_profile sugar (then_id/else_id). A signal condition can also branch on the LEAD'S DATA: a data leaf { has_column: \"email\" } is true when that row_values column has a non-empty value (add present:false for \"missing\") — e.g. route leads that have an email down an email arm and the rest down a LinkedIn arm. MINIMAL EMAIL STEP SHAPE: { \"id\": \"s1\", \"channel\": \"email\", \"kind\": \"email_send\", \"subject_template\": \"...\", \"body_template\": \"...\" } — subject_template + body_template are REQUIRED on email_send; A/B tests use an explicit `variants` array of copy partials on the step (up to 25 alternates, a–z; spintax varies wording INSIDE one variant and is not A/B-tracked). For the complete replay-safe crm_task upsert mapping shape, install/read the oxygen-sequencer skill.")
+        .requiredOption("--steps-file <path>", "Path to a JSON file: { \"steps\": [...] }. LinkedIn steps (visit_profile | invite | wait_for_connection | message | inmail | follow | like_post | comment_post | withdraw_invite), email steps (email_send | email_enroll | email_move | email_stop), WhatsApp (whatsapp_message), human call tasks (call_task), connected-CRM tasks (crm_task; channel crm; exact identity record_mappings + explicit create/update policy + record_links + dynamic task property_mappings/associations), and control steps (wait | wait_for_signal | branch | stop), each with an `id`. Copy templates support {{column}} interpolation from the lead's row, {{column|fallback}} inline fallbacks, deterministic spintax — {{RANDOM|a|b|c}} or industry-standard bare {Hi|Hey|Hello}, nestable like {Would {Tuesday|Thursday} work|next week?} — and {% if column %}…{% endif %} conditionals; a bare {…} region is spintax only when it contains a top-level |, so literal braces (CSS/JSON) pass through. Native email sends (email_send) also expose three reserved sender variables from the sending mailbox: {{sender_name}} (mailbox display name), {{sender_first_name}} (its first word), and {{sender_email}} (the from address); a row column of the same name WINS on collision, and a missing display name renders empty. comment_post takes text_template and/or ai_prompt — a KG-grounded comment generated at send time (a paid AI call) that falls back to text_template if generation fails. A `branch` routes on signals (then/else) or the legacy connection_accepted/already_connected/open_profile sugar (then_id/else_id). A signal condition can also branch on the LEAD'S DATA: a data leaf { has_column: \"email\" } is true when that row_values column has a non-empty value (add present:false for \"missing\") — e.g. route leads that have an email down an email arm and the rest down a LinkedIn arm. MINIMAL EMAIL STEP SHAPE: { \"id\": \"s1\", \"channel\": \"email\", \"kind\": \"email_send\", \"subject_template\": \"...\", \"body_template\": \"...\" } — body_template is REQUIRED on email_send; subject_template is OPTIONAL and is the one control that decides threading: give a step its own subject and it goes out as a NEW email, omit it and the step continues the lead's previous email in the same thread (what the retired email_reply kind used to be — still accepted on input and rewritten into this shape). The FIRST email step of a sequence must carry a subject, since it has no earlier thread to continue; A/B tests use an explicit `variants` array of copy partials on the step (up to 25 alternates, a–z; spintax varies wording INSIDE one variant and is not A/B-tracked). For the complete replay-safe crm_task upsert mapping shape, install/read the oxygen-sequencer skill.")
         .option("--channels <list>", "Comma-separated channels: linkedin,email,whatsapp,call,crm. Defaults to the channels the journey touches. crm_task currently supports HubSpot.")
         .option("--whatsapp-cold-initiate", "WhatsApp: allow cold-initiating new chats (no prior conversation). Required to start a WhatsApp sequence live — WhatsApp via Unipile is unofficial WhatsApp Web, so cold-initiating is an explicit ban-risk opt-in.")
         .option("--phone-column-key <key>", "WhatsApp: row_values key holding each lead's phone number (else falls back to phone/phone_number/mobile).")

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

@@ -426,8 +426,21 @@ export type SequenceEmailSendStep = {
     id: string;
     channel: "email";
     kind: "email_send";
-    /** Subject line. Supports {{column}} interpolation. */
-    subject_template: string;
+    /**
+     * Subject line. Supports {{column}} interpolation.
+     *
+     * OPTIONAL, and that option IS the one-email-action model: writing a subject
+     * opens a NEW thread, leaving it blank CONTINUES the lead's existing one. The
+     * builder pre-fills a follow-up step with the previous email's subject, so
+     * leaving it alone threads and typing a different one forks a new email. Blank
+     * or absent therefore means exactly what the retired `email_reply` kind meant,
+     * and a stored legacy `email_reply` normalizes into precisely this shape.
+     *
+     * The FIRST native email step has no thread to continue, so it must carry a
+     * subject — enforced by validateSequenceDefinition (and reported as missing
+     * copy on a draft, which is allowed to be half-written).
+     */
+    subject_template?: string;
     /** Body (plain text). Supports {{column}} interpolation. */
     body_template: string;
     /** Optional HTML body (B-W2): renders the send as multipart/alternative. Supports {{column}}. */
@@ -446,7 +459,15 @@ export type SequenceEmailSendStep = {
     /** Per-step send window (overrides the sequence-level email_send_window). */
     send_window?: SequenceSendWindow;
 };
-/** Threaded follow-up in the same email thread as the lead's prior email_send. */
+/**
+ * LEGACY threaded follow-up, retired as an authored step kind.
+ *
+ * "Reply in thread" merged into "Send email": a subject-less `email_send` IS the
+ * threaded follow-up. normalizeStep rewrites any incoming `email_reply` into that
+ * shape, so no newly written definition contains this kind — but definitions
+ * stored before the merge do, and the planner/dispatcher still execute them
+ * unchanged, so the type stays.
+ */
 export type SequenceEmailReplyStep = {
     id: string;
     channel: "email";
@@ -468,6 +489,26 @@ export type SequenceEmailReplyStep = {
     /** Per-step send window (overrides the sequence-level email_send_window). */
     send_window?: SequenceSendWindow;
 };
+/**
+ * Does this email step continue the lead's existing thread instead of opening a
+ * new one? True for a subject-less `email_send` (the merged model) and for a
+ * stored legacy `email_reply`. The single predicate every surface reads: the
+ * planner (which action kind to materialize), the send payload, the canvas, and
+ * the builder's subject field.
+ */
+export declare function sequenceEmailStepThreads(step: SequenceStep): boolean;
+/**
+ * The subject a threaded email step inherits: the nearest PRECEDING email step
+ * that opens a thread of its own, in flat step order. Flat order is the order the
+ * dispatcher's "latest email message ref for this enrollment" resolves in, so
+ * this is the subject the send actually lands under. Null when nothing precedes
+ * it — the state validateSequenceDefinition rejects, because a threaded send with
+ * no thread would go out with no subject at all.
+ */
+export declare function sequenceInheritedEmailSubject(steps: readonly {
+    readonly kind: string;
+    readonly subject_template?: string;
+}[], index: number): string | null;
 /**
  * Native WhatsApp message send through one of the sequence's WhatsApp senders
  * (Unipile chats_messages_send into an existing chat, else chats_create to open

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

@@ -629,6 +629,43 @@ export const SEQUENCE_STEP_KINDS = [
     "branch",
     "stop",
 ];
+/**
+ * Does this email step continue the lead's existing thread instead of opening a
+ * new one? True for a subject-less `email_send` (the merged model) and for a
+ * stored legacy `email_reply`. The single predicate every surface reads: the
+ * planner (which action kind to materialize), the send payload, the canvas, and
+ * the builder's subject field.
+ */
+export function sequenceEmailStepThreads(step) {
+    if (step.kind === "email_reply")
+        return true;
+    if (step.kind !== "email_send")
+        return false;
+    return !(step.subject_template ?? "").trim();
+}
+/**
+ * The subject a threaded email step inherits: the nearest PRECEDING email step
+ * that opens a thread of its own, in flat step order. Flat order is the order the
+ * dispatcher's "latest email message ref for this enrollment" resolves in, so
+ * this is the subject the send actually lands under. Null when nothing precedes
+ * it — the state validateSequenceDefinition rejects, because a threaded send with
+ * no thread would go out with no subject at all.
+ */
+export function sequenceInheritedEmailSubject(
+// Structural rather than SequenceStep[]: the planner walks a looser PlanStep[]
+// (it accepts channel-less LinkedIn steps), and this only ever reads kind +
+// subject_template.
+steps, index) {
+    for (let i = Math.min(index, steps.length) - 1; i >= 0; i -= 1) {
+        const prior = steps[i];
+        if (!prior || prior.kind !== "email_send")
+            continue;
+        const subject = prior.subject_template ?? "";
+        if (subject.trim())
+            return subject;
+    }
+    return null;
+}
 // ---- CRM-channel steps (external writes through a connected CRM) ----
 export const SEQUENCE_CRM_TASK_PROVIDERS = ["hubspot"];
 export const SEQUENCE_CRM_IDENTITY_KINDS = [
@@ -686,7 +723,7 @@ export function sequenceStepsMissingCopy(steps) {
         if (typeof value !== "string" || !value.trim())
             missing.push({ stepId: step.id, kind: step.kind, field });
     };
-    for (const step of steps) {
+    steps.forEach((step, index) => {
         switch (step.kind) {
             case "message":
             case "whatsapp_message":
@@ -697,7 +734,13 @@ export function sequenceStepsMissingCopy(steps) {
                 check(step, "template", step.template);
                 break;
             case "email_send":
-                check(step, "subject_template", step.subject_template);
+                // A blank subject is only "missing copy" on the FIRST email of a journey.
+                // Anywhere after one, blank is a deliberate choice — continue the previous
+                // thread — and demanding a subject there would block the launch of exactly
+                // the follow-up the merged action exists to make one click.
+                if (sequenceInheritedEmailSubject(steps, index) === null) {
+                    check(step, "subject_template", step.subject_template);
+                }
                 check(step, "body_template", step.body_template);
                 break;
             case "email_reply":
@@ -730,7 +773,7 @@ export function sequenceStepsMissingCopy(steps) {
             default:
                 break;
         }
-    }
+    });
     return missing;
 }
 /**
@@ -788,6 +831,35 @@ export function validateSequenceDefinition(input, options = {}) {
     if (!options.nativeTrackingEnabled) {
         reportNativeEngagementGates(normalized, issues);
     }
+    // Pass 4: a threaded email step needs a thread to continue. "Send email" reads
+    // its subject as the fork: written => new thread, blank => continue the previous
+    // email. The first email of a journey has no previous email, so a blank subject
+    // there is not a follow-up, it is a cold send that would go out with no Subject
+    // header at all. Reject it on a real write; a draft is allowed to be half-typed
+    // and surfaces the same gap through sequenceStepsMissingCopy at launch.
+    //
+    // Which "earlier" applies depends on the journey. A LINEAR journey runs in flat
+    // array order, so flat order is exactly what precedes a step. A BRANCHED one does
+    // not: an arm may route backwards, so a step that reads as first in the array can
+    // still be reached after an email that opened a thread — and the dispatcher
+    // resolves the thread from what this enrollment actually SENT, not from step
+    // order. Being stricter than the runtime there would refuse to save a campaign
+    // that works, so a branched journey only has to open a thread somewhere.
+    if (options.draft !== true) {
+        const branched = normalized.some((step) => step.kind === "branch");
+        const opensAnyThread = normalized.some((step) => step.kind === "email_send" && !sequenceEmailStepThreads(step));
+        normalized.forEach((step, index) => {
+            if (step.kind !== "email_send" || !sequenceEmailStepThreads(step))
+                return;
+            const hasThread = branched ? opensAnyThread : sequenceInheritedEmailSubject(normalized, index) !== null;
+            if (hasThread)
+                return;
+            issues.push({
+                path: `steps[${index}].subject_template`,
+                message: `step '${step.id}' has no subject, which means "continue the previous email" — but no earlier step sends one. Give the first email of the sequence a subject.`,
+            });
+        });
+    }
     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 });
     }
@@ -953,16 +1025,26 @@ raw, index, options, issues) {
             return { id, channel: "email", kind: "email_move", subsequence_id: subsequenceId ?? "" };
         }
         case "email_send": {
-            const subject = requiredTemplate(raw.subject_template, `${path}.subject_template`, issues, options.draft === true);
+            // Subject is optional. Present => a new thread; absent/blank => continue the
+            // lead's existing one (what `email_reply` used to be). A blank one is dropped
+            // rather than stored as "", so the definition states the intent structurally
+            // instead of relying on an empty string being read the right way downstream.
+            const subject = optionalTemplate(raw.subject_template, `${path}.subject_template`, MAX_TEMPLATE_LENGTH, issues);
+            const threaded = !(subject ?? "").trim();
             const body = requiredTemplate(raw.body_template, `${path}.body_template`, issues, options.draft === true);
             const bodyHtml = optionalTemplate(raw.body_html_template, `${path}.body_html_template`, MAX_TEMPLATE_LENGTH, issues);
-            const variants = normalizeVariants(raw.variants, `${path}.variants`, ["subject_template", "body_template", "body_html_template"], issues, options.draft === true);
+            // A threaded step has no subject to override, so its variants may only vary
+            // the body — a subject-only variant then fails normalizeVariants' own
+            // "must override at least one of" check rather than silently doing nothing.
+            const variants = normalizeVariants(raw.variants, `${path}.variants`, threaded ? ["body_template", "body_html_template"] : ["subject_template", "body_template", "body_html_template"], issues, options.draft === true);
             const autoOptimize = normalizeAutoOptimize(raw.auto_optimize, `${path}.auto_optimize`, variants, options, issues);
             const cc = optionalEmailList(raw.cc, `${path}.cc`, issues);
             const bcc = optionalEmailList(raw.bcc, `${path}.bcc`, issues);
             const sendWindow = normalizeSendWindow(raw.send_window, `${path}.send_window`, issues);
             return {
-                id, channel: "email", kind: "email_send", subject_template: subject ?? "", body_template: body ?? "",
+                id, channel: "email", kind: "email_send",
+                ...(threaded ? {} : { subject_template: subject }),
+                body_template: body ?? "",
                 ...(bodyHtml !== undefined ? { body_html_template: bodyHtml } : {}),
                 ...(cc ? { cc } : {}),
                 ...(bcc ? { bcc } : {}),
@@ -972,6 +1054,13 @@ raw, index, options, issues) {
             };
         }
         case "email_reply": {
+            // Retired as an authored kind: "Reply in thread" merged into "Send email",
+            // where a subject-less step IS the threaded follow-up. Anything still writing
+            // `email_reply` — an older CLI, a recipe file, a stored definition being
+            // re-saved — migrates forward here, so every newly written definition holds
+            // exactly one email-send kind. Definitions that are never re-saved keep the
+            // old kind on disk and keep executing: the planner and the dispatcher both
+            // still handle it, and it plans byte-identically to the threaded form.
             const body = requiredTemplate(raw.body_template, `${path}.body_template`, issues, options.draft === true);
             const bodyHtml = optionalTemplate(raw.body_html_template, `${path}.body_html_template`, MAX_TEMPLATE_LENGTH, issues);
             const variants = normalizeVariants(raw.variants, `${path}.variants`, ["body_template", "body_html_template"], issues, options.draft === true);
@@ -980,7 +1069,7 @@ raw, index, options, issues) {
             const bcc = optionalEmailList(raw.bcc, `${path}.bcc`, issues);
             const sendWindow = normalizeSendWindow(raw.send_window, `${path}.send_window`, issues);
             return {
-                id, channel: "email", kind: "email_reply", body_template: body ?? "",
+                id, channel: "email", kind: "email_send", body_template: body ?? "",
                 ...(bodyHtml !== undefined ? { body_html_template: bodyHtml } : {}),
                 ...(cc ? { cc } : {}),
                 ...(bcc ? { bcc } : {}),
@@ -2014,7 +2103,9 @@ export function sequenceVariantLabel(index) {
 function baseVariantContent(step) {
     switch (step.kind) {
         case "email_send": return {
-            subject_template: step.subject_template,
+            // Omitted on a threaded step: there is no subject to vary, and emitting ""
+            // would make sequenceTemplateVariables scan a field the send never renders.
+            ...(step.subject_template ? { subject_template: step.subject_template } : {}),
             body_template: step.body_template,
             // Include the HTML body so its {{column}} refs are scanned by
             // sequenceTemplateVariables (the start preview's variable-resolution check).

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

@@ -1,4 +1,4 @@
-export declare const OXYGEN_VERSION = "1.883.2";
+export declare const OXYGEN_VERSION = "1.886.3";
 export declare const OXYGEN_MINIMUM_CLI_VERSION = "1.181.0";
 export declare const MANAGED_INBOX_MINIMUM_CLI_VERSION = "1.326.2";
 export declare const SUPPORT_AGENT_REPLY_MINIMUM_CLI_VERSION = "1.747.0";

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

@@ -1,4 +1,4 @@
-export const OXYGEN_VERSION = "1.883.2";
+export const OXYGEN_VERSION = "1.886.3";
 // The GLOBAL CLI compatibility floor: the oldest CLI allowed to call any
 // operational route. Raising it hard-rejects every older CLI from the entire
 // product, so it obeys one law, enforced by scripts/ci/cli-min-version-gate.mjs:

package/package.json

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