@oxygen-agent/cli 1.1011.1091 → 1.1013.15

package/README.md

@@ -34,4 +34,4 @@ oxygen update
 
 For product documentation, visit https://oxygen-agent.com/docs. For support, visit https://oxygen-agent.com.
 
-Version: 1.1011.1091
+Version: 1.1013.15

package/dist/command-manifest.d.ts

@@ -17,6 +17,7 @@ export type CommandManifestEntry = {
     flags: CommandManifestFlag[];
     spends_credits: boolean;
     mutates: boolean;
+    destructive: boolean;
     preview_by_default: boolean;
     json_supported: boolean;
     hidden: boolean;
@@ -33,10 +34,11 @@ export type CommandSearchResult = {
     total_matches: number;
     returned: number;
     route: Record<string, unknown> | null;
-    commands: Array<Pick<CommandManifestEntry, "name" | "group" | "description" | "spends_credits" | "mutates" | "json_supported" | "hidden"> & {
+    commands: Array<Pick<CommandManifestEntry, "name" | "group" | "description" | "spends_credits" | "mutates" | "destructive" | "json_supported" | "hidden"> & {
         score: number;
     }>;
     hydrate: string;
+    next_step?: string;
 };
 export declare function buildCommandManifest(program: Command, binaryName: string): CommandManifest;
 /** Bounded natural-language projection over the complete local manifest. */

package/dist/command-manifest.js

@@ -108,6 +108,13 @@ const MUTATING_COMMANDS = new Set([
     // credits. The exact exceptions disclose writes without inventing spend.
     "billing balance",
     "billing seats",
+    // The ledger audit reads that same balance first, with the same conditional writes.
+    "billing audit",
+    // Creates an approval or Checkout link; a first plan's Checkout can start the
+    // first-month offer window. The plan changes only after an admin confirms.
+    "billing change",
+    // --approved records a domain's renewal exit, or with --revoke resumes renewals.
+    "managed-inboxes exit",
     // A default preview is free; approval restores provider seats and billing.
     "managed-inboxes recover",
     "mailboxes warmup status",
@@ -215,6 +222,7 @@ const READ_ONLY_COMMANDS = new Set([
 // invocation still previews, so machine-readable discovery must not imply that
 // calling the command without its confirmation flag writes anything.
 const PREVIEW_BY_DEFAULT_COMMANDS = new Set([
+    "mailboxes warmup enable",
     "mailboxes warmup google",
     "deliverability placement-test run",
     "deliverability placement-test send",
@@ -300,11 +308,13 @@ export function searchCommandManifest(manifest, query, requestedLimit = DEFAULT_
             description: command.description,
             spends_credits: command.spends_credits,
             mutates: command.mutates,
+            destructive: command.destructive,
             json_supported: command.json_supported,
             hidden: command.hidden,
             score,
         })),
         hydrate: `${manifest.binary} commands get <exact-command> --json`,
+        ...(matches.length ? {} : { next_step: `No command matched. Describe the outcome with ${manifest.binary} capabilities search, or inspect ${manifest.binary} commands --json.` }),
     };
 }
 /** Exact second hop after search; avoids serializing the full command grammar. */
@@ -426,6 +436,7 @@ function toManifestEntry(command, path) {
             && (MUTATING_COMMANDS.has(commandName)
                 || MUTATING_VERBS.has(leafVerb)
                 || MUTATING_VERBS.has(verbPrefix))),
+        destructive: operations.some((spec) => spec.mcp.annotations?.destructiveHint === true),
         preview_by_default: flagStrings.some((flags) => flags.includes("--live")) ||
             PREVIEW_BY_DEFAULT_COMMANDS.has(commandName),
         json_supported: flagStrings.some((flags) => flags.includes("--json")),

package/dist/customer-operation-commands.js

@@ -34,7 +34,7 @@ const GROUP_PURPOSES = {
 const OPERATION_FLAGS = {
     "tables rows remove-selection": {
         table: { help: "Table id or slug." },
-        row_ids: { help: "Comma-separated exact row IDs. Choose this or --selection-json." },
+        row_ids: { help: "Comma-separated exact row IDs. Choose this, --filter-tree-json or --selection-json." },
     },
     "tables favorite": { favorite: { negateHelp: "Unstar the selected Table or folder (favorite: false)." } },
     "tables favorites": { details: { negateHelp: "Return stored star keys without names or links (details: false)." } },
@@ -116,7 +116,11 @@ export function registerCustomerOperationCommands(program, handle) {
             if (spec.binary) {
                 if (spec.binary.stream)
                     return requestOxygen(request.path, { method: request.method, binaryOutputPath: resolve(String(options.output)) });
-                const bytes = await requestOxygen(request.path, { method: request.method, binaryMaxBytes: spec.binary.maxBytes });
+                const download = await requestOxygen(request.path, { method: request.method, binaryMaxBytes: spec.binary.maxBytes, ...(spec.binary.paginated ? { binaryMetadata: true } : {}) });
+                const bytes = download instanceof Uint8Array ? download : download.bytes;
+                const pagination = download instanceof Uint8Array ? undefined : download.pagination;
+                if (spec.binary.paginated && !pagination)
+                    throw new OxygenError("invalid_response", "The export did not include its evidence pagination. Retry the same read.");
                 const output = resolve(String(options.output));
                 try {
                     await writeFile(output, bytes, { flag: "wx" });
@@ -127,7 +131,7 @@ export function registerCustomerOperationCommands(program, handle) {
                     }
                     throw error;
                 }
-                return { path: output, bytes: bytes.byteLength };
+                return { path: output, bytes: bytes.byteLength, ...(pagination ? { pagination } : {}) };
             }
             if (spec.multipart) {
                 let formData;

package/dist/diagnostic-upload-main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/diagnostic-upload-main.js

@@ -0,0 +1,2 @@
+import { uploadCliDiagnostics } from "./diagnostic-uploader.js";
+await uploadCliDiagnostics().catch(() => undefined);

package/dist/diagnostic-uploader.d.ts

@@ -0,0 +1,3 @@
+import { type StoredCredentials } from "./credentials.js";
+/** Dedicated detached process: credential values never enter argv or the spool. */
+export declare function uploadCliDiagnostics(directory?: string, credentials?: StoredCredentials): Promise<number>;

package/dist/diagnostic-uploader.js

@@ -0,0 +1,68 @@
+import { createHash } from "node:crypto";
+import { readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
+import { acquireDiagnosticLock } from "@oxygen/shared/diagnostic-lock";
+import { join } from "node:path";
+import { gunzipSync, gzipSync } from "node:zlib";
+import { DIAGNOSTIC_RECORD_MAX_BYTES, DIAGNOSTIC_UPLOAD_CHUNK_BYTES, parseDiagnosticRecord } from "@oxygen/shared/diagnostics";
+import { loadCredentialsWithEndpoint } from "./credentials.js";
+import { cliDiagnosticDirectory, credentialFingerprint } from "./diagnostics.js";
+import { requestOxygen } from "./http-client.js";
+/** Dedicated detached process: credential values never enter argv or the spool. */
+export async function uploadCliDiagnostics(directory = cliDiagnosticDirectory(), credentials) {
+    if (process.env.OXYGEN_DIAGNOSTICS_ENABLED !== "1")
+        return 0;
+    const loaded = credentials ?? (await loadCredentialsWithEndpoint()).credentials;
+    if (!loaded)
+        return 0;
+    const lockPath = join(directory, ".upload.lock");
+    const release = await acquireDiagnosticLock(lockPath);
+    if (!release)
+        return 0;
+    let uploaded = 0;
+    try {
+        for (const name of (await readdir(directory)).filter((name) => /^[0-9a-f-]+\.json\.gz$/.test(name)).slice(0, 20)) {
+            const path = join(directory, name);
+            try {
+                const entry = JSON.parse(gunzipSync(await readFile(path), { maxOutputLength: DIAGNOSTIC_RECORD_MAX_BYTES }).toString("utf8"));
+                parseDiagnosticRecord(entry.record);
+                if (Date.now() - Date.parse(entry.record.started_at) >= 72 * 60 * 60 * 1000)
+                    continue;
+                // Never move an old invocation to a different endpoint, user or workspace.
+                if (new URL(entry.scope.api_url).origin !== new URL(loaded.apiUrl).origin
+                    || (entry.scope.fingerprint && entry.scope.fingerprint !== credentialFingerprint(loaded)))
+                    continue;
+                const bytes = gzipSync(Buffer.from(JSON.stringify(entry)));
+                const sha256 = createHash("sha256").update(bytes).digest("hex");
+                const total = Math.ceil(bytes.length / DIAGNOSTIC_UPLOAD_CHUNK_BYTES);
+                const selectedOrganization = entry.scope.organization ?? undefined;
+                const progressPath = path + ".upload.json";
+                const progress = JSON.parse(await readFile(progressPath, "utf8").catch(() => "null"));
+                // Staging expires after one day. Restart from zero after that boundary.
+                const next = progress?.sha256 === sha256 && Date.now() - progress.updated_at < 23 * 3_600_000
+                    && Number.isInteger(progress.next) && progress.next >= 0 && progress.next <= total ? progress.next : 0;
+                for (let index = next; index < total; index++) {
+                    await requestOxygen("/api/cli/observability/diagnostics", { method: "POST", credentials: loaded,
+                        ...(selectedOrganization ? { selectedOrganization } : {}), timeoutMs: 15_000,
+                        body: { id: entry.record.id, index, total, sha256,
+                            chunk: bytes.subarray(index * DIAGNOSTIC_UPLOAD_CHUNK_BYTES, (index + 1) * DIAGNOSTIC_UPLOAD_CHUNK_BYTES).toString("base64") },
+                    });
+                    const temporary = progressPath + ".tmp";
+                    await writeFile(temporary, JSON.stringify({ sha256, next: index + 1, updated_at: Date.now() }), { mode: 0o600 });
+                    await rename(temporary, progressPath);
+                }
+                const receipt = await requestOxygen("/api/cli/observability/diagnostics", { method: "POST", credentials: loaded,
+                    ...(selectedOrganization ? { selectedOrganization } : {}), timeoutMs: 15_000, body: { id: entry.record.id, total, sha256, complete: true } });
+                if (receipt.accepted !== true || receipt.complete !== true || receipt.diagnostic_id !== entry.record.id)
+                    continue;
+                await unlink(path);
+                await unlink(progressPath).catch(() => undefined);
+                uploaded++;
+            }
+            catch { /* leave the original for a later invocation; never replay product actions */ }
+        }
+    }
+    finally {
+        await release();
+    }
+    return uploaded;
+}

package/dist/diagnostics.d.ts

@@ -0,0 +1,22 @@
+import { type DiagnosticRecord } from "@oxygen/shared/diagnostics";
+import { type StoredCredentials } from "./credentials.js";
+export type CliDiagnosticScope = {
+    api_url: string;
+    fingerprint: string | null;
+    organization: string | null;
+    user: string | null;
+};
+export type CliDiagnosticSpoolEntry = {
+    scope: CliDiagnosticScope;
+    record: DiagnosticRecord;
+};
+export declare function cliDiagnosticDirectory(): string;
+export declare function credentialFingerprint(credentials: StoredCredentials): string;
+export declare function beginCliDiagnostics(argv?: string[]): void;
+export declare function setCliDiagnosticOperation(command: string): void;
+export declare function cliDiagnosticInvocation(): string | undefined;
+export declare function cliDiagnosticHeaders(): Record<string, string>;
+export declare function recordCliDiagnosticRequest(input: unknown): void;
+export declare function recordCliDiagnosticFailure(error: unknown): void;
+export declare function finishCliDiagnostics(exitCode: number): Promise<string | null>;
+export declare function writeCliDiagnosticSpool(directory: string, entry: CliDiagnosticSpoolEntry): Promise<string | null>;

package/dist/diagnostics.js

@@ -0,0 +1,219 @@
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readdir, readFile, rename, stat, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { acquireDiagnosticLock } from "@oxygen/shared/diagnostic-lock";
+import { StringDecoder } from "node:string_decoder";
+import { gzipSync } from "node:zlib";
+import { createDiagnosticRecord, credentialSafeDiagnostic, diagnosticId, DIAGNOSTIC_INVOCATION_HEADER, DIAGNOSTIC_MAX_BYTES, DIAGNOSTIC_RECORD_MAX_BYTES, diagnosticOutcome, sanitizeDiagnosticArgv, sanitizeDiagnosticContent } from "@oxygen/shared/diagnostics";
+import { OXYGEN_VERSION } from "@oxygen/shared/version";
+import { loadCredentialsWithEndpoint } from "./credentials.js";
+let active;
+export function cliDiagnosticDirectory() {
+    return join(process.env.OXYGEN_CONFIG_DIR?.trim() || (process.platform === "win32"
+        ? join(process.env.APPDATA || join(homedir(), "AppData", "Roaming"), "oxygen")
+        : join(homedir(), ".config", "oxygen")), "diagnostics", "v1");
+}
+export function credentialFingerprint(credentials) {
+    return createHash("sha256").update(credentials.token).digest("hex");
+}
+export function beginCliDiagnostics(argv = process.argv.slice(2)) {
+    if (active || process.env.OXYGEN_DIAGNOSTICS_ENABLED !== "1")
+        return;
+    const invocation = createDiagnosticRecord({ surface: "cli", operation: "cli parse",
+        client_version: OXYGEN_VERSION, input: { argv: sanitizeDiagnosticArgv(argv) },
+        trace_id: randomUUID().replaceAll("-", ""),
+    });
+    invocation.trace_id = invocation.invocation_id.replaceAll("-", "");
+    invocation.traceparent = `00-${invocation.trace_id}-${randomUUID().replaceAll("-", "").slice(0, 16)}-01`;
+    const credentialEnv = diagnosticCredentialEnvironment(argv);
+    const context = { record: invocation, credentialEnv, scope: loadCredentialsWithEndpoint(credentialEnv).catch(() => null),
+        organizationRef: credentialEnv.OXYGEN_ORG?.trim() || null, signalHandlers: [],
+        requests: [], bytes: 0, droppedBytes: 0, stdout: [], stderr: [], restore: () => undefined };
+    active = context;
+    const restorers = [];
+    for (const [stream, output] of [[process.stdout, context.stdout], [process.stderr, context.stderr]]) {
+        const original = stream.write;
+        const decoder = new StringDecoder("utf8");
+        const wrapped = function (...args) {
+            try {
+                const chunk = args[0];
+                const bytes = typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk);
+                if (context.bytes + bytes.length <= DIAGNOSTIC_RECORD_MAX_BYTES) {
+                    context.bytes += bytes.length;
+                    output.push(decoder.write(bytes));
+                }
+                else
+                    context.droppedBytes += bytes.length;
+            }
+            catch {
+                context.droppedBytes++;
+            }
+            return original.apply(stream, args);
+        };
+        stream.write = wrapped;
+        restorers.push(() => { output.push(decoder.end()); stream.write = original; });
+    }
+    context.restore = () => { for (const restore of restorers)
+        restore(); };
+    for (const [signal, code] of [["SIGINT", 130], ["SIGTERM", 143]]) {
+        const handler = () => {
+            recordCliDiagnosticFailure({ code: "interrupted" });
+            void finishCliDiagnostics(code).finally(() => process.exit(code));
+        };
+        process.once(signal, handler);
+        context.signalHandlers.push(() => process.removeListener(signal, handler));
+    }
+}
+export function setCliDiagnosticOperation(command) {
+    if (active)
+        active.record.operation = command.slice(0, 512);
+}
+export function cliDiagnosticInvocation() { return active?.record.invocation_id; }
+export function cliDiagnosticHeaders() {
+    return active ? { [DIAGNOSTIC_INVOCATION_HEADER]: active.record.invocation_id, traceparent: active.record.traceparent } : {};
+}
+export function recordCliDiagnosticRequest(input) {
+    if (!active)
+        return;
+    try {
+        const sanitized = sanitizeDiagnosticContent(input);
+        const size = Buffer.byteLength(JSON.stringify(sanitized));
+        if (active.bytes + size <= DIAGNOSTIC_RECORD_MAX_BYTES) {
+            active.requests.push(sanitized);
+            active.bytes += size;
+        }
+        else
+            active.droppedBytes += size;
+    }
+    catch {
+        active.droppedBytes++;
+    }
+}
+export function recordCliDiagnosticFailure(error) {
+    if (!active)
+        return;
+    const code = error && typeof error === "object" && "code" in error ? String(error.code) : "unexpected_error";
+    active.record.error_code = code;
+    active.record.outcome = diagnosticOutcome(false, null, code);
+    recordCliDiagnosticRequest({ error });
+}
+export async function finishCliDiagnostics(exitCode) {
+    const context = active;
+    if (!context)
+        return null;
+    context.restore();
+    for (const remove of context.signalHandlers)
+        remove();
+    active = undefined;
+    try {
+        const loaded = await context.scope;
+        const credentials = loaded?.credentials;
+        const storedOrganization = credentials?.activeOrganization ?? credentials?.identity?.organization;
+        const organization = !context.organizationRef ? storedOrganization?.id ?? null
+            : context.organizationRef === storedOrganization?.id || context.organizationRef === storedOrganization?.slug
+                ? storedOrganization.id : diagnosticId(context.organizationRef);
+        const user = credentials?.identity?.user.id ?? null;
+        const record = context.record;
+        record.ended_at = new Date().toISOString();
+        if (record.outcome === "pending")
+            record.outcome = exitCode === 0 ? "ok" : "invalid_input";
+        record.status = exitCode;
+        record.organization_id = organization;
+        record.user_id = user;
+        record.capture_state = context.droppedBytes ? "partial" : "complete";
+        record.output = { stdout: context.stdout.join(""), stderr: context.stderr.join("") };
+        record.metadata = { requests: context.requests, dropped_bytes: context.droppedBytes, client_reported: true,
+            original_organization_ref: context.organizationRef };
+        const entry = { scope: { api_url: loaded?.endpoint.apiUrl ?? process.env.OXYGEN_API_URL?.trim() ?? "https://oxygen-agent.com",
+                fingerprint: credentials ? credentialFingerprint(credentials) : null, organization: organization ?? context.organizationRef, user },
+            record: sanitizeDiagnosticContent(credentialSafeDiagnostic(record), [credentials?.token ?? ""]) };
+        const directory = cliDiagnosticDirectory();
+        const path = await writeCliDiagnosticSpool(directory, entry);
+        if (path && process.env.OXYGEN_DIAGNOSTICS_UPLOAD_DISABLED !== "1") {
+            const child = spawn(process.execPath, [fileURLToPath(new URL("./diagnostic-upload-main.js", import.meta.url))], { detached: true, stdio: "ignore", env: context.credentialEnv });
+            child.on("error", () => undefined);
+            child.unref();
+        }
+        return path;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeCliDiagnosticSpool(directory, entry) {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const lockPath = join(directory, ".admission.lock");
+    const release = await acquireDiagnosticLock(lockPath);
+    if (!release)
+        return null;
+    try {
+        let used = 0;
+        let dropped = 0;
+        for (const name of await readdir(directory)) {
+            if (!/^[0-9a-f-]+\.json\.gz$/.test(name) && !/^[0-9a-f-]+\.json\.gz\.[0-9a-f-]+\.tmp$/.test(name))
+                continue;
+            const path = join(directory, name);
+            const info = await stat(path).catch(() => null);
+            if (!info)
+                continue;
+            if (Date.now() - info.mtimeMs >= 72 * 60 * 60 * 1000) {
+                await unlink(path);
+                dropped += info.size;
+            }
+            else
+                used += info.size;
+        }
+        const lossPath = join(directory, "loss.json");
+        const previous = JSON.parse(await readFile(lossPath, "utf8").catch(() => "{\"bytes\":0}"));
+        let bytes = Buffer.from(JSON.stringify({ ...entry, record: sanitizeDiagnosticContent({ ...entry.record,
+                metadata: { ...entry.record.metadata, prior_spool_lost_bytes: previous.bytes + dropped } }) }));
+        if (bytes.length > DIAGNOSTIC_RECORD_MAX_BYTES) {
+            bytes = Buffer.from(JSON.stringify({ ...entry, record: { ...entry.record, input: null, output: null,
+                    capture_state: "partial", metadata: { capture_reason: "oversized_content", dropped_bytes: bytes.length } } }));
+        }
+        const compressed = gzipSync(bytes);
+        if (compressed.length + used > DIAGNOSTIC_MAX_BYTES)
+            dropped += compressed.length;
+        if (dropped) {
+            const loss = await open(lossPath, "w", 0o600);
+            try {
+                await loss.writeFile(JSON.stringify({ bytes: previous.bytes + dropped }));
+                await loss.sync();
+            }
+            finally {
+                await loss.close();
+            }
+        }
+        if (compressed.length + used > DIAGNOSTIC_MAX_BYTES)
+            return null;
+        const path = join(directory, `${entry.record.id}.json.gz`);
+        const temporary = path + `.${randomUUID()}.tmp`;
+        const handle = await open(temporary, "wx", 0o600);
+        try {
+            await handle.writeFile(compressed);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temporary, path);
+        return path;
+    }
+    finally {
+        await release();
+    }
+}
+function diagnosticCredentialEnvironment(argv) {
+    const env = { ...process.env };
+    for (const [flag, name] of [["--profile", "OXYGEN_PROFILE"], ["--org", "OXYGEN_ORG"]]) {
+        const at = argv.indexOf(flag);
+        const equals = argv.find(value => value.startsWith(flag + "="));
+        const value = equals?.slice(flag.length + 1) ?? (at >= 0 ? argv[at + 1] : undefined);
+        if (value && !value.startsWith("-"))
+            env[name] = value;
+    }
+    return env;
+}

package/dist/http-client.d.ts

@@ -1,8 +1,11 @@
+import { type GeoExportPagination } from "@oxygen/shared/geo";
 import { type StoredCredentials } from "./credentials.js";
 import { type CliEndpoint } from "./runtime.js";
 type RequestOptions = {
     /** Internal bounded file download; never follows a caller-supplied URL. */
     binaryMaxBytes?: number;
+    /** Return pagination beside bytes for operations advertising paginated downloads. */
+    binaryMetadata?: boolean;
     /** Stream a native authenticated download to an exclusively created file. */
     binaryOutputPath?: string;
     method?: "GET" | "POST" | "PATCH" | "DELETE";
@@ -25,6 +28,10 @@ type RequestOptions = {
 };
 export declare function requestOxygen<T>(// skipcq: JS-R1005
 path: string, options?: RequestOptions): Promise<T>;
+export type PaginatedFileDownload = {
+    bytes: Uint8Array;
+    pagination?: GeoExportPagination;
+};
 export declare function ensureFreshCliForApiUrl(apiUrl: string, options?: {
     fetch?: typeof fetch;
     endpoint?: CliEndpoint;

package/dist/http-client.js

@@ -1,5 +1,7 @@
+import { readGeoExportPagination } from "@oxygen/shared/geo";
 import { OXYGEN_VERSION, OxygenError, isCliResult, isVersionGreater, parseSemver, readEnvelopeCompatibility, vercelProtectionBypassHeaders, withRetryAfterDetails, } from "@oxygen/shared";
 import { randomUUID } from "node:crypto";
+import { cliDiagnosticHeaders, cliDiagnosticInvocation, recordCliDiagnosticRequest } from "./diagnostics.js";
 import { open, unlink } from "node:fs/promises";
 import { recordMutatingRequestAnswered, recoverFromCliFloorRejection } from "./auto-update.js";
 import { defaultApiUrl, loadCredentialsWithEndpoint } from "./credentials.js";
@@ -49,8 +51,9 @@ path, options = {}) {
         }
     }
     options.signal?.throwIfAborted();
-    const traceId = options.traceId ?? randomUUID();
+    const traceId = options.traceId ?? cliDiagnosticInvocation() ?? randomUUID();
     const headers = {
+        ...cliDiagnosticHeaders(),
         Accept: "application/json",
         "X-Oxygen-Trace-Id": traceId,
         // Advertise the CLI version so the server can enforce its minimum-CLI floor
@@ -104,15 +107,19 @@ path, options = {}) {
     else if (timeout.signal)
         requestInit.signal = timeout.signal;
     try {
+        recordCliDiagnosticRequest({ event: "request", trace_id: traceId, api_url: apiUrl, path, method,
+            input: options.body ?? (options.formData ? { withheld: "multipart_binary" } : null) });
         response = await fetchImpl(`${apiUrl}${path}`, requestInit);
         if (response.ok && options.binaryOutputPath !== undefined) {
             return await streamBinaryResponse(response, options.binaryOutputPath);
         }
         if (response.ok && options.binaryMaxBytes !== undefined) {
-            return await readBoundedBinaryResponse(response, options.binaryMaxBytes);
+            const bytes = await readBoundedBinaryResponse(response, options.binaryMaxBytes);
+            return (options.binaryMetadata ? { bytes, pagination: readGeoExportPagination(response.headers) } : bytes);
         }
     }
     catch (error) {
+        recordCliDiagnosticRequest({ event: "transport_failure", trace_id: traceId, error });
         if (error instanceof OxygenError)
             throw error;
         if (timeout.timedOut() || (timeoutMs !== undefined && isAbortError(error))) {
@@ -163,6 +170,7 @@ path, options = {}) {
         });
     });
     const compatibility = readEnvelopeCompatibility(envelope);
+    recordCliDiagnosticRequest({ event: "response", trace_id: traceId, status: response.status, output: envelope });
     const failed = !response.ok || !envelope.ok;
     try {
         assertCliMeetsMinimumApiVersion(compatibility, options, endpoint);
@@ -452,6 +460,7 @@ async function readEnvelope(response) {
         parsed = text ? JSON.parse(text) : null;
     }
     catch {
+        recordCliDiagnosticRequest({ event: "invalid_response", status: response.status, output: text });
         throw new OxygenError("invalid_response", "Oxygen API returned a non-JSON response.", {
             details: {
                 status: response.status,
@@ -462,6 +471,7 @@ async function readEnvelope(response) {
     }
     if (isCliResult(parsed))
         return parsed;
+    recordCliDiagnosticRequest({ event: "invalid_response", status: response.status, output: parsed });
     throw new OxygenError("invalid_response", "Oxygen API returned an invalid response envelope.", {
         details: { status: response.status },
         exitCode: 1,