@oxygen-agent/cli 1.1012.2 → 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.1012.2
+Version: 1.1013.15

package/dist/customer-operation-commands.js

@@ -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,

package/dist/index.js

@@ -13,6 +13,7 @@ import { registerCrmFileReadCommands } from "./crm-file-read-commands.js";
 import { registerCrmSupportFlags, readCrmNoteEditFields, readCrmPhotoFields, readCrmFileLabel, buildCrmObjectsPath, buildCrmConnectionsPath, buildCrmRecordPath } from "./crm-support-flags.js";
 import { registerCustomerOperationCommands } from "./customer-operation-commands.js";
 import { DATABASE_QUERY_FLAG_OVERLAY } from "./database-query-flags.js";
+import { beginCliDiagnostics, finishCliDiagnostics, setCliDiagnosticOperation, recordCliDiagnosticFailure } from "./diagnostics.js";
 import { addFeedReadFlags, feedReadWindowParams } from "./feed-read-flags.js";
 import { registerFunctionsCommands } from "./functions-commands.js";
 import { applyOxygenHelp, argvRequestsJson, commanderUsageFailure, commandNameForArgv, enableCommandSuggestions, unknownCommandHint, unknownOptionHint, withoutHelpForUnknownCommand, validateRequiredOptionValues, } from "./help.js";
@@ -961,6 +962,7 @@ function writeManagedProviderAvailabilityNotice(data) {
 // process exit code from the error. Command handlers that don't route through
 // handleAsyncAction catch straight into this so the shape can't drift.
 function emitCliFailure(command, error) {
+    recordCliDiagnosticFailure(error);
     writeJson(toFailure(command, error));
     writeMaxCreditsHint(error);
     process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
@@ -30337,20 +30339,27 @@ function muteTokenEcho() {
 // head -c 20`) otherwise crashes with a raw EPIPE stack after the consumer
 // closes the pipe; a closed pipe is normal shell behavior, not an error.
 process.stdout.on("error", (error) => {
-    if (error.code === "EPIPE")
-        process.exit(0);
+    if (error.code === "EPIPE") {
+        void finishCliDiagnostics(0).finally(() => process.exit(0));
+        return;
+    }
     process.stderr.write(`stdout error: ${error.message}\n`);
-    process.exit(1);
+    recordCliDiagnosticFailure(error);
+    void finishCliDiagnostics(1).finally(() => process.exit(1));
 });
+beginCliDiagnostics();
 maybeScheduleBackgroundUpdate();
 const program = createProgram();
 installCommanderExitOverride(program);
 const argv = withoutHelpForUnknownCommand(program, process.argv);
+setCliDiagnosticOperation(commandNameForArgv(program, argv.slice(2)));
 try {
     await program.parseAsync(argv);
 }
 catch (error) {
     if (error instanceof CommanderError) {
+        if (error.exitCode !== 0)
+            recordCliDiagnosticFailure(error);
         const cliArgs = argv.slice(2);
         // Every hint goes to stderr as it always has; the first, the most specific,
         // also becomes the --json envelope's details.next_step below.
@@ -30417,6 +30426,8 @@ catch (error) {
         emitCliFailure(commandNameForArgv(program, argv.slice(2)), error);
     }
     else {
+        recordCliDiagnosticFailure(error);
+        await finishCliDiagnostics(1);
         throw error;
     }
 }
@@ -30424,6 +30435,7 @@ catch (error) {
 // pipe, wait for the queued write callback before Node exits or the tail of
 // `oxygen --help` can be truncated at the pipe high-water mark.
 await Promise.all([flushWritable(process.stdout), flushWritable(process.stderr)]);
+await finishCliDiagnostics(Number(process.exitCode ?? 0));
 function flushWritable(stream) {
     return new Promise((resolve) => stream.write("", () => resolve()));
 }

package/node_modules/@oxygen/shared/dist/capability-discovery.js

@@ -9,10 +9,10 @@ export const OXYGEN_CAPABILITY_ROUTES = [
         owns: "GEO / AEO AI-search tracking: buyer prompts, consumer answers, citations, competitive visibility, customer chat evidence and optimization experiments. Experimental staff/dev access.",
         notFor: "Direct model API benchmarks, automatic public edits, autonomous publishing or personalized chat attribution.",
         execution: "Staff in dev workspaces only. Preview consumer collection and cost, start within the $10 shared pilot cap, inspect answers and citations, then record reviewed changes and compare later samples. Reads never collect or spend.",
-        gatewayTools: ["oxygen_geo_projects_list", "oxygen_geo_engines_list", "oxygen_geo_runs_preview"],
-        gatewayCommands: ["geo projects list", "geo engines list", "geo runs preview"],
+        gatewayTools: ["oxygen_geo_projects_list", "oxygen_geo_engines_list", "oxygen_geo_analytics_get", "oxygen_geo_runs_preview"],
+        gatewayCommands: ["geo projects list", "geo engines list", "geo analytics get", "geo runs preview"],
         endpointSections: ["geo"], skills: ["oxygen-geo"],
-        intentTerms: ["GEO", "AEO", "answer engine optimization", "generative engine optimization", "AI search visibility", "AI visibility", "consumer AI answers", "answer engines", "brand visibility", "brand citations", "chatgpt mentions", "citation gaps"],
+        intentTerms: ["GEO", "AEO", "answer engine optimization", "generative engine optimization", "AI search visibility", "AI answer visibility", "AI visibility", "consumer AI answers", "answer engines", "brand visibility", "brand citations", "chatgpt mentions", "citation gaps"],
     },
     {
         id: "visual-rendering",
@@ -1791,7 +1791,7 @@ function isSpintaxIntent(query) {
 }
 function explicitCapabilityIntent(query) {
     // Importing an AI answer is GEO evidence, rather than a Table file import.
-    if (/\b(?:geo|aeo|ai (?:search )?visibility|consumer ai answers?|answer engine optimization|generative engine optimization)\b/.test(query))
+    if (/\b(?:geo|aeo|ai (?:(?:search|answer) )?visibility|consumer ai answers?|answer engine optimization|generative engine optimization)\b/.test(query))
         return ROUTE_BY_ID.get("geo") ?? null;
     if (isConnectionPriceIntent(query))
         return ROUTE_BY_ID.get("billing-and-budgets") ?? null;

package/node_modules/@oxygen/shared/dist/contracts/browser-operations.js

@@ -120,5 +120,5 @@ export const BROWSER_OPERATIONS = [
     operation("notetaker.calendar.schedule", "/api/cli/notetaker/calendar", "POST", "notetaker calendar schedule", "oxygen_notetaker_calendar_schedule", "crm", "Schedule recording for an existing calendar event after approval; an external CLI or MCP caller must supply an explicit max_credits ceiling.", { event_id: text(), approved: bool(), max_credits: num({ minimum: 0 }) }, ["event_id", "approved"], { defaults: { action: "schedule" }, spends: true }),
     operation("notetaker.note.edit", "/api/cli/notetaker/sessions/{session}/note", "PATCH", "notetaker notes edit", "oxygen_notetaker_note_edit", "crm", "Save the markdown note for one meeting session and return the committed note.", { markdown: text() }, ["markdown"]),
     operation("orgs.create", "/api/cli/orgs/create", "POST", "orgs create", "oxygen_workspace_create", "workspace", "Create a workspace for the authenticated person's account and begin native company setup. Workspace API keys cannot create personal workspaces.", { name: text(), company_domain: text("Company website or domain, or its LinkedIn company page URL when it has no website."), linkedin_profile_url: text("Creator's LinkedIn profile URL, separate from the company's page.") }, ["name", "company_domain"]),
-    operation("onboarding.complete", "/api/cli/onboarding/complete", "POST", "onboarding complete", "oxygen_onboarding_complete", "workspace", "Complete the active workspace's onboarding step and record its discovery-source choices. The other choice requires source_other.", { sources: arr(enumOf(["linkedin_content", "linkedin_dm", "linkedin_ads", "youtube", "google", "email", "word_of_mouth", "referral", "event", "other"])), source_other: text(), redirect_url: text() }, ["sources"]),
+    operation("onboarding.complete", "/api/cli/onboarding/complete", "POST", "onboarding complete", "oxygen_onboarding_complete", "workspace", "Complete the active workspace's onboarding step and record its discovery-source choices. The other choice requires source_other.", { sources: arr(enumOf(["linkedin_content", "linkedin_dm", "linkedin_ads", "x", "youtube", "google", "email", "word_of_mouth", "referral", "event", "other"])), source_other: text(), redirect_url: text() }, ["sources"]),
 ];

package/node_modules/@oxygen/shared/dist/contracts/geo.js

@@ -1,7 +1,10 @@
 import { arr, bool, enumOf, int, obj, str, } from "./schema.js";
 import { GEO_ENGINES } from "../geo.js";
 const text = (maxLength = 1000) => str({ maxLength });
-const strings = () => arr(text(), { maxItems: 100 });
+const strings = () => arr(text(), {
+    maxItems: 100,
+    description: "List of strings. CLI: comma-separated values; MCP: a JSON array.",
+});
 const engine = enumOf(GEO_ENGINES);
 const market = obj({
     country: str({ minLength: 2, maxLength: 2 }),
@@ -10,10 +13,22 @@ const market = obj({
 const project = {
     name: str({ minLength: 1, maxLength: 120 }),
     aliases: strings(),
-    domains: arr(text(), { minItems: 1, maxItems: 100 }),
+    domains: arr(text(), {
+        minItems: 1,
+        maxItems: 100,
+        description: "Owned public domains. CLI: comma-separated values; MCP: a JSON array.",
+    }),
     icp: text(5000),
-    engines: arr(engine, { minItems: 1, maxItems: 7 }),
-    markets: arr(market, { minItems: 1, maxItems: 10 }),
+    engines: arr(engine, {
+        minItems: 1,
+        maxItems: 7,
+        description: "Engine names. CLI: comma-separated values; MCP: a JSON array. Omit to select ready collectors, or Claude import-only if none are ready.",
+    }),
+    markets: arr(market, {
+        minItems: 1,
+        maxItems: 10,
+        description: 'JSON array of country/language pairs, e.g. [{"country":"US","language":"en"}].',
+    }),
     repetitions: int({ minimum: 1, maximum: 5 }),
     archived: bool(),
 };
@@ -61,7 +76,7 @@ function operation(id, suffix, method, command, summary, fields = {}, required =
 }
 export const GEO_OPERATIONS = [
     operation("projects.list", "/projects", "GET", "projects list", "List GEO / AEO AI-search tracking projects."),
-    operation("projects.create", "/projects", "POST", "projects create", "Create a GEO / AEO brand tracking project.", project, ["name", "domains"]),
+    operation("projects.create", "/projects", "POST", "projects create", "Create a GEO / AEO brand tracking project, private to the selected workspace and its authorized staff in dev. This never publishes data.", project, ["name", "domains"]),
     operation("projects.get", "/projects/{project_id}", "GET", "projects get", "Read a GEO / AEO project and its tracking settings."),
     operation("projects.update", "/projects/{project_id}", "PATCH", "projects update", "Change brand aliases, ICP, markets or tracking settings.", project),
     operation("context.get", "/context", "GET", "context get", "Read editable brand, ICP and offering context from workspace Knowledge."),
@@ -83,6 +98,7 @@ export const GEO_OPERATIONS = [
     operation("runs.list", "/projects/{project_id}/runs", "GET", "runs list", "List tracking runs with completion and costs."),
     operation("runs.get", "/projects/{project_id}/runs/{run_id}", "GET", "runs get", "Inspect a tracking run, provider tasks, costs, failures and retries."),
     operation("runs.retry", "/projects/{project_id}/runs/{run_id}/retry", "POST", "runs retry", "Resume failed reads of saved provider tasks without a new paid submission."),
+    operation("runs.reconcile", "/projects/{project_id}/runs/{run_id}/reconcile", "POST", "runs reconcile", "Reconcile uncertain submissions using a matching saved no-job supplier receipt. No new collection or paid submission."),
     operation("runs.cancel", "/projects/{project_id}/runs/{run_id}/cancel", "POST", "runs cancel", "Stop unsubmitted samples; submitted collection retains its spend reservation."),
     operation("schedules.set", "/projects/{project_id}/schedule", "PATCH", "schedule set", "Pause or configure daily/weekly GEO tracking within a reviewed cost ceiling.", {
         cadence: enumOf(["paused", "daily", "weekly"]),
@@ -92,10 +108,16 @@ export const GEO_OPERATIONS = [
     operation("answers.get", "/projects/{project_id}/answers/{document_id}", "GET", "answers get", "Read the immutable original answer and full provider payload."),
     operation("answers.import", "/projects/{project_id}/answers", "POST", "answers import", "Import a manually observed consumer answer, separate from controlled tracker metrics.", {
         engine,
+        prompt_id: str({
+            description: "Optional tracked question ID. The prompt text must match its current revision; the import stays outside controlled measurements.",
+        }),
         prompt: text(500),
         text: text(100000),
         urls: strings(),
-        captured_at: text(40),
+        captured_at: str({
+            maxLength: 40,
+            description: "ISO 8601 capture timestamp, e.g. 2026-10-09T00:00:00Z. Omit to record the import time.",
+        }),
     }, ["engine", "prompt", "text"]),
     operation("analytics.get", "/projects/{project_id}/analytics", "GET", "analytics get", "Read AI visibility, citations, share of voice and trends with sample denominators.", filters),
     operation("sources.list", "/projects/{project_id}/sources", "GET", "sources list", "Find domains and pages cited by AI, including competitive citation gaps.", filters),
@@ -132,7 +154,7 @@ export const GEO_OPERATIONS = [
         notes: text(10000),
     }),
     {
-        ...operation("exports.get", "/projects/{project_id}/export", "GET", "export", "Download GEO evidence, metrics or an internal PDF report.", { format: enumOf(["json", "csv", "pdf"]), ...filters }),
-        binary: { maxBytes: 20_000_000 },
+        ...operation("exports.get", "/projects/{project_id}/export", "GET", "export", "Download a bounded page of GEO evidence or a PDF report. Follow next_cursor in the result with --cursor; metrics describe all filtered answers.", { format: enumOf(["json", "csv", "pdf"]), ...filters }),
+        binary: { maxBytes: 20_000_000, paginated: true },
     },
 ];

package/node_modules/@oxygen/shared/dist/contracts/operations.d.ts

@@ -32,6 +32,7 @@ export type OperationSpec<C extends ContractObject = ContractObject> = {
     binary?: {
         maxBytes: number;
         stream?: never;
+        paginated?: true;
     } | {
         stream: true;
         resourceParameter: string;

package/node_modules/@oxygen/shared/dist/diagnostic-context.d.ts

@@ -0,0 +1,3 @@
+export declare function enterDiagnosticInvocation(value: unknown): void;
+export declare function withDiagnosticInvocation<T>(value: string, task: () => T): T;
+export declare function activeDiagnosticInvocation(): string | undefined;