@oxygen-agent/cli 1.1014.136 → 1.1014.618

package/dist/commands/whatsapp.js

@@ -0,0 +1,226 @@
+import { addContractFlags } from "../contract-flags.js";
+import { requestOxygen } from "../http-client.js";
+import { addWhatsAppLimitFlags, buildSenderLimitsBody } from "../sender-limits-flags.js";
+import { readOption } from "../util.js";
+import { WHATSAPP_ACCOUNT_FLAGS, whatsappAccountQuery } from "../whatsapp-account-flags.js";
+import { WHATSAPP_ACCOUNTS_READ_CONTRACT } from "@oxygen/shared/contracts/whatsapp-reads";
+import { Command } from "commander";
+export function registerWhatsappFamily(program, handleAsyncAction) {
+    program.addCommand(new Command("whatsapp")
+        .description("Manage the org's connected WhatsApp accounts for Sequencer: accounts (list), connect, sync, inspect, disconnect, tune daily limits, and warm-send into an existing conversation. Cold outbound runs through a WhatsApp sequence (sequences create --channels whatsapp).")
+        .addCommand(addContractFlags(new Command("accounts")
+        .description("Read stored WhatsApp account health. Disconnected accounts are hidden by default; --include-disconnected includes retained accounts, --status selects one status. Presence is not send readiness. Use summary and exact account-id/value for long public metadata."), WHATSAPP_ACCOUNTS_READ_CONTRACT, WHATSAPP_ACCOUNT_FLAGS)
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("whatsapp accounts", options, () => {
+            const suffix = whatsappAccountQuery(options).toString();
+            return requestOxygen(`/api/cli/whatsapp/accounts${suffix ? `?${suffix}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("connect")
+        .description("Get a hosted sign-in link to connect a new WhatsApp account by scanning a QR in WhatsApp → Linked Devices (or reconnect with --reconnect). Running this command creates a pending provider authorization. Inspect the current monthly price and first billing timing with `oxygen billing commitments --view connection-prices --json` before connecting. Newly connected accounts start a mandatory warm-up ramp.")
+        .option("--reconnect <connection_id>", "Reconnect an existing connection id instead of linking a new account.")
+        .option("--pairing-phone-number <phone>", "Offer phone-number pairing instead of QR where supported; use your international number.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("whatsapp connect", options, () => {
+            const reconnect = readOption(options.reconnect);
+            const pairingPhoneNumber = readOption(options.pairingPhoneNumber);
+            return requestOxygen("/api/cli/whatsapp/connect", {
+                method: "POST",
+                body: {
+                    ...(reconnect ? { reconnect_connection_id: reconnect } : {}),
+                    ...(pairingPhoneNumber ? { pairing_phone_number: pairingPhoneNumber } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("get")
+        .description("Get one WhatsApp account with limits, warm-up ramp state (account age + today's effective send ceiling), daily-reset timezone, and usage. Direct sends are warm-only; opted-in WhatsApp Sequences share these caps. <id> accepts an account id, connection id, or Unipile account id.")
+        .argument("<id>", "WhatsApp account id, connection id, or Unipile account id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("whatsapp get", options, () => requestOxygen(`/api/cli/whatsapp/accounts/${encodeURIComponent(id)}`));
+    }))
+        .addCommand(new Command("sync")
+        .description("Refresh WhatsApp account state (status) from Unipile. Pass --connection-id to sync one account, or omit to sync all.")
+        .option("--connection-id <id>", "Sync a specific connection id. Defaults to syncing all connected accounts.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("whatsapp sync", options, () => {
+            const connectionId = readOption(options.connectionId);
+            return requestOxygen("/api/cli/whatsapp/accounts/sync", {
+                method: "POST",
+                body: { ...(connectionId ? { connection_id: connectionId } : {}) },
+            });
+        });
+    }))
+        .addCommand(new Command("disconnect")
+        .description("Disconnect a WhatsApp account so it stops sending. Works on an account that is already disconnected. <id> accepts an account id, connection id, or Unipile account id.")
+        .argument("<id>", "WhatsApp account id, connection id, or Unipile account id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("whatsapp disconnect", options, () => requestOxygen(`/api/cli/whatsapp/accounts/${encodeURIComponent(id)}`, { method: "DELETE" }));
+    }))
+        .addCommand(new Command("limits")
+        .description("View and adjust per-account WhatsApp daily limits and the daily-reset timezone. The warm-up ramp is a non-bypassable ceiling on direct sends and opted-in Sequence actions.")
+        .addCommand(new Command("get")
+        .description("Show current WhatsApp limits, the warm-up ramp state, direct-versus-Sequence delivery policy, daily-reset timezone, defaults, and safe maximums. <id> accepts an account id, connection id, or Unipile account id.")
+        .argument("<id>", "WhatsApp account id, connection id, or Unipile account id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("whatsapp limits get", options, () => requestOxygen(`/api/cli/whatsapp/accounts/${encodeURIComponent(id)}/limits`));
+    }))
+        .addCommand(addWhatsAppLimitFlags(new Command("set")
+        .description("Adjust per-account WhatsApp daily limits and the daily-reset timezone. Values are clamped to safe maximums; the warm-up ceiling still applies to direct and Sequence traffic. <id> accepts an account id, connection id, or Unipile account id.")
+        .argument("<id>", "WhatsApp account id, connection id, or Unipile account id."))
+        .option("--working-days <days>", "Allowed weekdays, e.g. mon-fri or 1,3,5.")
+        .option("--working-hours-start <HH:MM>", "Local start of the allowed sending window.")
+        .option("--working-hours-end <HH:MM>", "Local end of the allowed sending window.")
+        .option("--timezone <tz>", "IANA timezone the daily action counters reset in, e.g. America/New_York.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("whatsapp limits set", options, () => {
+            const body = buildSenderLimitsBody(options);
+            return requestOxygen(`/api/cli/whatsapp/accounts/${encodeURIComponent(id)}/limits`, {
+                method: "PATCH",
+                body,
+            });
+        });
+    })))
+        .addCommand(new Command("warm-send")
+        .description("Send ONE warm WhatsApp message into an EXISTING conversation (warm-only; a cold phone number with no prior conversation is rejected). Approval-gated: omit --approved for a preview, then re-run with --approved to send. For cold outbound at scale, use a WhatsApp sequence instead.")
+        .requiredOption("--account <ref>", "Connected WhatsApp account id, connection id, Unipile account id, or display-name ref that owns the conversation.")
+        .requiredOption("--text <text>", "Message text to send.")
+        .option("--conversation <id>", "Existing WhatsApp conversation id or Unipile chat id to send into.")
+        .option("--approved", "Actually send. Omit for a preview only.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("whatsapp warm-send", options, () => {
+            const account = readOption(options.account);
+            const text = readOption(options.text);
+            if (!account)
+                throw new Error("--account is required.");
+            if (!text)
+                throw new Error("--text is required.");
+            const conversation = readOption(options.conversation);
+            if (!conversation) {
+                throw new Error("--conversation is required — warm-send targets an existing WhatsApp conversation, not a cold phone number.");
+            }
+            return requestOxygen("/api/cli/whatsapp/warm-send", {
+                method: "POST",
+                body: {
+                    account,
+                    text,
+                    conversation_id: conversation,
+                    ...(options.approved ? { approved: true } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("history")
+        .description("Backfill one WhatsApp conversation's full message history. Poll the same command until status is SYNC_DONE. This is the only history backfill WhatsApp has — `whatsapp sync` refreshes account status, not messages.")
+        .argument("<chat>", "Unipile chat id of the conversation to backfill.")
+        .option("--account <ref>", "Connected WhatsApp account (account id, connection id, or Unipile account id). Required only when several are connected.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (chat, options) => {
+        await handleAsyncAction("whatsapp history", options, () => {
+            const account = readOption(options.account);
+            return requestOxygen(`/api/cli/whatsapp/chats/${encodeURIComponent(chat)}/sync`, {
+                method: "POST",
+                body: { ...(account ? { account } : {}) },
+            });
+        });
+    }))
+        .addCommand(new Command("profile")
+        .description("Show or edit the connected number's own WhatsApp profile (display name, About/status, picture).")
+        .addCommand(new Command("show")
+        .description("Show the connected number's WhatsApp profile.")
+        .option("--account <ref>", "Connected WhatsApp account. Required only when several are connected.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("whatsapp profile show", options, () => {
+            const account = readOption(options.account);
+            const suffix = account ? `?account=${encodeURIComponent(account)}` : "";
+            return requestOxygen(`/api/cli/whatsapp/profile${suffix}`);
+        });
+    }))
+        .addCommand(new Command("edit")
+        .description("Edit the connected number's WhatsApp profile. Every contact who has the number sees the change, so this is approval-gated: omit --approved for a preview.")
+        .option("--display-name <name>", "New WhatsApp display name.")
+        .option("--about <text>", "New About/status text.")
+        .option("--picture <url>", "New profile picture (file path or URL).")
+        .option("--account <ref>", "Connected WhatsApp account. Required only when several are connected.")
+        .option("--approved", "Actually apply the edit. Omit for a preview only.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("whatsapp profile edit", options, () => {
+            const displayName = readOption(options.displayName);
+            const about = readOption(options.about);
+            const picture = readOption(options.picture);
+            if (!displayName && !about && !picture) {
+                throw new Error("Pass at least one of --display-name, --about, or --picture.");
+            }
+            const account = readOption(options.account);
+            return requestOxygen("/api/cli/whatsapp/profile", {
+                method: "PATCH",
+                body: {
+                    ...(displayName ? { display_name: displayName } : {}),
+                    ...(about ? { about } : {}),
+                    ...(picture ? { picture_url: picture } : {}),
+                    ...(account ? { account } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                },
+            });
+        });
+    })))
+        .addCommand(new Command("chat-action")
+        .description("Act on one WhatsApp chat: read/mute/archive/pin state, labels, group membership, or the group invite link.")
+        .argument("<chat>", "Unipile chat id.")
+        .requiredOption("--action <action>", "setReadStatus | setMuteStatus | setArchiveStatus | setPinnedStatus | setLabel | addParticipant | removeParticipant | getInviteLink.")
+        .option("--value <value>", "Required for every action except getInviteLink: true/false for the status actions, a participant id for addParticipant/removeParticipant, or the label text for setLabel.")
+        .option("--account <ref>", "Connected WhatsApp account. Required only when several are connected.")
+        .option("--approved", "Required for actions other participants can see (addParticipant, removeParticipant, getInviteLink). Omit for a preview.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (chat, options) => {
+        await handleAsyncAction("whatsapp chat-action", options, () => {
+            const action = readOption(options.action);
+            if (!action)
+                throw new Error("--action is required.");
+            const value = readOption(options.value);
+            const account = readOption(options.account);
+            return requestOxygen(`/api/cli/whatsapp/chats/${encodeURIComponent(chat)}/action`, {
+                method: "POST",
+                body: {
+                    action,
+                    ...(value !== undefined && value !== null ? { value } : {}),
+                    ...(account ? { account } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("forward")
+        .description("Forward an existing WhatsApp message into another chat. This delivers a new message, so it spends send budget and is approval-gated: omit --approved for a preview.")
+        .argument("<message>", "Unipile message id to forward.")
+        .requiredOption("--to-chat <id>", "Unipile chat id to forward the message into.")
+        .option("--account <ref>", "Connected WhatsApp account. Required only when several are connected.")
+        .option("--approved", "Actually forward. Omit for a preview only.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (message, options) => {
+        await handleAsyncAction("whatsapp forward", options, () => {
+            const toChat = readOption(options.toChat);
+            if (!toChat)
+                throw new Error("--to-chat is required.");
+            const account = readOption(options.account);
+            return requestOxygen(`/api/cli/whatsapp/messages/${encodeURIComponent(message)}/forward`, {
+                method: "POST",
+                body: {
+                    to_chat_id: toChat,
+                    ...(account ? { account } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                },
+            });
+        });
+    })));
+}

package/dist/commands/whoami.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerWhoamiFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;

package/dist/commands/whoami.js

@@ -0,0 +1,110 @@
+import { emitCliFailure, writeJson } from "../cli-output.js";
+import { ansi, describeProfileSource, identityFromWhoami, resolveActiveProfileWithSource, storedOrganizationFromOption } from "../command-support.js";
+import { defaultApiUrl, readEnvToken, saveCredentials } from "../credentials.js";
+import { requestOxygen } from "../http-client.js";
+import { success } from "@oxygen/shared/cli-result";
+import { OXYGEN_VERSION } from "@oxygen/shared/version";
+import { stdout as output } from "node:process";
+async function handleWhoamiAction(options) {
+    try {
+        const identity = await requestOxygen("/api/cli/whoami", {
+            enforceMinimumCliVersion: false,
+        });
+        const context = await resolveActiveProfileWithSource();
+        // Compact, credential-free identity shape for health probes and ops
+        // sweeps: the full envelope carries apiKey token prefix/suffix metadata,
+        // which forced every automated consumer to sanitize before logging
+        // (recurring fleet friction since 2026-06-18).
+        if (options.summaryJson) {
+            writeJson(success("whoami", {
+                user: { id: identity.user.id, email: identity.user.email },
+                organization: {
+                    id: identity.organization.id,
+                    name: identity.organization.name,
+                    slug: identity.organization.slug,
+                },
+                auth_type: identity.authType ?? identity.apiKey?.kind ?? null,
+                profile: context.resolution.exists ? context.resolution.name : null,
+                profile_source: context.source,
+                api_url: context.resolution.credentials?.apiUrl ?? null,
+                cli_version: OXYGEN_VERSION,
+            }));
+            return;
+        }
+        if (context.resolution.exists) {
+            const existingCredentials = context.resolution.credentials;
+            const cached = existingCredentials?.identity;
+            const cachedOrg = existingCredentials?.activeOrganization ?? cached?.organization ?? null;
+            const orgChanged = !cachedOrg || cachedOrg.id !== identity.organization.id;
+            const userChanged = !cached || cached.user.id !== identity.user.id;
+            // Heal only from a request that ran as this profile. An environment token
+            // replaces its token, and OXYGEN_ORG or --org picks a workspace for this
+            // command only; saving what either resolved repointed the profile, and with
+            // it every later unpinned command in every shell that shares it (2026-10-05).
+            const pinnedElsewhere = Boolean(process.env.OXYGEN_ORG?.trim()) && orgChanged;
+            if (existingCredentials && !readEnvToken() && !pinnedElsewhere && (orgChanged || userChanged)) {
+                const refreshed = {
+                    token: existingCredentials.token,
+                    apiUrl: existingCredentials.apiUrl,
+                    activeOrganization: storedOrganizationFromOption(identity.organization),
+                    identity: identityFromWhoami(identity),
+                };
+                if (existingCredentials.authKind)
+                    refreshed.authKind = existingCredentials.authKind;
+                await saveCredentials(refreshed, process.env, {
+                    profile: context.resolution.name,
+                    activate: false,
+                }).catch(() => undefined);
+            }
+        }
+        const data = {
+            ...identity,
+            profile: context.resolution.exists ? context.resolution.name : null,
+            profile_source: context.source,
+        };
+        if (options.json) {
+            writeJson(success("whoami", data));
+            return;
+        }
+        process.stdout.write(formatWhoami(identity, context));
+    }
+    catch (error) {
+        emitCliFailure("whoami", error);
+    }
+}
+function formatWhoami(identity, context) {
+    const styles = ansi(output.isTTY === true && !process.env.NO_COLOR);
+    const email = identity.user.email ?? identity.user.id;
+    const orgName = identity.organization.name || identity.organization.slug || identity.organization.id;
+    const orgSlug = identity.organization.slug ?? null;
+    const org = orgSlug && orgSlug !== orgName ? `${orgName} (${orgSlug})` : orgName;
+    const sourceLabel = describeProfileSource(context.source);
+    const profileName = context.resolution.exists ? context.resolution.name : "(no stored profile)";
+    const apiUrl = context.resolution.credentials?.apiUrl ?? defaultApiUrl();
+    // Every Oxygen size shares plan_tier "oxygen"; the name says which size.
+    const planName = identity.organization.plan_name ?? null;
+    const rows = [
+        ["Account", email],
+        ["Organization", org],
+        ...(planName ? [["Plan", planName]] : []),
+        ["Profile", `${profileName} ${styles.dim(`(${sourceLabel})`)}`],
+        ["API", apiUrl],
+    ];
+    const labelWidth = Math.max(...rows.map(([label]) => label.length));
+    const lines = [
+        "",
+        ...rows.map(([label, value]) => `  ${styles.dim(label.padEnd(labelWidth))}   ${value}`),
+        "",
+    ];
+    return lines.join("\n");
+}
+export function registerWhoamiFamily(program, handleAsyncAction) {
+    program
+        .command("whoami")
+        .description("Show the current Oxygen CLI identity.")
+        .option("--json", "Print a JSON envelope.")
+        .option("--summary-json", "Print a compact identity envelope with no credential-shaped fields (safe for health probes and logs).")
+        .action(async (options) => {
+        await handleWhoamiAction(options);
+    });
+}

package/dist/commands/worker.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerWorkerFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;

package/dist/commands/worker.js

@@ -0,0 +1,60 @@
+import { readPositiveInt } from "../cli-values.js";
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { Command } from "commander";
+export function registerWorkerFamily(program, handleAsyncAction) {
+    program
+        .command("worker")
+        .description("Background worker commands.")
+        .addCommand(new Command("queue-stats")
+        .description("Show background action and ingestion queue health.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("worker queue-stats", options, () => requestOxygen("/api/cli/worker/queue-stats"));
+    }))
+        .addCommand(new Command("failures")
+        .description("List failed background action and ingestion items.")
+        .option("--queue <queue>", "all, actions, ingestions, or postgres_queue. Defaults to all. Legacy aliases: postgres_jobs, bullmq, redis, jobs.")
+        .option("--limit <n>", "Maximum failed items per queue. Defaults to 25; server cap is 100.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("worker failures", options, () => {
+            const query = new URLSearchParams();
+            if (readOption(options.queue))
+                query.set("queue", readOption(options.queue) ?? "");
+            const limit = readPositiveInt(options.limit);
+            if (limit)
+                query.set("limit", String(limit));
+            const suffix = query.toString() ? `?${query.toString()}` : "";
+            return requestOxygen(`/api/cli/worker/failures${suffix}`);
+        });
+    }))
+        .addCommand(new Command("repair")
+        .description("Repair stale background action, ingestion, and workflow queue state.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("worker repair", options, () => requestOxygen("/api/cli/worker/repair", {
+            method: "POST",
+            body: {},
+        }));
+    }))
+        .addCommand(new Command("run-once")
+        .description("Compatibility alias for worker repair; repairs Postgres-backed worker state for the current organization.")
+        .option("--claim-limit <n>", "Compatibility option; ignored by the Postgres worker.")
+        .option("--concurrency <n>", "Compatibility option; ignored by the Postgres worker.")
+        .option("--enrichment-concurrency <n>", "Compatibility option; ignored by the Postgres worker.")
+        .option("--lease-seconds <n>", "Compatibility option; ignored by the Postgres worker.")
+        .option("--provider-timeout-ms <n>", "Compatibility option; ignored by the Postgres worker.")
+        .option("--recipe-timeout-ms <n>", "Compatibility option; ignored by the Postgres worker.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        // The legacy tuning options are accepted for backward compatibility but
+        // intentionally ignored: the Postgres worker has no BullMQ knobs, and the
+        // route runs repairTenantWorkspaceQueues regardless of the request body.
+        // Send an empty body so we stop modeling ignored knobs as meaningful fields.
+        await handleAsyncAction("worker run-once", options, () => requestOxygen("/api/cli/worker/run-once", {
+            method: "POST",
+            body: {},
+        }));
+    }));
+}

package/dist/commands/workflows.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerWorkflowsFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;