@oxygen-agent/cli 1.1014.135 → 1.1014.618

package/dist/commands/managed-inboxes.d.ts

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

package/dist/commands/managed-inboxes.js

@@ -0,0 +1,361 @@
+import { readPositiveInt } from "../cli-values.js";
+import { putAvatarBytesToStorage, readJsonFileValue, splitCommaList } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { isRecord, readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { Command, Option } from "commander";
+import { resolve } from "node:path";
+// Builds the `prompts` command tree (list/get/upsert/archive). The
+// deprecated `templates` alias is the identical tree — same subcommands,
+// options, request bodies, and routes — differing only in the parent command
+// name, its description, and the `handleAsyncAction` operation labels, so both
+// surfaces are generated here to stop them drifting (the alias previously
+// duplicated every subcommand). All subcommands hit the shared
+// /api/cli/templates/* routes.
+/**
+ * Accept the domain as EITHER a positional argument or --domain.
+ *
+ * `subscribe` required --domain while get/cancel took a positional, so the same value had
+ * two spellings depending on the verb, and `get --domain acme.com` failed outright with "unknown
+ * option". Both spellings now work on every verb; nothing that used to work stops working.
+ */
+function requireDomainArg(positional, option) {
+    const domain = readOption(positional) ?? readOption(option);
+    if (!domain) {
+        throw new OxygenError("invalid_request", "A domain is required \u2014 pass it as an argument or with --domain. `oxygen managed-inboxes list` shows your managed domains.", { exitCode: 2, details: { next_step: "oxygen managed-inboxes list" } });
+    }
+    return domain;
+}
+/**
+ * Build the `mailboxes[]` an order route receives, from whichever input form the
+ * caller used, plus the optional `--sender` stamp.
+ *
+ * Shared by `managed-inboxes subscribe` and `add-inboxes` because the two used to
+ * drift: only one of them accepted the `--count/--prefix` shorthand, and each
+ * assembled its own body, so a fix to one silently missed the other. `forms`
+ * parameterises which spellings the calling command accepts instead.
+ *
+ * The `--sender` stamp is the reason this is one function. The inbox vendor has no
+ * post-provisioning update, so whatever first/last name reaches it is permanent —
+ * which is why a sender-backed item must not also carry a typed name. The server
+ * ignores those keys when `sender_profile_id` is present, but a request body that
+ * still lists `first_name: "Ada"` reads like Ada is what ships. Strip them here so
+ * the body says exactly what the vendor will stamp.
+ */
+function buildManagedInboxMailboxes(options, forms) {
+    const senderProfileId = readOption(options.sender);
+    const mailboxesJson = readOption(options.mailboxes);
+    const filePath = readOption(options.file);
+    const locals = splitCommaList(options.locals);
+    const prefix = readOption(options.prefix);
+    const count = readPositiveInt(options.count);
+    let mailboxes;
+    if (mailboxesJson) {
+        mailboxes = JSON.parse(mailboxesJson);
+    }
+    else if (filePath) {
+        const parsed = readJsonFileValue(resolve(filePath), "--file");
+        mailboxes = parsed.mailboxes ?? [];
+    }
+    else if (locals.length > 0) {
+        if (!senderProfileId) {
+            // Without a sender there is no identity to attach to a bare local part, and
+            // the vendor stamps a name on every mailbox permanently. Refusing is the
+            // only honest answer: inventing "Talia Rosen" from `talia.rosen` would bake
+            // a guess into a mailbox nobody can rename later.
+            throw new OxygenError("invalid_request", "--locals needs --sender <sender profile id>: the local parts carry no name, and the inbox vendor stamps a permanent one. Pass --mailboxes/--file with real first_name/last_name instead, or `oxygen senders profiles list` to pick a sender.", { exitCode: 2 });
+        }
+        mailboxes = locals.map((username) => ({ username }));
+    }
+    else if (forms.countPrefix && (count !== undefined || prefix)) {
+        if (count === undefined || !prefix) {
+            throw new Error("--count and --prefix must be passed together (e.g. --count 3 --prefix ada).");
+        }
+        const base = prefix.toLowerCase();
+        if (senderProfileId) {
+            // With a sender the shorthand finally has a real identity behind it, so it
+            // generates usernames only — the placeholder names below are exactly what
+            // this flag exists to stop shipping.
+            mailboxes = Array.from({ length: count }, (_entry, index) => ({ username: `${base}${index + 1}` }));
+        }
+        else {
+            // The vendor stamps a first/last name on every mailbox, so there is no
+            // name-less order shape to fall back on — the shorthand invents
+            // placeholders rather than pretending names are optional. Anyone who
+            // wants real human identities on the inboxes passes --sender (best),
+            // or --mailboxes/--file.
+            const label = `${base.charAt(0).toUpperCase()}${base.slice(1)}`;
+            mailboxes = Array.from({ length: count }, (_entry, index) => ({
+                username: `${base}${index + 1}`,
+                first_name: label,
+                last_name: String(index + 1),
+            }));
+        }
+    }
+    else {
+        const spellings = ["--mailboxes <json>", "--file <path>", "--locals <list> --sender <id>"];
+        if (forms.countPrefix)
+            spellings.push("--count <n> --prefix <base>");
+        throw new Error(`Provide ${spellings.join(", ")}.`);
+    }
+    if (!senderProfileId || !Array.isArray(mailboxes))
+        return mailboxes;
+    return mailboxes.map((entry) => {
+        if (!isRecord(entry))
+            return entry;
+        const { first_name: _firstName, last_name: _lastName, profile_picture_url: _profilePictureUrl, ...rest } = entry;
+        return { ...rest, sender_profile_id: senderProfileId };
+    });
+}
+export function registerManagedInboxesFamily(program, handleAsyncAction) {
+    program.addCommand(new Command("managed-inboxes")
+        .addCommand(new Command("recover")
+        .description("Restore a cancelled managed subscription using its original addresses and domain. Find candidates with managed-inboxes list --status cancelled --json. Without --approved, performs a read-only preview at 0 credits: eligibility, upfront credits, recurring charges and a quote_id. Review the preview, then use --approved --quote <id> --max-credits <n>. Interrupted provider attempts are inspected before any repeat. After provider recovery, verify sending authorization and warmup for the exact recovered mailboxes. If warmup is disabled, preview enrollment and review its scope and costs before approving it.")
+        .argument("<domain>", "The cancelled managed sending domain")
+        .option("--approved", "Execute the reviewed recovery quote", false)
+        .option("--quote <id>", "quote_id from the recovery preview")
+        .option("--rebuy", "Include replacement licenses in the recovery preview and approval", false)
+        .option("--max-credits <n>", "Upfront recovery credit ceiling; does not cap recurring charges", Number)
+        .option("--json", "Print a JSON envelope")
+        .action(async (domain, options) => {
+        await handleAsyncAction("managed-inboxes recover", options, () => requestOxygen("/api/cli/managed-inboxes/recover", {
+            method: "POST", body: { domain, approved: options.approved === true, rebuy: options.rebuy === true,
+                ...(options.quote ? { quote_id: options.quote } : {}),
+                ...(options.maxCredits !== undefined ? { max_credits: options.maxCredits } : {}) },
+        }));
+    }))
+        .description("Managed sending inboxes bought through OXYGEN: subscribe a domain + N InboxKit mailboxes (google/microsoft/azure) as a recurring monthly Oxygen-credit purchase, add inboxes to a domain you already own, inspect/verify, cancel, and recover cancelled original addresses. OXYGEN Warm-up defaults on when available: its quoted recurring credits and exact future addresses are part of the order approval, and the worker activates it after provisioning without a second warmup approval. Warm-up does not prove native-send authorization: verify each exact address with `mailboxes oauth-health --json`. Subscribe/add-inboxes preview first (re-run with --approved --quote); cancel previews first (re-run with --approved --confirm <domain>). To remove several domains with their inboxes, use `domains delete`. The inbox vendor is chosen for you; --vendor pins one.")
+        .addCommand(new Command("verify")
+        .description("Compare purchased inbox inventory with the vendor and legacy Stripe mailbox seats. Credit-billed orders do not require Stripe seats; their credit captures and renewal amounts are explicitly unverified by this check. Unavailable reads are reported as verification gaps, never agreement or underbilling. Reports mismatches with who loses money (customer_overbilled first, then oxygen_pays). Read-only, no writes, 0 Oxygen credits.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("managed-inboxes verify", options, () => requestOxygen("/api/cli/managed-inboxes/verify"));
+    }))
+        .addCommand(new Command("registrant")
+        .description("Show the registrant (WHOIS) contact this workspace files domain registrations under, or null if it has never bought one. Your FIRST managed-inboxes subscribe supplies it via --billing; every order after that reuses it automatically, so this is how you check what is on file. Read-only, 0 Oxygen credits.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("managed-inboxes registrant", options, () => requestOxygen("/api/cli/managed-inboxes/registrant"));
+    }))
+        .addCommand(new Command("subscribe")
+        .description("Buy managed monthly inboxes on a new domain or your existing Cloudflare domain. Use --existing-domain for Cloudflare: the read-only preview shows ownership, occupancy, DNS scope and blockers, with zero registration charge. --max-per-domain saves a stricter limit with the approved order, including existing addresses; later additions honor it. Preview does not save the limit or change workspace data. WITHOUT --approved this prints a priced PREVIEW with a quote_id (nothing ordered, nothing charged); re-run with --approved --quote <id> to place the order. OXYGEN Warm-up defaults on for Google, Microsoft, and Azure when available: preview and approved responses carry `warmup_activation` with the exact `mailboxes` and `scope=warmup_only`; it is null when warmup is disabled or unavailable. For InboxKit, Google carries `transport=inboxkit_managed_google_handoff`; Microsoft/Azure carries `transport=inboxkit_sequencer_export`. Both carry `mailbox_credentials_required=false` and `native_send_oauth_separate=true`, so managed warm-up needs no customer-supplied OAuth or mailbox password. Google retrieves the existing managed credential only during activation and never persists or returns it; Microsoft/Azure uses native export. Native sending authorization is separate and may still be required before OXYGEN can send. Verify each exact address with `mailboxes oauth-health --json`; InboxKit's unattended Google domain approval usually lands within minutes and the worker keeps retrying, so a waiting row is not a reason to ask the customer to sign in. This order authorizes automatic OXYGEN Warm-up activation after provisioning, so no second `mailboxes warmup enable` approval is needed. The preview shows the price in force: from the 2026-09 repricing date a Google Workspace or Microsoft 365 inbox is one flat mailbox line plus the 100-credit mailbox connection, warm-up included, which `connection_monthly_credits` shows and your balance reserves once the inbox connects (400 credits a month all-in at the committed price), and an Azure tenant is one flat charge for its domain (4,000 a month) plus each inbox's connection; `managed-inboxes list --json` reports the prices in force under `prices`. Domains are priced from the vendor's LIVE domain price, and any price below vendor cost is refused. A domain you bought on its own through Oxygen (`domains buy`) takes its first inboxes here too: the preview says `domain_source: owned`, nothing is registered again and `one_off_credits` is 0 (Google or Microsoft; omit --years). To add mailboxes to a domain that already has inboxes use `managed-inboxes add-inboxes`.")
+        .argument("[domain]", "Sending domain to register + host the mailboxes (e.g. send.acme.com), or one you already bought through Oxygen. May also be passed as --domain.")
+        .option("--domain <domain>", "Sending domain (alternative to the positional argument).")
+        .requiredOption("--provider <provider>", "Mailbox PLATFORM: google, microsoft, or azure. (google/microsoft cap at 5 mailboxes per domain; azure allows 100.)")
+        .option("--vendor <vendor>", "Pin the vendor: inboxkit. Omit to let OXYGEN choose. A named vendor with no credential FAILS rather than falling back to another.")
+        .option("--sender <id>", "Sender profile id (from `oxygen senders profiles list`) that OWNS every mailbox in this order: its first name, last name, and profile picture are stamped on each one, so you never retype them. A sender profile is one person's sending identity — their LinkedIn/WhatsApp accounts and email inboxes under one name and photo. One sender can own several addresses on the same domain (see --locals). Any first_name/last_name/profile_picture_url in --mailboxes/--file is dropped for the sender's own values.")
+        .option("--locals <list>", "Comma-separated local parts to create for --sender, e.g. `--locals talia,talia.rosen,t.rosen` on send.acme.com orders talia@, talia.rosen@, and t.rosen@ — all owned by that one person. Requires --sender, because a bare local part carries no name and the vendor's stamp is permanent.")
+        .option("--mailboxes <json>", "JSON array of mailboxes: [{\"username\",\"first_name\",\"last_name\",\"profile_picture_url\"}], or [{\"username\",\"sender_profile_id\"}] to take the identity from a sender profile per item (mix freely). profile_picture_url is optional and must be a PUBLIC, PERMANENT https URL — the vendor fetches it server-side at provisioning, so an expiring CDN link (e.g. a media.licdn.com URL with e=<epoch>) ships the mailbox faceless. Use `oxygen managed-inboxes upload-avatar <path>` to host one, or --sender / sender_profile_id, whose photo Oxygen already mirrors.")
+        .option("--file <path>", "Path to a JSON file { \"mailboxes\": [...] } (alternative to --mailboxes).")
+        .addOption(new Option("--preview", "Explicit read-only quote: connects nothing, buys nothing and charges nothing. Cannot be combined with purchase or DNS cleanup approval.").conflicts(["approved", "dnsCleanupApproved"]))
+        .option("--existing-domain", "Use an existing Cloudflare domain from oxygen domains list; never register or transfer it.")
+        .option("--max-per-domain <n>", "Save a stricter mailbox limit with the approved order, including existing addresses (e.g. 2). Preview does not save it.")
+        .option("--dns-cleanup-records <ids>", "Preview deletion of these comma-separated exact email DNS record IDs on an existing domain; connects and buys nothing.")
+        .addOption(new Option("--dns-cleanup-approved", "Delete only the reviewed email records; requires --dns-cleanup-records and --dns-cleanup-hash. Request a fresh purchase quote afterward.").conflicts("approved"))
+        .option("--dns-cleanup-hash <hash>", "The plan_hash from the exact DNS cleanup preview, required to delete records.")
+        .option("--years <n>", "Years to register a new domain for (1-10). Omit for existing domains.")
+        .option("--redirect-url <url>", "Where the domain's web root redirects. Defaults to your workspace's company website; editable later with `oxygen domains forwarding set`.")
+        .option("--billing <path>", "Path to a JSON file with the registrant/WHOIS contact (first_name, last_name, phone, country, city, state, address_line_one, postal_code). Required on your FIRST order; later orders reuse the registrant already on file.")
+        .option("--no-warmup", "Order WITHOUT automatic OXYGEN Warm-up. Warm-up is included by default and starts after provisioning under this order approval for the exact quoted Google/Microsoft/Azure addresses; opting out means using BYO warm-up or a later standalone warmup approval.")
+        .option("--placement", "Add inbox placement to every inbox (optional, billed monthly per inbox from provisioning): inbox-placement (spam) testing, blacklist/reputation monitoring, and authentication checks. Off unless you pass this flag.")
+        .option("--approved", "Place the order (requires --quote). Without it, a priced preview is returned.")
+        .option("--quote <id>", "The quote_id from a fresh preview. Required with --approved.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domainArg, options) => {
+        await handleAsyncAction("managed-inboxes subscribe", options, () => {
+            // The domain may arrive either way. `subscribe` took --domain while get and
+            // cancel took a positional, so the same value had two spellings depending on the
+            // verb — `get --domain x` simply failed. Both work everywhere now.
+            const domain = readOption(domainArg) ?? readOption(options.domain);
+            const provider = readOption(options.provider);
+            if (!domain)
+                throw new Error("--domain is required.");
+            if (!provider)
+                throw new Error("--provider is required (google, microsoft, or azure).");
+            // No --count/--prefix here, deliberately: that shorthand can only
+            // reach the vendor by inventing names, and a new domain's first
+            // order is exactly where a placeholder becomes permanent.
+            const mailboxes = buildManagedInboxMailboxes(options, { countPrefix: false });
+            const years = readOption(options.years);
+            const vendor = readOption(options.vendor);
+            const redirectUrl = readOption(options.redirectUrl);
+            const billingPath = readOption(options.billing);
+            const billing = billingPath ? readJsonFileValue(resolve(billingPath), "--billing") : undefined;
+            const quote = readOption(options.quote);
+            const cleanupRecords = readOption(options.dnsCleanupRecords);
+            const cleanupHash = readOption(options.dnsCleanupHash);
+            if ((cleanupRecords && !options.existingDomain)
+                || ((options.dnsCleanupApproved || cleanupHash) && !cleanupRecords)
+                || (options.dnsCleanupApproved && !cleanupHash)) {
+                throw new OxygenError("invalid_request", "DNS cleanup requires --existing-domain and --dns-cleanup-records; deletion also requires its fresh --dns-cleanup-hash.", { exitCode: 2 });
+            }
+            return requestOxygen("/api/cli/managed-inboxes/subscribe", {
+                method: "POST",
+                body: {
+                    domain,
+                    provider,
+                    mailboxes,
+                    ...(vendor ? { vendor } : {}),
+                    ...(years ? { years: Number(years) } : {}),
+                    ...(options.existingDomain ? { existing_domain: true } : {}),
+                    ...(options.maxPerDomain !== undefined ? { max_mailboxes_per_domain: Number(options.maxPerDomain) } : {}),
+                    ...(cleanupRecords ? { dns_cleanup: {
+                            record_ids: cleanupRecords.split(",").map((id) => id.trim()),
+                            approved: options.dnsCleanupApproved === true,
+                            ...(cleanupHash ? { plan_hash: cleanupHash } : {}),
+                        } } : {}),
+                    ...(redirectUrl ? { redirect_url: redirectUrl } : {}),
+                    ...(billing ? { billing } : {}),
+                    // Warm-up is on unless --no-warmup. Placement is opt-in: it is sent only
+                    // when --placement was passed, so an untouched flag leaves the server's
+                    // default (off) in force. Older CLIs sent `placement: true` on every
+                    // order. The selection is hashed into quote_id, so --approved must
+                    // repeat whatever the preview was run with.
+                    addons: {
+                        warmup: options.warmup !== false,
+                        ...(options.placement === true ? { placement: true } : {}),
+                    },
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(quote ? { quote_id: quote } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("add-inboxes")
+        .description("Add mailboxes to a managed domain you ALREADY own — no new domain is registered and there is NO domain registration charge, only the extra inboxes' monthly rate (plus their add-ons). WITHOUT --approved this prints a priced PREVIEW with a quote_id and orders nothing; re-run with --approved --quote <id> to place the order. When the standing OXYGEN Warm-up add-on is enabled and available, preview and approved responses carry `warmup_activation` for only the exact newly added `mailboxes`, with `scope=warmup_only`; it is null when warmup is disabled or unavailable. For InboxKit, Google carries `transport=inboxkit_managed_google_handoff`; Microsoft/Azure carries `transport=inboxkit_sequencer_export`. Both carry `mailbox_credentials_required=false` and `native_send_oauth_separate=true`, so managed warm-up needs no customer-supplied OAuth or mailbox password. Google retrieves the existing managed credential only during activation and never persists or returns it; Microsoft/Azure uses native export. Native sending authorization is separate and may still be required before OXYGEN can send. Verify each exact address with `mailboxes oauth-health --json`; InboxKit's unattended Google domain approval usually lands within minutes and the worker keeps retrying, so a waiting row is not a reason to ask the customer to sign in. The quote authorizes automatic OXYGEN Warm-up activation after provisioning, so do not run a second warmup approval. Capped per domain by the platform the domain was bought on (5 google/microsoft, 100 azure) COUNTING the inboxes already on it. To register a NEW domain use `managed-inboxes subscribe` instead.")
+        .argument("[domain]", "A managed domain this workspace already owns (e.g. send.acme.com). May also be passed as --domain.")
+        .option("--domain <domain>", "The managed inbox domain (alternative to the positional argument).")
+        .option("--sender <id>", "Sender profile id (from `oxygen senders profiles list`) that OWNS every mailbox in this order: its first name, last name, and profile picture are stamped on each one, so you never retype them. A sender profile is one person's sending identity — their LinkedIn/WhatsApp accounts and email inboxes under one name and photo. One sender can own several addresses on the same domain (see --locals). Any first_name/last_name/profile_picture_url in --mailboxes/--file is dropped for the sender's own values.")
+        .option("--locals <list>", "Comma-separated local parts to add for --sender, e.g. `--locals talia,talia.rosen,t.rosen` adds talia@, talia.rosen@, and t.rosen@ on this domain — all owned by that one person. Requires --sender, because a bare local part carries no name and the vendor's stamp is permanent.")
+        .option("--mailboxes <json>", "JSON array of mailboxes: [{\"username\",\"first_name\",\"last_name\",\"profile_picture_url\"}], or [{\"username\",\"sender_profile_id\"}] to take the identity from a sender profile per item (mix freely). The vendor stamps the names on each mailbox permanently, so real names belong here. profile_picture_url is optional and must be a PUBLIC, PERMANENT https URL the vendor can fetch at provisioning; `oxygen managed-inboxes upload-avatar <path>` returns one, and a sender profile's mirrored photo already is one.")
+        .option("--file <path>", "Path to a JSON file { \"mailboxes\": [...] } (alternative to --mailboxes).")
+        .option("--count <n>", "Shorthand for --mailboxes: how many inboxes to add. Requires --prefix.")
+        .option("--prefix <base>", "Shorthand username base for --count: `--count 3 --prefix ada` adds ada1, ada2, ada3. WITH --sender all three belong to that person, named and pictured as them; WITHOUT --sender they get placeholder names (Ada 1, Ada 2, Ada 3) the vendor can never change. Pass --sender, or --mailboxes/--file with real names.")
+        .option("--approved", "Place the order (requires --quote). Without it, a priced preview is returned.")
+        .option("--quote <id>", "The quote_id from a fresh preview. Required with --approved.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domainArg, options) => {
+        await handleAsyncAction("managed-inboxes add-inboxes", options, () => {
+            const domain = requireDomainArg(domainArg, options.domain);
+            const mailboxes = buildManagedInboxMailboxes(options, { countPrefix: true });
+            const quote = readOption(options.quote);
+            // Refuse locally rather than spending a round trip on a PAID path: the
+            // route requires the quote that priced this exact expansion, so
+            // `--approved` alone can only ever come back as a 400.
+            if (options.approved && !quote) {
+                // Typed, not a bare Error: a bare throw surfaces as
+                // `unexpected_error`, which an agent cannot tell apart from a
+                // real failure on a PAID command. Refusing to order is an
+                // ordinary, expected outcome and must say so in its code.
+                throw new OxygenError("invalid_request", "--approved requires --quote <id> from a fresh preview. Re-run without --approved to get one.", { exitCode: 2 });
+            }
+            return requestOxygen(`/api/cli/managed-inboxes/${encodeURIComponent(domain)}/mailboxes`, {
+                method: "POST",
+                body: {
+                    // Always an explicit mailboxes[]: --count/--prefix is client-side
+                    // sugar, so the server sees exactly one shape and the preview it
+                    // prices is the list that gets ordered.
+                    mailboxes,
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(quote ? { quote_id: quote } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("list")
+        .description("List the org's managed inbox orders: vendor, platform, live inbox count, lifecycle status, internal billing posture, and each order's FULL monthly cost — the inbox line, each inbox's mailbox connection once inboxes are sold all-in (`orders[].connection`), and the warm-up and inbox-placement add-ons billing per inbox on top of it (`orders[].total_monthly_credits`, `total_monthly_credits` across the workspace). Read-only, 0 Oxygen credits.")
+        .option("--status <status>", "Filter by status: pending, active, renewing, past_due, expired, cancelled, or failed.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("managed-inboxes list", options, () => {
+            const params = new URLSearchParams();
+            const status = readOption(options.status);
+            if (status)
+                params.set("status", status);
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/managed-inboxes${suffix ? `?${suffix}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("get")
+        .description("Get one managed inbox subscription by domain (vendor, platform, mailbox count, monthly USD price, vendor order id, lifecycle status, auto-renew, period end, internal billing status). Read-only, 0 Oxygen credits.")
+        .argument("[domain]", "The managed inbox domain (e.g. send.acme.com). May also be passed as --domain.")
+        .option("--domain <domain>", "The managed inbox domain (alternative to the positional argument).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domainArg, options) => {
+        await handleAsyncAction("managed-inboxes get", options, () => {
+            const domain = requireDomainArg(domainArg, options.domain);
+            return requestOxygen(`/api/cli/managed-inboxes/${encodeURIComponent(domain)}`);
+        });
+    }))
+        .addCommand(new Command("cancel")
+        .description("Cancel a managed inbox order by domain: the inboxes AND every recurring add-on on them (warm-up, inbox placement). WITHOUT --approved prints the itemized teardown — every line that stops billing, when the inboxes go dark, and which live sequences send from them. To cancel, re-run with --approved AND --confirm <domain> echoing the domain exactly. Once cancelled, original-address recovery depends on provider eligibility; preview with managed-inboxes recover. The domain stays registered until its term ends. Cancelling is free.")
+        .argument("[domain]", "The managed inbox domain to cancel. May also be passed as --domain.")
+        .option("--domain <domain>", "The managed inbox domain (alternative to the positional argument).")
+        .option("--approved", "Actually cancel (otherwise the teardown preview is returned).")
+        .option("--confirm <domain>", "Type the domain again to confirm. Required with --approved.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domainArg, options) => {
+        await handleAsyncAction("managed-inboxes cancel", options, () => {
+            const domain = requireDomainArg(domainArg, options.domain);
+            const confirm = readOption(options.confirm);
+            return requestOxygen("/api/cli/managed-inboxes/cancel", {
+                method: "POST",
+                body: {
+                    domain,
+                    ...(options.approved ? { approved: true } : {}),
+                    // Sent verbatim, never defaulted to `domain`: the whole point of the
+                    // echo is that a human (or an agent) typed the name a second time, and
+                    // filling it in here would delete the only friction on the path.
+                    ...(confirm ? { confirm_domain: confirm } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("exit")
+        .description("Transfer ONE managed domain out of OXYGEN: stop every OXYGEN renewal for this domain after the paid period; keep the domain, mailboxes, DNS, warm-up state and data exactly as they are. Nothing is cancelled, disconnected, or released; the handoff is coordinated by a human with the vendor. OXYGEN continues paying the inbox vendor until that handoff or `managed-inboxes cancel`; the customer does not pay that vendor-carry cost. For all external resources in a workspace, preview `workspace infrastructure-exit` instead. WITHOUT --approved prints the domain plan; to record the transfer, re-run with --approved AND --confirm <domain>. --revoke resumes OXYGEN renewals. Free, 0 credits.")
+        .argument("[domain]", "The managed domain to stop renewing. May also be passed as --domain.")
+        .option("--domain <domain>", "The managed inbox domain (alternative to the positional argument).")
+        .option("--contact <email>", "Who the human handoff should be coordinated with (recorded on the request).")
+        .option("--note <text>", "Free-text context for the handoff, e.g. where the mailboxes are moving.")
+        .option("--revoke", "Undo a recorded exit: renewals resume on the next cycle. Still needs --approved --confirm.")
+        .option("--approved", "Actually record the exit (or the revoke); otherwise the plan is printed.")
+        .option("--confirm <domain>", "Type the domain again to confirm. Required with --approved.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domainArg, options) => {
+        await handleAsyncAction("managed-inboxes exit", options, () => {
+            const domain = requireDomainArg(domainArg, options.domain);
+            const confirm = readOption(options.confirm);
+            const contact = readOption(options.contact);
+            const note = readOption(options.note);
+            return requestOxygen("/api/cli/managed-inboxes/exit", {
+                method: "POST",
+                body: {
+                    domain,
+                    ...(contact ? { contact } : {}),
+                    ...(note ? { note } : {}),
+                    ...(options.revoke ? { revoke: true } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                    // Sent verbatim, never defaulted to `domain` — same rule as cancel: the
+                    // echo only means something if a human (or an agent) typed it a second time.
+                    ...(confirm ? { confirm_domain: confirm } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("upload-avatar")
+        .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) => {
+        await handleAsyncAction("managed-inboxes upload-avatar", options, async () => {
+            const storageKey = await putAvatarBytesToStorage(path);
+            // Confirming against the avatars route is what turns the staged
+            // bytes into a public URL — the server sniffs the real bytes here,
+            // so a .png that is actually a PDF is caught before an order.
+            return await requestOxygen("/api/cli/managed-inboxes/avatars", {
+                method: "PATCH",
+                body: { storage_key: storageKey },
+            });
+        });
+    })));
+}

package/dist/commands/messages.d.ts

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

package/dist/commands/messages.js

@@ -0,0 +1,78 @@
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { Command } from "commander";
+export function registerMessagesFamily(program, handleAsyncAction) {
+    program.addCommand(new Command("messages")
+        .description("Cross-channel message corpus: every individual email + LinkedIn + WhatsApp message as one searchable stream (Postgres full-text search over bodies, keyset paginated by recency), plus INBOX-WIDE conversation analytics. NOT campaign performance: for per-channel campaign reply rates use `oxygen sequences analytics`. Message-level, unlike inbox (conversation-level triage).")
+        .addCommand(new Command("query")
+        .description("Query messages across channels newest first, or relevance-ranked when -q is set. --channel all merges email + LinkedIn + WhatsApp (narrow with --channels); a campaign filter (--sequence-id) restricts to email. Filter by direction, account, contact, status, and date range. Scope: the Messages store (Unibox conversations, every native email since v1.927.0 linked to its campaign; earlier sends without a provider thread id are not). The complete send ledger of a sequence is `sequences events --kind sent`; its counts are `sequences stats`.")
+        .option("-q, --query <text>", "Full-text search over message bodies (relevance-ranked).")
+        .option("--channel <channel>", "Channel: all (merged, default), email, linkedin, or whatsapp.")
+        .option("--channels <list>", "channel=all only: comma-separated channels to include (email,linkedin,whatsapp). Empty = all three.")
+        .option("--direction <direction>", "Filter by direction: inbound or outbound.")
+        .option("--account <id>", "Mailbox id (email) or sender account id (DM) to filter to.")
+        .option("--contact <text>", "Filter by counterpart name or handle (address / provider id).")
+        .option("--sequence-id <id>", "Email only: campaign (sequence) id (restricts the result to email).")
+        .option("--status <keys>", "Comma-separated conversation status keys (e.g. interested,meeting_booked).")
+        .option("--tag <tag>", "Only messages whose conversation carries this workspace tag (see `oxygen tags list`).")
+        .option("--since <iso>", "Only messages sent at or after this ISO timestamp.")
+        .option("--until <iso>", "Only messages sent before this ISO timestamp.")
+        .option("--limit <n>", "Maximum messages to return (1-200). Defaults to 50.")
+        .option("--cursor <c>", "Pagination cursor from a previous page's next_cursor (recency path only).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("messages query", options, () => {
+            const params = new URLSearchParams();
+            const query = readOption(options.query);
+            if (query)
+                params.set("q", query);
+            for (const [flag, key] of [
+                ["channel", "channel"],
+                ["channels", "channels"],
+                ["direction", "direction"],
+                ["account", "account"],
+                ["contact", "contact"],
+                ["sequenceId", "sequence_id"],
+                ["status", "status"],
+                ["tag", "tag"],
+                ["since", "since"],
+                ["until", "until"],
+                ["limit", "limit"],
+                ["cursor", "cursor"],
+            ]) {
+                const value = readOption(options[flag]);
+                if (value)
+                    params.set(key, value);
+            }
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/messages${suffix ? `?${suffix}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("stats")
+        .description("INBOX-WIDE message-ledger analytics over the WHOLE corpus, not your campaigns: outbound/inbound totals, a conversation-level reply rate (has-inbound over has-outbound) by channel, status breakdowns, response-time percentiles, top counterpart domains, and winning openers. It counts every conversation in the workspace, including mail no campaign sent, so its reply rate is NOT your campaign reply rate — for that, and for per-channel campaign performance, use `oxygen sequences analytics`. byCampaign is email-only because direct-message conversations carry no campaign link; an empty list there is inaccessible, not absence. Scope with --sequence-id, --channel, and a date range. Defaults to the last 30 days; pass --all-time for full history.")
+        .option("--sequence-id <ids>", "Comma-separated campaign (sequence) ids to scope to.")
+        .option("--channel <channel>", "Channel: all (default), email, linkedin, or whatsapp.")
+        .option("--since <iso>", "Only messages sent at or after this ISO timestamp. Defaults to 30 days ago.")
+        .option("--until <iso>", "Only messages sent before this ISO timestamp.")
+        .option("--all-time", "Scan full message history instead of the default trailing 30 days. Ignored if --since or --until is also set.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("messages stats", options, () => {
+            const params = new URLSearchParams();
+            for (const [flag, key] of [
+                ["sequenceId", "sequence_id"],
+                ["channel", "channel"],
+                ["since", "since"],
+                ["until", "until"],
+            ]) {
+                const value = readOption(options[flag]);
+                if (value)
+                    params.set(key, value);
+            }
+            if (options.allTime)
+                params.set("all_time", "true");
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/messages/stats${suffix ? `?${suffix}` : ""}`);
+        });
+    })));
+}

package/dist/commands/notetaker.d.ts

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

package/dist/commands/notetaker.js

@@ -0,0 +1,79 @@
+import { readPositiveInt, resolveLiveDryRunMode } from "../cli-values.js";
+import { parseJsonArray, readPositiveNumber } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { Command } from "commander";
+function buildNotetakerSetupBody(options) {
+    return {
+        mode: resolveLiveDryRunMode(options),
+        enabled: options.disabled === true ? false : true,
+        capture_mode: "invited_bot",
+        auto_record_scope: "manual",
+        ...(readOption(options.botName) ? { bot_name: readOption(options.botName) } : {}),
+        ...(options.botAvatarUrl !== undefined ? { bot_avatar_url: readOption(options.botAvatarUrl) ?? null } : {}),
+        ...(options.consentDisclosure !== undefined ? { consent_disclosure: readOption(options.consentDisclosure) ?? null } : {}),
+        ...(readPositiveInt(options.defaultMaxMinutes) ? { default_max_minutes: readPositiveInt(options.defaultMaxMinutes) } : {}),
+        ...(readPositiveNumber(options.defaultMaxCredits) ? { default_max_credits: readPositiveNumber(options.defaultMaxCredits) } : {}),
+        ...(readPositiveInt(options.retentionDays) ? { retention_days: readPositiveInt(options.retentionDays) } : {}),
+    };
+}
+function buildNotetakerScheduleBody(meetingUrl, options) {
+    return {
+        mode: resolveLiveDryRunMode(options),
+        meeting_url: meetingUrl,
+        approved: options.approved === true,
+        ...(readOption(options.title) ? { title: readOption(options.title) } : {}),
+        ...(readOption(options.joinAt) ? { join_at: readOption(options.joinAt) } : {}),
+        ...(readPositiveInt(options.maxMinutes) ? { max_minutes: readPositiveInt(options.maxMinutes) } : {}),
+        ...(readPositiveNumber(options.maxCredits) ? { max_credits: readPositiveNumber(options.maxCredits) } : {}),
+        ...(readOption(options.crmLinksJson) ? { crm_links: parseJsonArray(readOption(options.crmLinksJson) ?? "") } : {}),
+    };
+}
+export function registerNotetakerFamily(program, handleAsyncAction) {
+    program
+        .command("notetaker")
+        .description("AI meeting notetaker setup, scheduling, and session inspection.")
+        .addCommand(new Command("setup")
+        .description("Configure the Recall-backed Oxygen Notetaker. Defaults to dry-run.")
+        .option("--bot-name <name>", "Meeting bot display name. Defaults to Oxygen Notetaker.")
+        .option("--bot-avatar-url <url>", "Meeting bot avatar URL; pass an empty string to clear it.")
+        .option("--consent-disclosure <text>", "Recording disclosure; pass an empty string to restore the default disclosure.")
+        .option("--disabled", "Save the notetaker as disabled when used with --live.")
+        .option("--default-max-minutes <n>", "Default maximum meeting minutes to reserve. Defaults to 60.")
+        .option("--default-max-credits <n>", "Default spend cap for live schedules.")
+        .option("--retention-days <n>", "Transcript/artifact retention window. Defaults to 30.")
+        .option("--dry-run", "Preview setup without writing settings.")
+        .option("--live", "Apply notetaker settings.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("notetaker setup", options, () => requestOxygen("/api/cli/notetaker/setup", {
+            method: "POST",
+            body: buildNotetakerSetupBody(options),
+        }));
+    }))
+        .addCommand(new Command("schedule")
+        .description("Schedule an invited meeting bot. Defaults to dry-run.")
+        .argument("<meeting_url>", "Zoom, Google Meet, or Teams meeting URL.")
+        .option("--title <title>", "Meeting title for the CRM timeline.")
+        .option("--join-at <iso>", "ISO date-time for scheduled bot join.")
+        .option("--max-minutes <n>", "Maximum meeting minutes to reserve.")
+        .option("--max-credits <n>", "Required spend cap for live schedules.")
+        .option("--crm-links-json <json>", "JSON array of CRM links: [{\"object\":\"companies\",\"row_id\":\"...\",\"role\":\"account\"}].")
+        .option("--approved", "Approve the live paid Recall bot schedule.")
+        .option("--dry-run", "Preview schedule and credit estimate without creating a bot.")
+        .option("--live", "Create the Recall bot after approval and credit reservation.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (meetingUrl, options) => {
+        await handleAsyncAction("notetaker schedule", options, () => requestOxygen("/api/cli/notetaker/schedule", {
+            method: "POST",
+            body: buildNotetakerScheduleBody(meetingUrl, options),
+        }));
+    }))
+        .addCommand(new Command("status")
+        .description("Get one notetaker session with artifacts and credit state.")
+        .argument("<session_id>", "Notetaker session id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sessionId, options) => {
+        await handleAsyncAction("notetaker status", options, () => requestOxygen(`/api/cli/notetaker/sessions/${encodeURIComponent(sessionId)}`));
+    }));
+}

package/dist/commands/observability.d.ts

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