@oxygen-agent/cli 1.1014.136 → 1.1014.619

package/dist/commands/support.js

@@ -0,0 +1,651 @@
+import { emitCliFailure, handleAsyncAction, writeJson } from "../cli-output.js";
+import { ansi, readCsvOption, readSelectedTranscriptExcerpt } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { captureCurrentTranscript, TranscriptCaptureError } from "../transcript.js";
+import { isRecord, readOption } from "../util.js";
+import { OxygenError, success } from "@oxygen/shared/cli-result";
+import { Command } from "commander";
+import { stdout as output } from "node:process";
+function buildSupportTicketBody(options) {
+    const message = readOption(options.body);
+    if (!message) {
+        throw new OxygenError("invalid_input", 'Provide a support message with --body "...".', { exitCode: 1 });
+    }
+    const body = { subject: readOption(options.subject), body: message };
+    const sessionId = readOption(options.sessionId);
+    const file = readOption(options.transcriptFile);
+    if (options.transcript !== false && options.transcriptText !== undefined) {
+        if (options.includeTranscript || sessionId || file) {
+            throw new OxygenError("invalid_input", "Choose --transcript-text or one local transcript option.", { exitCode: 1 });
+        }
+        body.transcript_text = readSelectedTranscriptExcerpt(options.transcriptText);
+    }
+    if (options.transcript !== false && (options.includeTranscript || sessionId || file)) {
+        try {
+            const captured = captureCurrentTranscript({ sessionId, file });
+            if (!captured) {
+                throw new OxygenError("transcript_not_found", "No local agent transcript was found. Choose --session-id or --transcript-file.", { exitCode: 1 });
+            }
+            const { path: _path, ...payload } = captured;
+            body.transcript = payload;
+        }
+        catch (error) {
+            if (error instanceof TranscriptCaptureError) {
+                throw new OxygenError("transcript_not_found", error.message, { exitCode: 1 });
+            }
+            throw error;
+        }
+    }
+    if (readOption(options.severity))
+        body.severity = readOption(options.severity);
+    if (readOption(options.category))
+        body.category = readOption(options.category);
+    if (readOption(options.source))
+        body.source = readOption(options.source);
+    const context = {};
+    if (readOption(options.cliVersion))
+        context.cli_version = readOption(options.cliVersion);
+    if (readOption(options.operation))
+        context.operation = readOption(options.operation);
+    if (readOption(options.errorCode))
+        context.error_code = readOption(options.errorCode);
+    if (readOption(options.slackPermalink))
+        context.slack_permalink = readOption(options.slackPermalink);
+    if (readOption(options.slackChannelId))
+        context.slack_channel_id = readOption(options.slackChannelId);
+    if (readOption(options.customerWorkspace))
+        context.customer_workspace = readOption(options.customerWorkspace);
+    const runIds = readCsvOption(options.runIds);
+    const tableIds = readCsvOption(options.tableIds);
+    const deepLinks = readCsvOption(options.deepLinks);
+    if (runIds.length)
+        context.run_ids = runIds;
+    if (tableIds.length)
+        context.table_ids = tableIds;
+    if (deepLinks.length)
+        context.deep_links = deepLinks;
+    if (Object.keys(context).length)
+        body.context = context;
+    return body;
+}
+function withSupportListQuery(path, options) {
+    const params = new URLSearchParams();
+    const status = readOption(options.status);
+    const limit = readOption(options.limit);
+    if (status)
+        params.set("status", status);
+    if (limit)
+        params.set("limit", limit);
+    const query = params.toString();
+    return query ? `${path}?${query}` : path;
+}
+function withSupportEventsQuery(path, options) {
+    const params = new URLSearchParams();
+    const after = readOption(options.after);
+    const limit = readOption(options.limit);
+    if (after)
+        params.set("after", after);
+    if (limit)
+        params.set("limit", limit);
+    const query = params.toString();
+    return query ? `${path}?${query}` : path;
+}
+// Workflow text flags (--verify-notes/--plan/--draft) bypass readOption: an
+// explicitly-passed empty string clears the field server-side, while an absent
+// flag leaves it untouched, so "" must survive to the request body.
+function buildSupportAdminWorkflowBody(options) {
+    const body = {};
+    const verifyStatus = readOption(options.verifyStatus);
+    if (verifyStatus)
+        body.verify_status = verifyStatus;
+    if (options.verifyNotes !== undefined)
+        body.verify_notes = options.verifyNotes;
+    const planStatus = readOption(options.planStatus);
+    if (planStatus)
+        body.plan_status = planStatus;
+    if (options.plan !== undefined)
+        body.plan = options.plan;
+    const draftStatus = readOption(options.draftStatus);
+    if (draftStatus)
+        body.draft_status = draftStatus;
+    if (options.draft !== undefined)
+        body.draft_reply = options.draft;
+    if (!Object.keys(body).length) {
+        throw new OxygenError("invalid_request", "Pass at least one of --verify-status, --verify-notes, --plan-status, --plan, --draft-status, --draft.", { exitCode: 1 });
+    }
+    return body;
+}
+function buildSupportAdminUpdateBody(options) {
+    if (options.assign !== undefined && options.unassign) {
+        throw new OxygenError("invalid_request", "Pass either --assign <email> or --unassign, not both.", {
+            exitCode: 1,
+        });
+    }
+    const body = {};
+    const status = readOption(options.status);
+    if (status)
+        body.status = status;
+    const assign = readOption(options.assign);
+    if (assign)
+        body.assignee_email = assign;
+    if (options.unassign)
+        body.assignee_email = null;
+    const note = readOption(options.note);
+    if (note)
+        body.note = note;
+    if (!Object.keys(body).length) {
+        throw new OxygenError("invalid_request", "Pass at least one of --status, --assign, --unassign, --note.", { exitCode: 1 });
+    }
+    return body;
+}
+function supportAdminOpenResult(data) {
+    if (!isRecord(data) || !isRecord(data.ticket)) {
+        throw new OxygenError("invalid_response", "The support admin response did not include a Plain Thread.", { exitCode: 1 });
+    }
+    const plainUrl = data.ticket.plain_url;
+    if (typeof plainUrl !== "string" || !plainUrl.startsWith("https://app.plain.com/")) {
+        throw new OxygenError("invalid_response", "The support admin response did not include a valid Plain Inbox URL.", { exitCode: 1 });
+    }
+    return {
+        thread_id: data.ticket.id ?? null,
+        thread_ref: data.ticket.ref ?? null,
+        plain_url: plainUrl,
+    };
+}
+async function handleSupportAdminUpdateRequest(action, ticketId, options, fields) {
+    await handleAsyncAction(`support admin ${action}`, options, () => requestOxygen(`/api/cli/admin/support/tickets/${encodeURIComponent(ticketId)}/update`, {
+        method: "POST",
+        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);
+        const data = await requestOxygen(`/api/cli/admin/support/tickets/${encodeURIComponent(ticketId)}/workflow`, { method: "POST", body });
+        if (options.json) {
+            writeJson(success("support admin workflow", data));
+            return;
+        }
+        process.stdout.write(formatSupportAdminWorkflowTicket(data));
+    }
+    catch (error) {
+        emitCliFailure("support admin workflow", error);
+    }
+}
+async function handleSupportAdminUpdateAction(ticketId, options) {
+    try {
+        const body = buildSupportAdminUpdateBody(options);
+        const data = await requestOxygen(`/api/cli/admin/support/tickets/${encodeURIComponent(ticketId)}/update`, { method: "POST", body });
+        if (options.json) {
+            writeJson(success("support admin update", data));
+            return;
+        }
+        process.stdout.write(formatSupportAdminUpdateTicket(data));
+    }
+    catch (error) {
+        emitCliFailure("support admin update", error);
+    }
+}
+function formatSupportAdminWorkflowStep(styles, label, status, artifactLabel, artifact) {
+    const artifactNote = artifact?.trim() ? `${artifactLabel} set` : `no ${artifactLabel}`;
+    return `  ${label.padEnd(6)} ${status ?? "pending"} ${styles.dim(`(${artifactNote})`)}`;
+}
+function formatSupportAdminWorkflowTicket(data) {
+    const styles = ansi(output.isTTY === true && !process.env.NO_COLOR);
+    const ticket = data.ticket ?? {};
+    const workflow = ticket.workflow ?? {};
+    const lines = [
+        `${styles.bold("Workflow updated")}${ticket.subject ? styles.dim(` — ${ticket.subject}`) : ""}`,
+        formatSupportAdminWorkflowStep(styles, "verify", workflow.verify_status, "notes", workflow.verify_notes),
+        formatSupportAdminWorkflowStep(styles, "plan", workflow.plan_status, "plan", workflow.plan),
+        formatSupportAdminWorkflowStep(styles, "draft", workflow.draft_status, "draft reply", workflow.draft_reply),
+    ];
+    if (ticket.admin_web_url)
+        lines.push(`View ticket: ${ticket.admin_web_url}`);
+    return `${lines.join("\n")}\n`;
+}
+function formatSupportAdminUpdateTicket(data) {
+    const styles = ansi(output.isTTY === true && !process.env.NO_COLOR);
+    const ticket = data.ticket ?? {};
+    const lines = [
+        `${styles.bold("Ticket updated")}${ticket.subject ? styles.dim(` — ${ticket.subject}`) : ""}`,
+        `  Status:   ${ticket.status ?? "?"}`,
+        `  Assignee: ${ticket.assignee_email ?? "(unassigned)"}`,
+    ];
+    if (ticket.admin_web_url)
+        lines.push(`View ticket: ${ticket.admin_web_url}`);
+    return `${lines.join("\n")}\n`;
+}
+export function registerSupportFamily(program, handleAsyncAction) {
+    program
+        .command("support")
+        .description("Open and track Plain support conversations for the active OXYGEN organization. In the app, the support chat is the widget in the bottom-right corner of every page. Retry is the only recovery control; it returns after each failed connection attempt and never creates a Thread. `support chat` starts or continues a zero-credit conversation without making you write a ticket title. Guide: https://oxygen-agent.com/docs/surfaces/support.")
+        .addCommand(new Command("chat")
+        .description("Start a Plain Chat conversation from one message, or pass an existing Thread ID to continue it. New conversations derive Plain's internal title from the message; you never have to file each message as a separate titled ticket.")
+        .argument("[threadId]", "Existing Plain Thread ID (th_...) or Thread ref (T-<n>) to continue. Omit to start a new conversation.")
+        .requiredOption("-m, --message <message>", "Your message to OXYGEN support.")
+        .option("--severity <severity>", "New conversation only: low | normal | high. Defaults to normal.")
+        .option("--category <category>", "New conversation only: question, bug, feature_request, billing, security_data, configuration, agency_directory, or other. Defaults to question.")
+        .option("--transcript-text <text>", "New conversation only: explicitly share a selected transcript excerpt of 1–200,000 bytes after credential redaction.")
+        .option("--no-transcript", "Omit any selected transcript excerpt.")
+        .option("--json", "Print a JSON envelope.")
+        .addHelpText("after", `
+Examples:
+  oxygen support chat --message "The dedicated IP is not being assigned" --category bug
+  oxygen support chat th_... --message "Here is the additional evidence"
+`)
+        .action(async (threadId, options) => {
+        const message = readOption(options.message);
+        if (threadId) {
+            await handleAsyncAction("support chat", options, () => {
+                if (options.transcript !== false && options.transcriptText !== undefined) {
+                    throw new OxygenError("invalid_transcript", "Transcript excerpts can only be attached when starting a new conversation. Omit the Thread ID or use support file.", { exitCode: 1 });
+                }
+                return requestOxygen(`/api/cli/support/tickets/${encodeURIComponent(threadId)}/messages`, {
+                    method: "POST",
+                    body: { body: message },
+                });
+            });
+            return;
+        }
+        const severity = readOption(options.severity);
+        await handleAsyncAction("support chat", options, () => {
+            const body = {
+                message,
+                category: readOption(options.category) ?? "question",
+                ...(severity ? { severity } : {}),
+            };
+            if (options.transcript !== false && options.transcriptText !== undefined) {
+                body.transcript_text = readSelectedTranscriptExcerpt(options.transcriptText);
+            }
+            return requestOxygen("/api/cli/support/tickets", {
+                method: "POST",
+                body,
+            });
+        });
+    }))
+        .addCommand(new Command("file")
+        .description("Create a structured Plain support conversation with a subject and required message. Prefer `support chat` for an ordinary conversation; use this zero-credit filing path when operation, error, run, or table metadata helps triage. Share a selected excerpt with --transcript-text, or a local transcript with --transcript-file, --session-id, or --include-transcript. Check `support list --status open` first because a new filing can create a second Thread.")
+        .requiredOption("--subject <subject>", "One-line summary of the problem.")
+        .requiredOption("--body <body>", "Required message: what you were doing, what happened, and what you tried.")
+        .option("--include-transcript", "Attach the most recent local agent transcript after redaction.")
+        .option("--session-id <id>", "Attach this local agent session transcript.")
+        .option("--transcript-file <path>", "Attach the last 2 MB of a selected text/JSONL file after best-effort credential redaction; review it first.")
+        .option("--transcript-text <text>", "Explicitly share a selected transcript excerpt of 1–200,000 bytes after credential redaction, instead of a local transcript.")
+        .option("--no-transcript", "Omit any transcript, including explicitly selected content.")
+        .option("--severity <severity>", "low | normal | high. Defaults to normal.")
+        .option("--category <category>", "Request type: question, bug, feature_request, billing, security_data, configuration, agency_directory, or other.")
+        .option("--source <source>", "Where the ticket originated. Only slack is supported today.")
+        .option("--operation <operation>", "The operation/tool that failed, e.g. oxygen_columns_run.")
+        .option("--error-code <code>", "The error envelope code you received.")
+        .option("--run-ids <ids>", "Comma-separated run ids to attach.")
+        .option("--table-ids <ids>", "Comma-separated table ids to attach.")
+        .option("--deep-links <urls>", "Comma-separated https://oxygen-agent.com/... links.")
+        .option("--slack-permalink <url>", "Slack message permalink (https://*.slack.com/...) to attach as context.")
+        .option("--slack-channel-id <id>", "Slack channel id (e.g. C0123ABC456) the report came from.")
+        .option("--customer-workspace <label>", "Customer workspace (org name/slug) a forwarded report concerns.")
+        .option("--cli-version <version>", "CLI version associated with the reported problem.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("support ticket create", options, () => requestOxygen("/api/cli/support/tickets", {
+            method: "POST",
+            body: buildSupportTicketBody(options),
+        }));
+    }))
+        .addCommand(new Command("list")
+        .description("List Plain support Threads for the active organization.")
+        .option("--status <status>", "Filter by status (open, triaging, waiting_on_user, resolved, closed).")
+        .option("--limit <n>", "Max tickets to return.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("support tickets list", options, () => requestOxygen(withSupportListQuery("/api/cli/support/tickets", options)));
+    }))
+        .addCommand(new Command("get")
+        .description("Show one Plain support Thread and its customer-visible timeline.")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>) — both shown by `oxygen support list` as `id` and `ref` — or a migrated legacy ticket UUID.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (ticketId, options) => {
+        await handleAsyncAction("support ticket get", options, () => requestOxygen(`/api/cli/support/tickets/${encodeURIComponent(ticketId)}`));
+    }))
+        .addCommand(new Command("reply")
+        .description("Reply to a Plain Chat thread; migrated or native-channel history continues in one linked Chat thread.")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>) — both shown by `oxygen support list` as `id` and `ref` — or a migrated legacy ticket UUID.")
+        .requiredOption("--body <body>", "Your reply.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (ticketId, options) => {
+        await handleAsyncAction("support ticket reply", options, () => requestOxygen(`/api/cli/support/tickets/${encodeURIComponent(ticketId)}/messages`, {
+            method: "POST",
+            body: { body: readOption(options.body) },
+        }));
+    }))
+        .addCommand(new Command("ack")
+        .description("Legacy command; Plain owns delivery and read state.")
+        .argument("<ticketId>", "Ticket UUID.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (ticketId, options) => {
+        await handleAsyncAction("support ticket ack", options, () => requestOxygen(`/api/cli/support/tickets/${encodeURIComponent(ticketId)}/ack`, {
+            method: "POST",
+            body: {},
+        }));
+    }), { hidden: true })
+        .addCommand(new Command("admin")
+        .description("Operate the live Plain support queue as OXYGEN staff. Public replies are previewed first and sent as the shared Oxygen Support identity.")
+        .addCommand(new Command("list")
+        .description("List live Plain Threads across customer Tenants (staff only).")
+        .option("--status <status>", "Filter by status.")
+        .option("--limit <n>", "Max tickets to return.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("support admin list", options, () => requestOxygen(withSupportListQuery("/api/cli/admin/support/tickets", options)));
+    }))
+        .addCommand(new Command("get")
+        .description("Show one live Plain Thread, its routing metadata, and customer-visible messages (staff only). Add --include-notes to also read back the Thread's team-only notes and staged reply drafts as `internal_notes` (kind note, reply_draft, suggested_reply_provenance or undelivered_customer_report); read-only, never shown to the customer.")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
+        .option("--include-notes", "Also return team-only internal notes and staged drafts.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (ticketId, options) => {
+        await handleAsyncAction("support admin get", options, () => requestOxygen(`/api/cli/admin/support/tickets/${encodeURIComponent(ticketId)}${options.includeNotes ? "?include_notes=1" : ""}`));
+    }))
+        .addCommand(new Command("open")
+        .description("Return the exact Plain Inbox URL for one live Thread (staff only).")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (ticketId, options) => {
+        await handleAsyncAction("support admin open", options, () => requestOxygen(`/api/cli/admin/support/tickets/${encodeURIComponent(ticketId)}`)
+            .then((data) => supportAdminOpenResult(data)));
+    }))
+        .addCommand(new Command("claim")
+        .description("Claim a live Plain Thread and move it to In progress without overwriting another assignee (staff only).")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
+        .option("--agent", "Claim as the authenticated Oxygen Support machine user instead of the signed-in human.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (ticketId, options) => {
+        await handleAsyncAction("support admin claim", options, () => requestOxygen(`/api/cli/admin/support/tickets/${encodeURIComponent(ticketId)}/update`, {
+            method: "POST",
+            body: { action: "claim", as_machine_user: options.agent === true },
+        }));
+    }))
+        .addCommand(new Command("start")
+        .description("Set a live Plain Thread to Plain TODO with the In progress detail when OXYGEN work remains after a reply, preserving its assignee (staff only).")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
+        .requiredOption("--agent", "Required safety declaration: reconcile this Thread's status as the Oxygen Support machine user.")
+        .requiredOption("--confirm-message <messageId>", "Apply only while this is still the exact latest customer-visible conversation-head message ID. From support admin get --json, use the id of the data.messages[] entry with the greatest created_at.")
+        .option("--json", "Print a JSON envelope.")
+        .addHelpText("after", `
+Safety: 0 credits, but this is a real Plain queue write. It preserves the current assignee and changes only the lifecycle to plain_status TODO with plain_status_detail ThreadStatusDetailInProgress (projected as ticket.status triaging).
+
+Safe sequence:
+  oxygen support admin get <thread-id> --json
+  # Select the data.messages[] entry with the greatest created_at and copy its id.
+  oxygen support admin start <thread-id> --agent --confirm-message <latest-message-id> --json
+  oxygen support admin get <thread-id> --json
+
+The final readback must show ticket.status triaging, plain_status TODO, the In progress detail, the same conversation head, and an unchanged assignee.
+`)
+        .action(async (ticketId, options) => {
+        await handleAsyncAction("support admin start", options, () => requestOxygen(`/api/cli/admin/support/tickets/${encodeURIComponent(ticketId)}/update`, {
+            method: "POST",
+            body: {
+                action: "start",
+                as_agent: true,
+                confirm_message_id: readOption(options.confirmMessage),
+            },
+        }));
+    }))
+        .addCommand(new Command("priority")
+        .description("Set the native Plain priority for a live Thread (staff only).")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
+        .requiredOption("--priority <priority>", "urgent | high | normal | low")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (ticketId, options) => {
+        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_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
+        .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_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
+        .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_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
+        .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_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
+        .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).")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
+        .requiredOption("--label <externalId>", "Plain label external ID, for example oxygen_request_bug.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (ticketId, options) => {
+        await handleSupportAdminUpdateRequest("label_add", ticketId, options, {
+            label_external_id: readOption(options.label),
+        });
+    }))
+        .addCommand(new Command("label-remove")
+        .description("Remove a Plain label by external ID (staff only).")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
+        .requiredOption("--label <externalId>", "Plain label external ID.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (ticketId, options) => {
+        await handleSupportAdminUpdateRequest("label_remove", ticketId, options, {
+            label_external_id: readOption(options.label),
+        });
+    }))
+        .addCommand(new Command("note")
+        .description("Add a team-only internal note to a live Plain Thread (staff only).")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
+        .requiredOption("--body <body>", "Internal note body.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (ticketId, options) => {
+        await handleSupportAdminUpdateRequest("note", ticketId, options, {
+            body: readOption(options.body),
+        });
+    }))
+        .addCommand(new Command("draft")
+        .description("Stage a reply as a team-only Plain note; this never sends to the customer (staff and agents).")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
+        .requiredOption("--body <body>", "Proposed customer reply.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (ticketId, options) => {
+        await handleSupportAdminUpdateRequest("draft", ticketId, options, {
+            body: readOption(options.body),
+        });
+    }))
+        .addCommand(new Command("reply")
+        .description("Preview or send a guarded public reply on the Thread's native Plain channel as Oxygen Support (staff only). CLI delivery is agent-only; named humans use Plain Inbox or Plain MCP.")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
+        .requiredOption("--body <body>", "Customer-visible reply body.")
+        .requiredOption("--agent", "Required safety declaration: reply as the authenticated Oxygen Support machine user after it owns the Thread.")
+        .option("--confirm-ref <ref>", "Send only when this exactly matches the previewed Plain ref (for example T-10). Omit to preview without sending.")
+        .option("--confirm-message <messageId>", "Agent send only: confirm the latest customer-visible conversation-head message ID returned by preview.")
+        .option("--confirm-token <token>", "Agent send only: use the exact server-authenticated preview token bound to the Thread, latest message, reply body, and actor mode; never calculate it locally.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (ticketId, options) => {
+        await handleAsyncAction("support admin reply", options, () => requestOxygen(`/api/cli/admin/support/tickets/${encodeURIComponent(ticketId)}/messages`, {
+            method: "POST",
+            body: {
+                body: readOption(options.body),
+                as_agent: true,
+                ...(readOption(options.confirmRef)
+                    ? { confirm_ref: readOption(options.confirmRef) }
+                    : {}),
+                ...(readOption(options.confirmMessage)
+                    ? { confirm_message_id: readOption(options.confirmMessage) }
+                    : {}),
+                ...(readOption(options.confirmToken)
+                    ? { confirm_token: readOption(options.confirmToken) }
+                    : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("done")
+        .description("Preview or mark a Plain Thread Done after the exact verified agent reply; new customer activity reopens it to Todo (staff only). CLI completion is agent-only.")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
+        .requiredOption("--agent", "Required safety declaration: mark Done as the authenticated Oxygen Support machine user while it still owns the Thread.")
+        .requiredOption("--reply-token <token>", "Use the exact agent_done_token returned by the preceding live `support admin reply --agent`; previews and errors never mint or reveal one.")
+        .option("--confirm-ref <ref>", "Complete only when this exactly matches the previewed Plain ref.")
+        .option("--confirm-message <messageId>", "Complete only when this exactly matches the latest verified staff reply ID from preview.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (ticketId, options) => {
+        await handleAsyncAction("support admin done", options, () => requestOxygen(`/api/cli/admin/support/tickets/${encodeURIComponent(ticketId)}/resolve`, {
+            method: "POST",
+            body: {
+                as_agent: true,
+                ...(readOption(options.replyToken)
+                    ? { agent_reply_token: readOption(options.replyToken) }
+                    : {}),
+                ...(readOption(options.confirmRef)
+                    ? { confirm_ref: readOption(options.confirmRef) }
+                    : {}),
+                ...(readOption(options.confirmMessage)
+                    ? { confirm_message_id: readOption(options.confirmMessage) }
+                    : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("file")
+        .description("Retired legacy write; always returns the Plain-cutover error (staff only).")
+        .requiredOption("--organization <organization>", "Target organization id or slug the ticket belongs to.")
+        .requiredOption("--subject <subject>", "One-line summary of the customer's request.")
+        .requiredOption("--body <body>", "The customer's request in their words, plus any staff notes.")
+        .option("--severity <severity>", "low | normal | high. Defaults to normal.")
+        .option("--category <category>", "Optional category label, e.g. bug, feature, question.")
+        .option("--source <source>", "Where the ticket originated. Only slack is supported today.")
+        .option("--operation <operation>", "The operation/tool involved, if known.")
+        .option("--error-code <code>", "The error envelope code, if known.")
+        .option("--run-ids <ids>", "Comma-separated run ids to attach.")
+        .option("--table-ids <ids>", "Comma-separated table ids to attach.")
+        .option("--deep-links <urls>", "Comma-separated https://oxygen-agent.com/... links.")
+        .option("--slack-permalink <url>", "Slack message permalink (https://*.slack.com/...) to attach as context.")
+        .option("--slack-channel-id <id>", "Slack channel id (e.g. C0123ABC456) the report came from.")
+        .option("--customer-workspace <label>", "Customer workspace label when --org is not the customer's own org.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("support admin file", options, () => requestOxygen("/api/cli/admin/support/tickets", {
+            method: "POST",
+            body: {
+                ...buildSupportTicketBody(options),
+                organization: readOption(options.organization),
+            },
+        }));
+    }), { 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).")
+        .option("--limit <n>", "Events to return (1-100, defaults to 50).")
+        .option("--json", "Print a JSON envelope.")
+        .addHelpText("after", `
+Event schema (each data.events item has exactly these fields):
+  event_kind: ticket_snapshot
+  ticket_ref: UUID; version: decimal string; event_time: UTC timestamp
+  status: open | triaging | waiting_on_user | resolved | closed | null
+  severity: low | normal | high | null
+  category: account | auth | billing | bug | data | deliverability |
+            feature_request | feedback | integration | other | performance |
+            provider | security | sequencer | tables | workflow | null
+  source: slack | null; route: slack | cli | mcp | web | null
+
+The cursor is opaque. has_more discriminates its phase: next_cursor continues a
+fixed scan; watermark_cursor starts a later bounded replay. Consumers must retain
+(ticket_ref, version) as the idempotency key across every poll.
+`)
+        .action(async (options) => {
+        await handleAsyncAction("support admin events", options, () => requestOxygen(withSupportEventsQuery("/api/cli/admin/support/events", options)));
+    }), { hidden: true })
+        .addCommand(new Command("workflow")
+        .description("Retired legacy write; Plain notes and downstream engineering work own triage (staff only).")
+        .argument("<ticketId>", "Ticket UUID.")
+        .option("--verify-status <status>", "Verify step: pending | in_progress | done | blocked | skipped.")
+        .option("--verify-notes <text>", "Verification notes. Pass an empty string to clear.")
+        .option("--plan-status <status>", "Plan step: pending | in_progress | done | blocked | skipped.")
+        .option("--plan <text>", "Remediation plan. Pass an empty string to clear.")
+        .option("--draft-status <status>", "Draft step: pending | in_progress | done | blocked | skipped.")
+        .option("--draft <text>", "Draft reply to the opener. Pass an empty string to clear.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (ticketId, options) => {
+        await handleSupportAdminWorkflowAction(ticketId, options);
+    }), { hidden: true })
+        .addCommand(new Command("update")
+        .description("Retired legacy write; Plain owns status, assignee, and notes (staff only).")
+        .argument("<ticketId>", "Ticket UUID.")
+        .option("--status <status>", "open | triaging | waiting_on_user | closed. Use the resolve command to resolve.")
+        .option("--assign <email>", "Assign the ticket to a staff email.")
+        .option("--unassign", "Clear the ticket assignment.")
+        .option("--note <text>", "Append a staff message to the ticket thread.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (ticketId, options) => {
+        await handleSupportAdminUpdateAction(ticketId, options);
+    }), { hidden: true }));
+}