@oxygen-agent/cli 1.1014.136 → 1.1014.618

package/dist/commands/copilot.js

@@ -0,0 +1,565 @@
+import { emitCliFailure, emitSuccess } from "../cli-output.js";
+import { readJsonObjectOption, readNonNegativeInt, readPositiveInt, readRecordString } from "../cli-values.js";
+import { collectRepeatable, readPositiveNumber } from "../command-support.js";
+import { addContractFlags, readContractFlags } from "../contract-flags.js";
+import { requestOxygen } from "../http-client.js";
+import { waitForCliRun } from "../run-wait.js";
+import { resolveCliBinaryName } from "../runtime.js";
+import { isRecord, readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { COPILOT_SESSIONS_LIST_CONTRACT } from "@oxygen/shared/contracts/copilot-sessions";
+import { formatCopilotPlanDuration, formatCopilotPlanSeconds, normalizeCopilotPlanStepStatus } from "@oxygen/shared/copilot-plan";
+import { COPILOT_ASK_USER_TOOL_NAME, normalizeCopilotQuestions } from "@oxygen/shared/copilot-questions";
+import { Command, Option } from "commander";
+import { readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+// `copilot send` streams a single turn: a shorter default deadline than a batch
+// workflow tail, polled every couple of seconds so assistant text feels live.
+const COPILOT_SEND_DEFAULT_TIMEOUT_SECONDS = 300;
+const COPILOT_SEND_DEFAULT_INTERVAL_SECONDS = 2;
+// "Show me" is retired (2026-10-14): the web app shows what the copilot creates
+// or changes in the chat, and nothing moves anyone's screen. `copilot follow`
+// and --no-follow stay so older scripts keep running; they change nothing.
+const FOLLOW_RETIRED_NOTICE = "The web app now shows changes in the chat.";
+/**
+ * Attach one local file to a copilot session: presign, PUT the bytes straight to
+ * object storage, then have the server verify and describe what landed.
+ *
+ * The middle hop bypasses the API on purpose — the same reason `tables import`
+ * does it. A real lead list does not fit in a request body, and the worker reads
+ * the object out of the bucket anyway.
+ */
+async function uploadCopilotAttachment(sessionId, filePath) {
+    const resolved = resolve(filePath);
+    let fileBuffer;
+    try {
+        fileBuffer = readFileSync(resolved);
+    }
+    catch {
+        throw new OxygenError("file_not_found", `Could not read ${filePath}.`, { exitCode: 1 });
+    }
+    const fileName = basename(resolved);
+    const ticket = await requestOxygen(`/api/cli/copilot/sessions/${encodeURIComponent(sessionId)}/attachments`, {
+        method: "POST",
+        body: {
+            file_name: fileName,
+            content_length: fileBuffer.byteLength,
+        },
+    });
+    const upload = isRecord(ticket.upload) ? ticket.upload : {};
+    const attachment = isRecord(ticket.attachment) ? ticket.attachment : {};
+    const uploadUrl = readRecordString(upload, "url");
+    const attachmentId = readRecordString(attachment, "id");
+    if (!uploadUrl || !attachmentId) {
+        throw new OxygenError("attachment_upload_failed", "The server did not return an upload URL for that attachment.", { exitCode: 1 });
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 300_000);
+    // Content-Type is bound into the storage signature. Older tickets omit the
+    // SDK's binary default; newer tickets supply every required upload header.
+    const uploadHeaders = { "content-type": "application/octet-stream" };
+    if (isRecord(upload.headers)) {
+        for (const [name, value] of Object.entries(upload.headers)) {
+            if (typeof value === "string")
+                uploadHeaders[name] = value;
+        }
+    }
+    let putResponse;
+    try {
+        putResponse = await fetch(uploadUrl, {
+            method: "PUT",
+            headers: uploadHeaders,
+            body: new Uint8Array(fileBuffer),
+            signal: controller.signal,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!putResponse.ok) {
+        throw new OxygenError("attachment_upload_failed", `Uploading ${fileName} to object storage failed (HTTP ${putResponse.status}).`, { details: { status: putResponse.status }, exitCode: 1 });
+    }
+    const completed = await requestOxygen(`/api/cli/copilot/sessions/${encodeURIComponent(sessionId)}/attachments/${encodeURIComponent(attachmentId)}/complete`, { method: "POST", timeoutMs: 120_000 });
+    return {
+        id: attachmentId,
+        attachment: isRecord(completed.attachment) ? completed.attachment : { id: attachmentId },
+    };
+}
+function isTerminalCopilotTurnStatus(status) {
+    // Terminal here means "stop streaming this turn": completed/failed/cancelled
+    // are final, and awaiting_input parks the turn on a human decision (an
+    // approval) that the caller surfaces rather than polling through.
+    return status === "completed" || status === "failed"
+        || status === "cancelled" || status === "awaiting_input";
+}
+function readCopilotTurnStatus(data, turnId) {
+    const turns = Array.isArray(data.turns) ? data.turns : [];
+    for (const turn of turns) {
+        if (isRecord(turn) && turn.id === turnId) {
+            return typeof turn.status === "string" ? turn.status : null;
+        }
+    }
+    return null;
+}
+function readCopilotTurnCreditsCaptured(data, turnId) {
+    const turns = Array.isArray(data.turns) ? data.turns : [];
+    for (const turn of turns) {
+        if (isRecord(turn) && turn.id === turnId && typeof turn.credits_captured === "number") {
+            return turn.credits_captured;
+        }
+    }
+    return null;
+}
+// The session-detail payload carries no top-level `credits` block, so the shared
+// writeCreditsReceipt (which handleAsyncAction runs on the returned data) is a
+// no-op for `copilot send`. Mirror the sent turn's own captured spend as one
+// stderr line so a terminal still shows what the turn cost.
+function writeCopilotTurnCreditsSummary(data, turnId) {
+    const captured = readCopilotTurnCreditsCaptured(data, turnId);
+    if (captured === null)
+        return;
+    process.stderr.write(`credits used this turn: ${captured.toLocaleString("en-US")}\n`);
+}
+// Print one appended copilot event to stderr as it streams in. assistant_delta
+// text is written verbatim — no prefix, no trailing newline — so the model's
+// output flows as one continuous block; every other kind is a one-line human
+// notice. billing_settled is intentionally silent (its spend lands in the
+// end-of-turn credits summary); tool_call_* surface as brief progress so a turn
+// that pauses on a slow capability does not look frozen.
+/**
+ * The plan as a person reads it.
+ *
+ * `copilot get` has no human renderer at all -- both its branches call writeJson,
+ * so --json only decides whether the payload is wrapped in an envelope. This leaf
+ * exists because "how far along is it" is a question a JSON dump answers badly,
+ * and because the same projection has to be legible on all three surfaces.
+ */
+function writeCopilotPlan(plan, webUrl) {
+    if (!isRecord(plan)) {
+        process.stdout.write("No plan yet. The copilot publishes one for multi-step work; a short answer finishes without planning.\n");
+        return;
+    }
+    const progress = isRecord(plan.progress) ? plan.progress : {};
+    const eta = isRecord(plan.eta) ? plan.eta : {};
+    const steps = Array.isArray(plan.steps) ? plan.steps : [];
+    const lines = [];
+    if (typeof plan.summary === "string" && plan.summary)
+        lines.push(plan.summary, "");
+    lines.push(`${progress.done ?? 0}/${progress.total ?? 0} steps done${formatPlanEta(eta, plan.turnActive !== false)}`, "");
+    for (const step of steps) {
+        if (!isRecord(step))
+            continue;
+        const status = String(step.status ?? "pending");
+        const mark = status === "done" ? "[x]" : status === "in_progress" ? "[>]" : status === "blocked" ? "[!]" : "[ ]";
+        const timing = status === "done"
+            ? formatPlanDuration(step.elapsedMs)
+            : typeof step.etaSeconds === "number" ? `~${formatCopilotPlanSeconds(step.etaSeconds)} left` : "";
+        lines.push(`${mark} ${String(step.title ?? "")}${timing ? `  (${timing})` : ""}`);
+        for (const sub of Array.isArray(step.substeps) ? step.substeps : []) {
+            if (!isRecord(sub))
+                continue;
+            const subStatus = String(sub.status ?? "pending");
+            const subMark = subStatus === "done" ? "-" : subStatus === "blocked" ? "!" : ">";
+            const subTiming = formatPlanDuration(sub.durationMs);
+            lines.push(`      ${subMark} ${String(sub.title ?? "")}${subTiming ? `  (${subTiming})` : ""}`);
+        }
+    }
+    if (typeof webUrl === "string" && webUrl)
+        lines.push("", webUrl);
+    process.stdout.write(`${lines.join("\n")}\n`);
+}
+/** Every estimate names its basis, so nobody reads a guess as a measurement. */
+function formatPlanEta(eta, turnActive) {
+    // Nothing is running, so nothing REMAINS. "estimating" on a session that stopped
+    // weeks ago describes work in flight that does not exist; the step marks still
+    // say where the copilot got to, which is the honest half of the answer.
+    if (!turnActive)
+        return "";
+    const remaining = typeof eta.remainingSeconds === "number" ? eta.remainingSeconds : null;
+    if (remaining === null)
+        return " · time remaining: estimating";
+    const measured = typeof eta.measuredSteps === "number" ? eta.measuredSteps : 0;
+    const basis = eta.basis === "calibrated" || eta.basis === "measured"
+        ? `measured from ${measured} completed step${measured === 1 ? "" : "s"}`
+        : eta.basis === "model" ? "estimated, nothing measured yet" : "no basis";
+    const bound = eta.deadlineBound === true ? ", capped by the turn deadline" : "";
+    return ` · ~${formatCopilotPlanSeconds(remaining)} left (${basis}${bound})`;
+}
+/** Narrows the untyped ledger value, then defers to the one shared formatter. */
+function formatPlanDuration(ms) {
+    return (typeof ms === "number" ? formatCopilotPlanDuration(ms) : null) ?? "";
+}
+function printCopilotEvent(event, sessionId) {
+    if (!isRecord(event))
+        return;
+    const kind = typeof event.kind === "string" ? event.kind : "";
+    const payload = isRecord(event.payload) ? event.payload : {};
+    switch (kind) {
+        case "assistant_delta": {
+            const text = typeof payload.text === "string" ? payload.text : "";
+            if (text)
+                process.stderr.write(text);
+            return;
+        }
+        case "tool_call_started": {
+            // A question prints whole once it is asked; "[tool] ask_user…" says nothing.
+            if (payload.tool === COPILOT_ASK_USER_TOOL_NAME)
+                return;
+            const capability = typeof payload.capability === "string" ? payload.capability : "tool";
+            process.stderr.write(`\n[tool] ${capability}…\n`);
+            return;
+        }
+        case "tool_call_finished": {
+            if (payload.tool === COPILOT_ASK_USER_TOOL_NAME) {
+                printCopilotQuestion(payload, sessionId);
+                return;
+            }
+            const capability = typeof payload.capability === "string" ? payload.capability : "tool";
+            const summary = typeof payload.summary === "string" ? payload.summary : "";
+            process.stderr.write(`[tool] ${capability} ${payload.ok === true ? "ok" : "failed"}${summary ? ` — ${summary}` : ""}\n`);
+            return;
+        }
+        case "approval_requested": {
+            const capability = typeof payload.capability === "string" ? payload.capability : "action";
+            const preview = typeof payload.preview === "string" ? payload.preview : "";
+            const estimated = typeof payload.estimated_credits === "number" ? payload.estimated_credits : null;
+            const approvalId = typeof payload.approval_id === "string" ? payload.approval_id : "";
+            process.stderr.write(`\n[approval required] ${capability}${preview ? ` — ${preview}` : ""}`
+                + `${estimated !== null ? ` (~${estimated.toLocaleString("en-US")} credits)` : ""}. `
+                + `Approve with: ${resolveCliBinaryName()} copilot approve ${sessionId} ${approvalId}\n`);
+            return;
+        }
+        case "plan_updated": {
+            // The plan is the one event that says how far along the turn is, and it was
+            // the only kind this printer dropped -- a `copilot send` streamed every tool
+            // call it made and never once said what it was working towards.
+            const steps = Array.isArray(payload.steps) ? payload.steps : [];
+            const done = steps.filter((step) => isRecord(step) && normalizeCopilotPlanStepStatus(step.status) === "done").length;
+            const current = steps.find((step) => isRecord(step) && normalizeCopilotPlanStepStatus(step.status) === "in_progress");
+            const title = isRecord(current)
+                ? String(current.title ?? current.description ?? "").trim()
+                : "";
+            process.stderr.write(`\n[plan] ${done}/${steps.length} done${title ? ` — now: ${title}` : ""}\n`);
+            return;
+        }
+        case "fallback_engaged": {
+            const from = typeof payload.from === "string" ? payload.from : "?";
+            const to = typeof payload.to === "string" ? payload.to : "?";
+            const reason = typeof payload.reason === "string" ? payload.reason : "";
+            process.stderr.write(`[model fallback] ${from} → ${to}${reason ? ` (${reason})` : ""}\n`);
+            return;
+        }
+        case "error": {
+            const code = typeof payload.code === "string" ? payload.code : "error";
+            const message = typeof payload.message === "string" ? payload.message : "";
+            process.stderr.write(`[error] ${code}${message ? `: ${message}` : ""}\n`);
+            return;
+        }
+        default:
+            return;
+    }
+}
+/**
+ * The Copilot ended its turn on a question (`ask_user`). The web answers it on a
+ * card; here the options print numbered and the answer is the next message, so
+ * nothing about it needs a command of its own.
+ */
+function printCopilotQuestion(payload, sessionId) {
+    const result = isRecord(payload.result) ? payload.result : {};
+    if (result.ok === false)
+        return;
+    const asked = normalizeCopilotQuestions(result.questions);
+    if (!asked.ok)
+        return;
+    const lines = [];
+    for (const question of asked.questions) {
+        lines.push(`\n[question] ${question.question}${question.multiSelect ? " (choose any)" : ""}`);
+        question.options.forEach((option, index) => {
+            lines.push(`  ${index + 1}. ${option.label}${option.recommended ? " (recommended)" : ""}`
+                + `${option.description ? ` — ${option.description}` : ""}`);
+        });
+    }
+    lines.push(`Answer with: ${resolveCliBinaryName()} copilot send ${sessionId} <your answer>\n`);
+    process.stderr.write(lines.join("\n"));
+}
+// `copilot send` is the CLI's one streaming wait surface. It reuses the shared
+// waitForCliRun poll loop (timeout/interval parsing, deadline, bounded sleep,
+// typed timeout throw) but injects a fetch that GETs the session detail after a
+// moving `after_seq` cursor, prints each newly appended event to stderr, and
+// advances the cursor to latest_seq. The SENT TURN's status — not the session's
+// — is the terminal signal, so fetchRun returns a record whose `status` mirrors
+// that turn while shapeTerminal returns the last full GET payload for scripts.
+function waitForCopilotTurn(options) {
+    let cursor = options.initialSeq;
+    let latestData = {};
+    return waitForCliRun({
+        runId: options.turnId,
+        requestedTimeoutSeconds: options.requestedTimeoutSeconds,
+        requestedIntervalSeconds: options.requestedIntervalSeconds,
+        defaultTimeoutSeconds: COPILOT_SEND_DEFAULT_TIMEOUT_SECONDS,
+        defaultIntervalSeconds: COPILOT_SEND_DEFAULT_INTERVAL_SECONDS,
+        fetchRun: async () => {
+            const query = new URLSearchParams({ after_seq: String(cursor) });
+            latestData = await requestOxygen(`/api/cli/copilot/sessions/${encodeURIComponent(options.sessionId)}?${query.toString()}`);
+            const events = Array.isArray(latestData.events) ? latestData.events : [];
+            for (const event of events)
+                printCopilotEvent(event, options.sessionId);
+            const latestSeq = latestData.latest_seq;
+            if (typeof latestSeq === "number" && Number.isFinite(latestSeq))
+                cursor = latestSeq;
+            // waitForCliRun reads terminality off `status`; mirror the sent turn's
+            // status there while leaving latestData itself untouched for shapeTerminal.
+            return { ...latestData, status: readCopilotTurnStatus(latestData, options.turnId) };
+        },
+        isTerminal: isTerminalCopilotTurnStatus,
+        shapeTerminal: () => latestData,
+        timeoutCode: "copilot_send_timeout",
+        // Only the CLI stops waiting. The turn keeps running on the server and keeps
+        // billing until it finishes or is interrupted, so the timeout says so and names
+        // the commands that read and stop it.
+        timeoutMessage: "Stopped waiting for the copilot turn. It is still running and keeps spending credits until it finishes or you interrupt it.",
+        timeoutDetailIdKey: "turn_id",
+        timeoutExtraDetails: () => ({
+            session_id: options.sessionId,
+            turn_still_running: true,
+            next_step: `oxygen copilot get ${options.sessionId}`,
+            interrupt_command: `oxygen copilot interrupt ${options.sessionId} ${options.turnId}`,
+        }),
+    });
+}
+export function registerCopilotFamily(program, handleAsyncAction) {
+    program
+        .command("copilot")
+        .description("Workspace Copilot: an attended workspace agent you drive turn by turn from the terminal. Start a session, send it messages and watch the reply stream, approve the actions it proposes, then cancel when done. Managed inference uses workspace credits; paid or external actions keep their own approval gates. Web: /copilot.")
+        .addCommand(new Command("dev-eval")
+        .description("DEV staff owner only: immutable USD30 campaign and supplier ledger; classify dispatches guarded inference.")
+        .argument("<operation>", "create, register, readiness, ledger, effects, classify, accept-pilot or end")
+        .option("--campaign-id <uuid>")
+        .option("--session-id <uuid>")
+        .option("--models <ids>", "Comma-separated exact priced model IDs for create")
+        .option("--question-set <name>", "Pinned thesis-icp-1 or title-fit-1")
+        .option("--state-json <json>", "Classifier state from the native readout")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (operation, options) => {
+        await handleAsyncAction("copilot dev-eval", options, () => {
+            if (operation === "readiness")
+                return requestOxygen("/api/cli/copilot/dev-eval?readiness=1");
+            if (operation === "effects")
+                return requestOxygen(`/api/cli/copilot/dev-eval?campaign_id=${encodeURIComponent(options.campaignId ?? "")}&session_id=${encodeURIComponent(options.sessionId ?? "")}`);
+            if (operation === "ledger")
+                return requestOxygen(`/api/cli/copilot/dev-eval?campaign_id=${encodeURIComponent(options.campaignId ?? "")}`);
+            if (!["create", "register", "end", "classify", "accept-pilot"].includes(operation))
+                throw new OxygenError("invalid_input", "Unknown campaign operation.", { exitCode: 1 });
+            return requestOxygen("/api/cli/copilot/dev-eval", { method: "POST", body: {
+                    operation, campaign_id: options.campaignId, session_id: options.sessionId,
+                    ...(options.questionSet ? { question_set: options.questionSet, state: JSON.parse(options.stateJson ?? "null") } : {}),
+                    ...(options.models ? { models: options.models.split(",").map(value => value.trim()) } : {}),
+                } });
+        });
+    }), { hidden: true })
+        .addCommand(new Command("start")
+        .description("Start an attended Workspace Copilot session on Oxygen Balanced by default. Starting is free; the next send starts inference using workspace credits. No inference budget is required. Legacy budget flags remain accepted but do not authorize or cap spend. Paid or external actions require separate approval.")
+        .option("--budget-credits <number>", "Legacy compatibility only: accepted and clamped, but does not authorize or cap attended Copilot inference.")
+        .option("--tier <auto|low|medium|high>", "Model tier: auto=Oxygen Auto, low=Oxygen Fast, medium=Oxygen Balanced (default), high=Oxygen Max.")
+        .option("--model <id>", "Pin a specific priced model id. Unknown ids fall back to the selected tier.")
+        .option("--per-turn-ceiling <number>", "Legacy compatibility only: accepted and clamped, but does not cap an attended turn.")
+        .option("--journey <slug>", "Optional journey slug to seed the session's goal and context.")
+        .option("--title <text>", "Optional human title for the session.")
+        .option("--auto-approve", "Start with auto-approve ON for paid, workspace-internal actions (cards are still created and decided automatically within each action's credit cap). External sends, sequence starts, publishes, DNS, and external CRM pushes always stay human-gated.")
+        .addOption(new Option("--no-follow", "Retired: the web app now shows changes in the chat. Still accepted so older scripts keep running.").hideHelp())
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("copilot start", options, () => {
+            const budgetCredits = readPositiveNumber(options.budgetCredits);
+            if (options.budgetCredits !== undefined && budgetCredits === undefined) {
+                throw new OxygenError("invalid_budget", "When supplied for legacy compatibility, --budget-credits must be a positive number.", { exitCode: 1 });
+            }
+            const perTurnCeiling = readPositiveNumber(options.perTurnCeiling);
+            if (options.perTurnCeiling !== undefined && perTurnCeiling === undefined) {
+                throw new OxygenError("invalid_budget", "When supplied for legacy compatibility, --per-turn-ceiling must be a positive number.", { exitCode: 1 });
+            }
+            const tier = readOption(options.tier);
+            const model = readOption(options.model);
+            const journey = readOption(options.journey);
+            const title = readOption(options.title);
+            const body = {};
+            if (budgetCredits !== undefined)
+                body.budget_credits = budgetCredits;
+            if (tier)
+                body.tier = tier;
+            if (model)
+                body.model = model;
+            if (perTurnCeiling !== undefined)
+                body.per_turn_credit_ceiling = perTurnCeiling;
+            if (journey)
+                body.journey = journey;
+            if (title)
+                body.title = title;
+            if (options.autoApprove)
+                body.auto_approve = true;
+            if (options.follow === false)
+                process.stderr.write(`${FOLLOW_RETIRED_NOTICE}\n`);
+            return requestOxygen("/api/cli/copilot/sessions", { method: "POST", body });
+        });
+    }))
+        .addCommand(addContractFlags(new Command("list")
+        .description("List Workspace Copilot conversations by session status, newest first; this read starts no inference.")
+        .option("--json", "Print a JSON envelope."), COPILOT_SESSIONS_LIST_CONTRACT)
+        .action(async (options) => {
+        await handleAsyncAction("copilot list", options, () => {
+            const selectors = readContractFlags(options, COPILOT_SESSIONS_LIST_CONTRACT);
+            const query = new URLSearchParams(Object.entries(selectors).map(([key, value]) => [key, String(value)]));
+            return requestOxygen(`/api/cli/copilot/sessions${query.size ? `?${query}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("get")
+        .description("Show one Workspace Copilot session: its state, turns, and event log. Use --after-seq to page through the event stream, --before to read earlier turns of a long chat.")
+        .argument("<sessionId>", "Copilot session id.")
+        .option("--after-seq <n>", "Only return events after this sequence number.")
+        .option("--events <n>", "Maximum events to return.")
+        .option("--wait-seconds <n>", "Native bounded event long-poll, requires --after-seq (maximum 50 seconds).")
+        .option("--before <turn>", "Only return turns before this turn index (window.first_turn_index loads earlier ones).")
+        .option("--turns <n>", "Maximum turns to return (a teammate chat returns its newest 40 by default).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sessionId, options) => {
+        await handleAsyncAction("copilot get", options, () => {
+            const query = new URLSearchParams();
+            const afterSeq = readNonNegativeInt(options.afterSeq);
+            const eventLimit = readPositiveInt(options.events);
+            const turnsBefore = readNonNegativeInt(options.before);
+            const turnLimit = readPositiveInt(options.turns);
+            if (afterSeq !== undefined)
+                query.set("after_seq", String(afterSeq));
+            if (options.waitSeconds !== undefined)
+                query.set("wait_seconds", String(options.waitSeconds));
+            if (eventLimit !== undefined)
+                query.set("event_limit", String(eventLimit));
+            if (turnsBefore !== undefined)
+                query.set("turns_before", String(turnsBefore));
+            if (turnLimit !== undefined)
+                query.set("turn_limit", String(turnLimit));
+            const suffix = query.toString() ? `?${query.toString()}` : "";
+            return requestOxygen(`/api/cli/copilot/sessions/${encodeURIComponent(sessionId)}${suffix}`);
+        });
+    }))
+        .addCommand(new Command("plan")
+        .description("Show how far along a Workspace Copilot session is: its plan's major steps, the substeps under each, what is done, and how much longer the rest is expected to take.")
+        .argument("<sessionId>", "Copilot session id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sessionId, options) => {
+        const result = await requestOxygen(`/api/cli/copilot/sessions/${encodeURIComponent(sessionId)}?event_limit=1`).catch((error) => {
+            emitCliFailure("copilot plan", error);
+            return null;
+        });
+        if (!result)
+            return;
+        const plan = isRecord(result) ? result.plan : null;
+        if (options.json) {
+            emitSuccess("copilot plan", { plan, web_url: isRecord(result) ? result.web_url : null }, options);
+            return;
+        }
+        writeCopilotPlan(plan, isRecord(result) ? result.web_url : null);
+    }))
+        .addCommand(new Command("follow")
+        .description("Retired compatibility command: the web app now shows what the copilot creates or changes in the chat, and nothing moves your screen, so this changes nothing.")
+        .argument("<sessionId>", "Copilot session id.")
+        .option("--off", "Retired compatibility flag; changes nothing.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sessionId, options) => {
+        await handleAsyncAction("copilot follow", options, async () => {
+            // The server accepts the retired field and answers with its notice.
+            const result = await requestOxygen(`/api/cli/copilot/sessions/${encodeURIComponent(sessionId)}`, {
+                method: "PATCH",
+                body: { surface_policy: options.off ? "off" : "follow" },
+            });
+            process.stderr.write(`${FOLLOW_RETIRED_NOTICE}\n`);
+            return result;
+        });
+    }))
+        .addCommand(new Command("send")
+        .description("Send a message to a Workspace Copilot session and stream the reply to stderr. Waits for the turn to finish (or pause for an approval) unless --no-wait. Managed inference uses workspace credits.")
+        .argument("<sessionId>", "Copilot session id.")
+        .argument("<message...>", "Message to send (all words joined with spaces).")
+        .option("--no-wait", "Post the turn and return immediately without streaming the reply.")
+        .option("--context <json>", "Optional JSON object of surface context to attach to the turn.")
+        .option("--attach <path>", "Attach a file to this message (repeatable). Spreadsheets become tables the copilot can import and enrich; text documents ground the conversation. Uploaded straight to object storage, so large files are fine.", collectRepeatable, [])
+        .option("--timeout-seconds <n>", "Maximum time to wait for the turn to finish. Defaults to 300.")
+        .option("--interval-seconds <n>", "Polling interval while streaming. Defaults to 2.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sessionId, messageParts, options) => {
+        await handleAsyncAction("copilot send", options, async () => {
+            const message = messageParts.join(" ");
+            const context = readJsonObjectOption(options.context);
+            const attachmentIds = [];
+            for (const path of options.attach ?? []) {
+                const attached = await uploadCopilotAttachment(sessionId, path);
+                attachmentIds.push(attached.id);
+            }
+            const posted = await requestOxygen(`/api/cli/copilot/sessions/${encodeURIComponent(sessionId)}/turns`, {
+                method: "POST",
+                body: {
+                    message,
+                    ...(context ? { context } : {}),
+                    ...(attachmentIds.length > 0 ? { attachment_ids: attachmentIds } : {}),
+                },
+            });
+            // Commander maps --no-wait to `wait: false` (default true).
+            if (options.wait === false)
+                return posted;
+            const turn = isRecord(posted.turn) ? posted.turn : {};
+            const turnId = typeof turn.id === "string" ? turn.id : "";
+            const latestSeq = posted.latest_seq;
+            const initialSeq = typeof latestSeq === "number" && Number.isFinite(latestSeq) ? latestSeq : 0;
+            const finalData = await waitForCopilotTurn({
+                sessionId,
+                turnId,
+                initialSeq,
+                requestedTimeoutSeconds: options.timeoutSeconds,
+                requestedIntervalSeconds: options.intervalSeconds,
+            });
+            writeCopilotTurnCreditsSummary(finalData, turnId);
+            return finalData;
+        });
+    }))
+        .addCommand(new Command("attach")
+        .description("Attach a file to a Workspace Copilot session without sending a message yet. The file uploads straight to object storage and is described back to you (a spreadsheet's columns and row count); pass the returned id to `copilot send --attach` or just send next — unsent attachments ride the next message.")
+        .argument("<sessionId>", "Copilot session id.")
+        .argument("<path>", "Path to the file to attach.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sessionId, path, options) => {
+        await handleAsyncAction("copilot attach", options, () => uploadCopilotAttachment(sessionId, path).then((result) => ({
+            attachment: result.attachment,
+        })));
+    }))
+        .addCommand(new Command("attachments")
+        .description("List the files attached to a Workspace Copilot session, sent and unsent.")
+        .argument("<sessionId>", "Copilot session id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sessionId, options) => {
+        await handleAsyncAction("copilot attachments", options, () => requestOxygen(`/api/cli/copilot/sessions/${encodeURIComponent(sessionId)}/attachments`));
+    }))
+        .addCommand(new Command("approve")
+        .description("Approve (or, with --reject, reject) an action a Workspace Copilot session is waiting on; approving re-queues the paused turn.")
+        .argument("<sessionId>", "Copilot session id.")
+        .argument("<approvalId>", "Approval id from the approval_requested event.")
+        .option("--reject", "Reject the action instead of approving it.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sessionId, approvalId, options) => {
+        await handleAsyncAction("copilot approve", options, () => requestOxygen(`/api/cli/copilot/sessions/${encodeURIComponent(sessionId)}/approvals/${encodeURIComponent(approvalId)}`, { method: "POST", body: { decision: options.reject ? "reject" : "approve" } }));
+    }))
+        .addCommand(new Command("interrupt")
+        .description("Stop the turn a Workspace Copilot session is currently working on, leaving the session open for your next message.")
+        .argument("<sessionId>", "Copilot session id.")
+        .argument("<turnId>", "Turn id to stop (see `oxygen copilot get <sessionId>`).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sessionId, turnId, options) => {
+        await handleAsyncAction("copilot interrupt", options, () => requestOxygen(`/api/cli/copilot/sessions/${encodeURIComponent(sessionId)}/turns/${encodeURIComponent(turnId)}/interrupt`, { method: "POST" }));
+    }))
+        .addCommand(new Command("cancel")
+        .description("End a Workspace Copilot session for good, stopping any in-flight turn. The session cannot take new messages afterwards — to stop only the current turn, use `copilot interrupt`.")
+        .argument("<sessionId>", "Copilot session id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sessionId, options) => {
+        await handleAsyncAction("copilot cancel", options, () => requestOxygen(`/api/cli/copilot/sessions/${encodeURIComponent(sessionId)}/cancel`, { method: "POST" }));
+    }));
+}

package/dist/commands/crm.d.ts

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