@oxygen-agent/cli 1.1012.2 → 1.1013.27

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.27

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;
@@ -11926,7 +11928,7 @@ Examples:
         .command("admin")
         .description("Staff-only commands.")
         .addCommand(new Command("kpis")
-        .description("Show the company conversion funnel (visitors → signups → agent connected → CLI/MCP activation → paid, with step rates), self-reported signup-channel attribution, new and positive-paid MRR/ARR, and paid churn separated from trial loss. OXYGEN staff only; workspace admin role alone does not grant access.")
+        .description("Show the company conversion funnel (visitors → signups → activation on any surface, web, CLI or MCP → paid, with step rates and agent connected beside it), self-reported signup-channel attribution, new and positive-paid MRR/ARR, and paid churn separated from trial loss. OXYGEN staff only; workspace admin role alone does not grant access.")
         .addOption(new Option("--range <range>", "Range for acquisition, the funnel's signup cohort, new revenue, and churn; current MRR/ARR and scheduled cancellations remain point-in-time.")
         .choices(["7d", "30d", "90d"])
         .default("30d"))
@@ -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/cli-ugc/dist/commands.js

@@ -318,7 +318,13 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
                 {
                     name: "knowledge_slugs",
                     kind: "array",
-                    description: "Selected live master wiki slugs shared with creators; empty array clears sharing.",
+                    description: "Knowledge file slugs, skills included, shared live with creators and loaded into their AI context (up to 30); empty array clears sharing.",
+                    required: false,
+                },
+                {
+                    name: "knowledge_folder_ids",
+                    kind: "array",
+                    description: "Knowledge folder ids (from knowledge folders list) shared live with creators, skill folders included: files added to them later reach existing creators too (up to 10); empty array clears.",
                     required: false,
                 },
                 {
@@ -373,7 +379,13 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
                 {
                     name: "knowledge_slugs",
                     kind: "array",
-                    description: "Selected live master wiki slugs shared with creators; empty array clears sharing.",
+                    description: "Knowledge file slugs, skills included, shared live with creators and loaded into their AI context (up to 30); empty array clears sharing.",
+                    required: false,
+                },
+                {
+                    name: "knowledge_folder_ids",
+                    kind: "array",
+                    description: "Knowledge folder ids (from knowledge folders list) shared live with creators, skill folders included: files added to them later reach existing creators too (up to 10); empty array clears.",
                     required: false,
                 },
                 {

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/column-operation.d.ts

@@ -0,0 +1,5 @@
+/** A named column operation constrains execution; it never grants authority. */
+export declare const COLUMN_OPERATION_HEADER = "X-Oxygen-Column-Operation";
+export declare const COLUMN_OPERATIONS: readonly ["ai", "research", "formula", "enrichment", "bind", "lookup"];
+export type ColumnOperation = typeof COLUMN_OPERATIONS[number];
+export declare function isColumnOperation(value: unknown): value is ColumnOperation;

package/node_modules/@oxygen/shared/dist/column-operation.js

@@ -0,0 +1,6 @@
+/** A named column operation constrains execution; it never grants authority. */
+export const COLUMN_OPERATION_HEADER = "X-Oxygen-Column-Operation";
+export const COLUMN_OPERATIONS = ["ai", "research", "formula", "enrichment", "bind", "lookup"];
+export function isColumnOperation(value) {
+    return typeof value === "string" && COLUMN_OPERATIONS.includes(value);
+}

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/customer-operations.js

@@ -27,6 +27,7 @@ const mcpOnly = { generated: { cli: false, mcp: true } };
 const cliOnly = { generated: { cli: true, mcp: false } };
 export const CUSTOMER_OPERATIONS = [
     operation("activation.state", "/api/cli/activation/state", "GET", "activation state", "oxygen_activation_state", "workspace", "Read this workspace's onboarding activation state and next available actions.", {}, [], mcpOnly),
+    operation("activation.checklist", "/api/cli/activation/checklist", "GET", "activation checklist", "oxygen_activation_checklist", "workspace", "Read this workspace's getting-started checklist: leads in a table, a first sequence, a connected sending account and a launched sequence, each with whether it is done and a link to do it; eligible says whether the sidebar shows it. Read-only, 0 credits."),
     operation("api_keys.list", "/api/cli/api-keys", "GET", "api-keys list", "oxygen_api_keys_list", "workspace", "List workspace API keys without revealing their tokens.", {}, [], mcpOnly),
     operation("api_keys.create", "/api/cli/api-keys", "POST", "api-keys create", "oxygen_api_keys_create", "workspace", "Create a workspace API key; requires the caller's personal user session. The token is returned once.", { name: text(), expires_at: text("ISO timestamp; omit for no expiry.") }, [], mcpOnly),
     operation("api_keys.revoke", "/api/cli/api-keys/{key_id}", "DELETE", "api-keys revoke", "oxygen_api_keys_revoke", "workspace", "Revoke a workspace API key; requires the caller's personal user session.", {}, [], mcpOnly),