@oxygen-agent/cli 1.836.4 → 1.837.9

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.836.4
+Version: 1.837.9

package/dist/command-manifest.js

@@ -39,6 +39,9 @@ const MUTATING_VERBS = new Set([
     "bind", "buy", "call", "cancel", "chat-action", "claim", "clear",
     "comment", "configure", "connect", "create", "decide", "delete", "delist", "disable",
     "disconnect", "dispatch", "done", "draft", "duplicate", "edit", "emit", "enable", "enroll",
+    // Exact leaf, not a `field` prefix: `support admin field-set` writes a Plain
+    // Thread field, while a future `field-get` would be a read.
+    "field-set",
     "file", "forward", "grant", "harvest", "history", "import", "insert", "interrupt", "invite",
     "label-add", "label-remove", "launch", "log", "login", "logout", "mark-all-read", "mark-read", "materialize", "merge",
     "migrate",
@@ -47,8 +50,12 @@ const MUTATING_VERBS = new Set([
     "register", "reject", "relink", "remove", "rename", "reorder", "reply", "request",
     "replay", "rerun", "rescan", "resend", "reset", "resolve", "restore", "resume",
     "retry", "retype", "revoke", "rotate", "run", "save", "schedule",
-    "seed", "select", "send", "set", "setup", "share", "solve",
-    "start", "stop", "subscribe", "sync", "synthesize", "tag", "unarchive", "unpublish", "unshare",
+    "seed", "select", "send", "set", "setup", "share", "snooze", "solve",
+    "start", "stop", "subscribe", "sync", "synthesize", "tag",
+    // `support admin todo` moves a Plain Thread back into the queue. The noun
+    // reads like a state, but the command is the transition into it.
+    "todo",
+    "unarchive", "unpublish", "unshare",
     "unbind", "unsubscribe", "update", "upload", "upsert", "use", "warm-send", "warmup",
     "withdraw", "write",
 ]);
@@ -80,6 +87,8 @@ const PREVIEW_BY_DEFAULT_COMMANDS = new Set([
     "mailboxes delete",
     "support admin done",
     "support admin reply",
+    // A bare call reads the Plain workspace and prints the plan; --apply writes.
+    "support admin setup",
     "workflows webhooks rotate",
 ]);
 export function buildCommandManifest(program, binaryName) {

package/dist/index.js

@@ -2966,6 +2966,50 @@ The final readback must show ticket.status triaging, plain_status TODO, the In p
         await handleSupportAdminUpdateRequest("priority", ticketId, options, {
             priority: readOption(options.priority),
         });
+    }))
+        .addCommand(new Command("snooze")
+        .description("Park a live Thread until a named time, so work blocked on a release, a provider, or a scheduled retry stops reading as unanswered (staff only).")
+        .argument("<ticketId>", "Plain Thread ID (th_...).")
+        .option("--days <n>", "Snooze for this many days.")
+        .option("--hours <n>", "Snooze for this many hours. Combined with --days when both are given.")
+        .requiredOption("--confirm-message <messageId>", "Confirm the exact latest customer-visible message ID. A Thread whose customer just wrote must be answered, not snoozed past.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (ticketId, options) => {
+        await handleSupportAdminUpdateRequest("snooze", ticketId, options, {
+            duration_seconds: readSupportSnoozeSeconds(options),
+            confirm_message_id: readOption(options.confirmMessage),
+        });
+    }))
+        .addCommand(new Command("todo")
+        .description("Return a snoozed Thread to the queue when its blocker clears (staff only). Never reopens a Done Thread: Plain does that on real customer activity.")
+        .argument("<ticketId>", "Plain Thread ID (th_...).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (ticketId, options) => {
+        await handleSupportAdminUpdateRequest("todo", ticketId, options, {});
+    }))
+        .addCommand(new Command("assign")
+        .description("Hand a live Thread to a named human, for escalation past an agent's authority or judgment boundary (staff only).")
+        .argument("<ticketId>", "Plain Thread ID (th_...).")
+        .requiredOption("--user <email>", "The staff email to assign the Thread to.")
+        .option("--allow-takeover", "Required to move a Thread that already has an owner. Without it, an owned Thread is refused rather than silently reassigned.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (ticketId, options) => {
+        await handleSupportAdminUpdateRequest("assign", ticketId, options, {
+            assignee_email: readOption(options.user),
+            allow_takeover: options.allowTakeover === true,
+        });
+    }))
+        .addCommand(new Command("field-set")
+        .description("Record OXYGEN workflow state on a live Thread as structured, filterable Plain data — which version and commit carry a fix, and the PR that shipped it (staff only).")
+        .argument("<ticketId>", "Plain Thread ID (th_...).")
+        .requiredOption("--field <key>", "oxygen_fix_version | oxygen_fix_sha | oxygen_fix_pr. Customer-intake fields are read-only evidence and cannot be written here.")
+        .requiredOption("--value <value>", "The value to record.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (ticketId, options) => {
+        await handleSupportAdminUpdateRequest("field_set", ticketId, options, {
+            field_key: readOption(options.field),
+            field_value: readOption(options.value),
+        });
     }))
         .addCommand(new Command("label-add")
         .description("Add an active Plain label by external ID (staff only).")
@@ -3085,6 +3129,21 @@ The final readback must show ticket.status triaging, plain_status TODO, the In p
             },
         }));
     }), { hidden: true })
+        .addCommand(new Command("setup")
+        .description("Reconcile the shared Plain workspace against the taxonomy OXYGEN declares in code: request-type labels and intake fields, plus the workflow-state labels and release fields the support loop writes. Previews by default and never sends anything to a customer (staff only).")
+        .option("--apply", "Apply the previewed plan. Requires --confirm-plan with the exact plan_hash you just read.")
+        .option("--confirm-plan <hash>", "The plan_hash from the immediately preceding preview. A workspace that drifted in between fails closed.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        if (options.apply !== true) {
+            await handleAsyncAction("support admin setup", options, () => requestOxygen("/api/cli/admin/support/setup"));
+            return;
+        }
+        await handleAsyncAction("support admin setup", options, () => requestOxygen("/api/cli/admin/support/setup", {
+            method: "POST",
+            body: { confirm_plan_hash: readOption(options.confirmPlan) },
+        }));
+    }))
         .addCommand(new Command("events")
         .description("Read-only poll of legacy OXYGEN archive events for cutover compatibility; never use it as the live queue (staff only).")
         .option("--after <cursor>", "If has_more=true, pass next_cursor to continue that scan. If false, persist the non-null watermark_cursor for later polls. A watermark poll intentionally replays the settled 24h window, not only unseen events; dedupe every page by (ticket_ref, version).")
@@ -10493,7 +10552,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         }));
     }))
         .addCommand(new Command("set-photo")
-        .description("Set the sender's profile picture — the face that goes on every mailbox you order for this person. Pick exactly one source: --file (upload your own image; Oxygen hosts it permanently), --url (a public https image), --from-linkedin (re-mirror the photo from the attached LinkedIn account), or --clear. Hosting matters: an inbox vendor fetches the photo from its own servers HOURS after the order, so a LinkedIn CDN link (media.licdn.com, e=<epoch>) has already expired by then and the mailbox ships faceless. --file and --from-linkedin both end up Oxygen-hosted, which is why they are the safe choices. Free — no credits.")
+        .description("Set the reusable sender identity's profile picture for FUTURE managed-inbox orders made with --sender <id>. Pick exactly one source: --file (upload your own image; Oxygen hosts it permanently), --url (a public https image), --from-linkedin (re-mirror the photo from the attached LinkedIn account), or --clear. Hosting matters: an inbox vendor fetches the photo HOURS after an order, so an expiring LinkedIn CDN URL can ship the mailbox faceless. This updates Oxygen's sender profile only: it does not change already-provisioned mailbox photos or call the inbox provider. For a one-off typed-name order using profile_picture_url in --mailboxes JSON, use `oxygen managed-inboxes upload-avatar <path>` instead. Free — no credits.")
         .argument("<id>", "Sender profile id (from `oxygen senders profiles list`).")
         .option("--file <path>", "Upload a PNG, JPEG, or WebP from disk (max 8MB) and use it. Oxygen hosts the image permanently, so an inbox vendor can still fetch it at provisioning time.")
         .option("--url <url>", "Use an image already published at a public https URL. If the link expires (e.g. media.licdn.com with e=<epoch>) the photo is kept for Oxygen's own UI but marked non-durable and NEVER sent to an inbox vendor.")
@@ -13397,7 +13456,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("upload-avatar")
-        .description("Host a mailbox profile picture and print the URL to pass as profile_picture_url. The inbox vendor FETCHES that URL from its own servers when it provisions the mailbox — often long after the order — so it must be public and permanent. A LinkedIn photo URL is neither: media.licdn.com links carry an e=<epoch> expiry and the mailbox ends up faceless. Uploads a PNG, JPEG, or WebP (max 8MB); nothing is charged.")
+        .description("Host a one-off mailbox profile picture and print the URL to pass as profile_picture_url in --mailboxes JSON. For a reusable sender identity used by FUTURE --sender <id> orders, prefer `oxygen senders profiles set-photo <id> --file <path>` instead. The inbox vendor FETCHES the hosted URL when it provisions the mailbox, often long after the order, so it must be public and permanent. Uploads a PNG, JPEG, or WebP (max 8MB), then normalizes it to a metadata-free 400x400 PNG at a matching .png URL. This only hosts the image: it does not update a sender, place an order, call the inbox provider, or charge credits.")
         .argument("<path>", "Path to a PNG, JPEG, or WebP image.")
         .option("--json", "Print a JSON envelope.")
         .action(async (path, options) => {
@@ -21898,6 +21957,28 @@ async function handleSupportAdminUpdateRequest(action, ticketId, options, fields
         body: { action, ...fields },
     }));
 }
+/**
+ * Plain snoozes by duration, but humans and agents think in days and hours.
+ * Requiring at least one keeps `snooze` from silently meaning "five minutes".
+ */
+function readSupportSnoozeSeconds(options) {
+    const days = readSupportSnoozeUnit(options.days, "--days");
+    const hours = readSupportSnoozeUnit(options.hours, "--hours");
+    const seconds = days * 24 * 60 * 60 + hours * 60 * 60;
+    if (seconds <= 0) {
+        throw new OxygenError("invalid_request", "Pass --days and/or --hours to say how long the Thread should stay parked.", { exitCode: 1 });
+    }
+    return seconds;
+}
+function readSupportSnoozeUnit(raw, flag) {
+    if (raw === undefined)
+        return 0;
+    const value = Number(raw.trim());
+    if (!Number.isInteger(value) || value < 0) {
+        throw new OxygenError("invalid_request", `${flag} must be a whole, non-negative number.`, { exitCode: 1 });
+    }
+    return value;
+}
 async function handleSupportAdminWorkflowAction(ticketId, options) {
     try {
         const body = buildSupportAdminWorkflowBody(options);

package/node_modules/@oxygen/shared/dist/object-storage.d.ts

@@ -144,6 +144,22 @@ export declare function putInboxAvatarObject(input: {
     storageKey: string;
     contentLength: number;
 }>;
+/**
+ * Replace one staged avatar with provider-compatible bytes while preserving its
+ * public URL. The upload presign exposes that URL before confirmation, so moving
+ * the object to a new key during normalization would break an existing API
+ * promise. The org-bound key check is load-bearing: this is a bare S3 overwrite
+ * in a bucket shared by every tenant and several non-avatar namespaces.
+ */
+export declare function replaceInboxAvatarObject(input: {
+    organizationId: string;
+    storageKey: string;
+    body: Uint8Array;
+    contentType: string;
+}): Promise<{
+    storageKey: string;
+    contentLength: number;
+}>;
 /**
  * Read an avatar back, bounded. `maxBytes` is a hard stop rather than a hint:
  * this is called from an unauthenticated route, so an object that somehow grew

package/node_modules/@oxygen/shared/dist/object-storage.js

@@ -334,6 +334,27 @@ export async function putInboxAvatarObject(input) {
     }));
     return { storageKey, contentLength: input.body.byteLength };
 }
+/**
+ * Replace one staged avatar with provider-compatible bytes while preserving its
+ * public URL. The upload presign exposes that URL before confirmation, so moving
+ * the object to a new key during normalization would break an existing API
+ * promise. The org-bound key check is load-bearing: this is a bare S3 overwrite
+ * in a bucket shared by every tenant and several non-avatar namespaces.
+ */
+export async function replaceInboxAvatarObject(input) {
+    if (!isInboxAvatarObjectKeyForOrganization(input.storageKey, input.organizationId)) {
+        throw new OxygenError("invalid_object_key", "Refusing to replace an avatar that belongs to another organization.", { exitCode: 1 });
+    }
+    const { client, config } = resolveClient();
+    await client.send(new PutObjectCommand({
+        Bucket: config.bucket,
+        Key: input.storageKey,
+        Body: input.body,
+        ContentLength: input.body.byteLength,
+        ContentType: input.contentType,
+    }));
+    return { storageKey: input.storageKey, contentLength: input.body.byteLength };
+}
 /**
  * Read an avatar back, bounded. `maxBytes` is a hard stop rather than a hint:
  * this is called from an unauthenticated route, so an object that somehow grew

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

@@ -1,4 +1,4 @@
-export declare const OXYGEN_VERSION = "1.836.4";
+export declare const OXYGEN_VERSION = "1.837.9";
 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.836.4";
+export const OXYGEN_VERSION = "1.837.9";
 // 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.836.4",
+  "version": "1.837.9",
   "private": false,
   "license": "UNLICENSED",
   "type": "module",