@oxygen-agent/cli 1.1011.974 → 1.1012.2

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.974
+Version: 1.1012.2

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

@@ -104,10 +104,23 @@ const MUTATING_VERBS = new Set([
 // status persists state and can pause the provider; reconnect replaces its
 // connection and can restart provider history. Other status commands are reads.
 const MUTATING_COMMANDS = new Set([
+    // These balance reads can post an eligible due grant or expire due sponsored
+    // 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",
     "mailboxes warmup reconnect",
+    // Approval creates a provider consent link; status can attach its receipt.
+    "mailboxes warmup google",
     // Immediately moves a provider proxy and may pause or resume the sender.
     "senders proxy-country",
     // A noun leaf with its own action (not a group), so the default would
@@ -134,6 +147,10 @@ const MUTATING_COMMANDS = new Set([
 // mode, but a small number of approved operations are explicitly
 // zero-credit. Keep those exceptions exact so discovery never invents spend.
 const ZERO_CREDIT_APPROVAL_COMMANDS = new Set([
+    // The compatibility --approved flag never bypasses canonical proposal review.
+    // Wiki revisions and canonical pin changes are free (Knowledge audit, 2026-10-06).
+    "knowledge page upsert",
+    "knowledge page pin",
     "inbox delete-message",
     "inbox forget-whatsapp-chat",
     "tables watcher preview",
@@ -168,12 +185,18 @@ const ZERO_CREDIT_APPROVAL_COMMANDS = new Set([
     // progress are covered by the existing monthly mailbox commitment.
     "mailboxes connect-oauth",
     "mailboxes sync",
+    // Separate Google consent always has a zero-credit ceiling; enrollment bills
+    // through its own warmup enable command.
+    "mailboxes warmup google",
     // Previews without --approved; with it, removes a program no creator ever
     // joined. No provider call, no credits.
     "ugc programs delete",
     // This approval only reopens exact fingerprint-bound tenant rows. It never
     // calls the provider, dispatches an action, or touches the credit ledger.
     "sequences recover-capacity",
+    // Provider reads are free; approval only records an exact match locally.
+    // Neither branch resends or writes to the provider.
+    "sequences reconcile",
     // Credential replacement is destructive but does not execute the graph,
     // call a provider, or spend Oxygen credits.
     "workflows webhooks rotate",
@@ -199,6 +222,8 @@ 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",
     "managed-inboxes recover",
@@ -233,6 +258,7 @@ const PREVIEW_BY_DEFAULT_COMMANDS = new Set([
     // No action reads progress; an action previews until --approved.
     "mailboxes sync",
     "sequences recover-capacity",
+    "sequences reconcile",
     "support admin done",
     "support admin reply",
     // A bare call reads the Plain workspace and prints the plan; --apply writes.
@@ -282,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. */
@@ -408,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/crm-support-flags.d.ts

@@ -8,4 +8,5 @@ export declare function readCrmPhotoFields(options: {
 }): Record<string, unknown>;
 export declare function readCrmFileLabel(options: object): Record<string, unknown>;
 export declare function buildCrmObjectsPath(options: object): string;
+export declare function buildCrmRecordPath(object: string, rowId: string, options: object): string;
 export declare function buildCrmConnectionsPath(object: string, rowId: string, options: object): string;

package/dist/crm-support-flags.js

@@ -1,5 +1,5 @@
 import { OxygenError } from "@oxygen/shared/cli-result";
-import { CRM_CONNECTIONS_QUERY_CONTRACT, CRM_NOTE_EDIT_CONTRACT, CRM_OBJECTS_QUERY_CONTRACT, CRM_PHOTOS_CONTRACT, CRM_FILE_COMPLETE_CONTRACT } from "@oxygen/shared/contracts/crm-support";
+import { CRM_CONNECTIONS_QUERY_CONTRACT, CRM_NOTE_EDIT_CONTRACT, CRM_OBJECTS_QUERY_CONTRACT, CRM_PHOTOS_CONTRACT, CRM_FILE_COMPLETE_CONTRACT, CRM_RECORD_QUERY_CONTRACT } from "@oxygen/shared/contracts/crm-support";
 import { validateContract } from "@oxygen/shared/contracts/schema";
 import { addContractFlags, readContractFlags } from "./contract-flags.js";
 import { assertModeFlagsExclusive } from "./cli-values.js";
@@ -19,6 +19,7 @@ function replaceFlags(command, attributes, contract, overlay) {
 export function registerCrmSupportFlags(program) {
     const crm = child(program, "crm");
     replaceFlags(child(crm, "objects"), [], CRM_OBJECTS_QUERY_CONTRACT);
+    replaceFlags(child(crm, "get"), [], CRM_RECORD_QUERY_CONTRACT);
     replaceFlags(child(crm, "connections"), ["conversationLimit", "sequenceLimit"], CRM_CONNECTIONS_QUERY_CONTRACT);
     replaceFlags(child(child(crm, "notes"), "update"), ["body", "title", "pin", "unpin"], CRM_NOTE_EDIT_CONTRACT, NOTE_OVERLAY);
     replaceFlags(child(crm, "photos"), ["limit", "live"], CRM_PHOTOS_CONTRACT);
@@ -55,6 +56,9 @@ function queryPath(path, query) {
     return params.size ? `${path}?${params}` : path;
 }
 export function buildCrmObjectsPath(options) { return queryPath("/api/cli/crm/objects", checkedFlags(options, CRM_OBJECTS_QUERY_CONTRACT)); }
+export function buildCrmRecordPath(object, rowId, options) {
+    return queryPath(`/api/cli/crm/objects/${encodeURIComponent(object)}/records/${encodeURIComponent(rowId)}`, checkedFlags(options, CRM_RECORD_QUERY_CONTRACT));
+}
 export function buildCrmConnectionsPath(object, rowId, options) {
     return queryPath(`/api/cli/crm/objects/${encodeURIComponent(object)}/records/${encodeURIComponent(rowId)}/connections`, checkedFlags(options, CRM_CONNECTIONS_QUERY_CONTRACT));
 }

package/dist/customer-operation-commands.js

@@ -32,6 +32,10 @@ const GROUP_PURPOSES = {
     onboarding: "Save workspace discovery choices and continue onboarding.",
 };
 const OPERATION_FLAGS = {
+    "tables rows remove-selection": {
+        table: { help: "Table id or slug." },
+        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)." } },
 };
@@ -92,7 +96,7 @@ export function registerCustomerOperationCommands(program, handle) {
         command.action((options, selected) => handle(spec.cli.path.join(" "), { ...options, json: selected.optsWithGlobals().json === true }, async () => {
             let input;
             try {
-                input = readContractFlags(options, contract, overlay);
+                input = readContractFlags(ancestorConsumedOptions(command, selected, options), contract, overlay);
                 if (spec.multipart && options.file !== undefined) {
                     if (input[spec.multipart.contentField] !== undefined)
                         throw new OxygenError("invalid_request", "Choose --file or the base64 content flag, not both.", { exitCode: 2 });
@@ -139,6 +143,31 @@ export function registerCustomerOperationCommands(program, handle) {
         }));
     }
 }
+/**
+ * Commander lets an ancestor that declares the same flag consume it, so a value
+ * the user typed for this leaf lands on the parent and the leaf reads nothing:
+ * `sequences contacts rows --limit 1` sent no limit at all, because the native
+ * `sequences contacts` list owns `--limit` too, and the server returned its
+ * default page (OXP-1.11.67). Take such a value back only when the user typed it
+ * (value source `cli`); an ancestor's own default never becomes this leaf's input.
+ */
+function ancestorConsumedOptions(leaf, selected, options) {
+    const merged = { ...options };
+    for (const option of leaf.options) {
+        const key = option.attributeName();
+        if (merged[key] !== undefined)
+            continue;
+        for (let ancestor = selected.parent; ancestor; ancestor = ancestor.parent) {
+            const owned = ancestor.options.find((candidate) => candidate.long === option.long);
+            if (!owned)
+                continue;
+            if (ancestor.getOptionValueSource(owned.attributeName()) === "cli")
+                merged[key] = ancestor.opts()[owned.attributeName()];
+            break;
+        }
+    }
+    return merged;
+}
 function uploadContentType(filePath) {
     const types = {
         ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".svg": "image/svg+xml",

package/dist/help.js

@@ -141,6 +141,7 @@ export function applyOxygenHelp(program, binaryName) {
         "",
         "Agent quickstart:",
         `  1. ${binaryName} login                      connect this terminal (or set OXYGEN_API_KEY)`,
+        `     ${binaryName} whoami --summary-json     confirm the active workspace and identity (0 credits)`,
         // `login` auto-installs the skills, but an agent authenticating with
         // OXYGEN_API_KEY never runs it — without this step nothing on any
         // first-touch surface names the skill that teaches the GTM loops.
@@ -163,8 +164,9 @@ export function applyOxygenHelp(program, binaryName) {
         "Conventions:",
         "  --json prints a stable envelope {ok, data|error, meta}; errors always print it.",
         "  Free Sequence launch previews omit --approved and --max-credits.",
-        "  Credit-spending commands require --approved --max-credits <n>; zero-credit",
-        "  external writes require --approved plus the command's preview-bound plan token.",
+        "  Credit-spending commands require --approved --max-credits <n>.",
+        "  Zero-credit external writes require --approved; supply a preview-bound plan",
+        "  token when the command requires one (see its preview and --help).",
         "  State-changing responses include a web_url deep-link to inspect the result.",
     ].join("\n"));
     program.addHelpText("afterAll", `\nExit codes: ${exitCodeLine}`);
@@ -360,6 +362,12 @@ export function unknownCommandHint(program, argv) {
     const { command, path, next } = resolveCommandPath(program, argv);
     if (next === undefined || command.commands.length === 0)
         return null;
+    const identityExists = program.commands.some((candidate) => candidate.name() === "whoami");
+    const currentWorkspace = (command.parent === program && command.name() === "workspace" && next === "current")
+        || (command === program && next === "workspaces" && argv.some((token, index) => token === "workspaces" && argv[index + 1] === "current"));
+    if (identityExists && currentWorkspace) {
+        return `Hint: Active workspace and identity: \`${program.name()} whoami --summary-json\` (read-only, 0 credits).`;
+    }
     return buildUnknownCommandHint(command, path, next);
 }
 /**

package/dist/http-client.d.ts

@@ -6,6 +6,10 @@ type RequestOptions = {
     /** Stream a native authenticated download to an exclusively created file. */
     binaryOutputPath?: string;
     method?: "GET" | "POST" | "PATCH" | "DELETE";
+    /** A native read that uses POST for its selection payload. Never set on a write. */
+    readOnly?: boolean;
+    /** Only for audited preview routes that request no product mutation. */
+    previewOnly?: boolean;
     body?: Record<string, unknown>;
     formData?: FormData;
     credentials?: StoredCredentials;

package/dist/http-client.js

@@ -11,6 +11,7 @@ const CLI_COMPATIBILITY_CHECK_TIMEOUT_MS = 5_000;
 // Replay on the Idempotency-Key is per route (most routes ignore the header),
 // so this must not promise that a same-key retry is safe.
 const UNCONFIRMED_WRITE_NEXT_STEP = "This change may already have been applied. Check the current state (for example with the matching list or get command) before you retry.";
+const FAILED_READ_NEXT_STEP = "This read failed. Check your connection; it is safe to retry the same read.";
 const cliCompatibilityCheckKeys = new Set();
 export async function requestOxygen(// skipcq: JS-R1005
 path, options = {}) {
@@ -75,7 +76,13 @@ path, options = {}) {
     // echoed in error details so a re-run (OXYGEN_IDEMPOTENCY_KEY=<key>) can
     // retry without duplicating the write once the route supports replay.
     const method = options.method ?? "GET";
-    const idempotencyKey = method === "GET"
+    const readOnly = method === "GET" || options.readOnly === true;
+    const recovery = {
+        next_step: options.previewOnly
+            ? "This was a preview; no changes were requested. Retry the preview when Oxygen is reachable."
+            : readOnly ? FAILED_READ_NEXT_STEP : UNCONFIRMED_WRITE_NEXT_STEP,
+    };
+    const idempotencyKey = readOnly
         ? undefined
         : options.idempotencyKey ?? process.env.OXYGEN_IDEMPOTENCY_KEY ?? randomUUID();
     if (idempotencyKey) {
@@ -108,7 +115,6 @@ path, options = {}) {
     catch (error) {
         if (error instanceof OxygenError)
             throw error;
-        const unconfirmedWrite = method === "GET" ? {} : { next_step: UNCONFIRMED_WRITE_NEXT_STEP };
         if (timeout.timedOut() || (timeoutMs !== undefined && isAbortError(error))) {
             throw new OxygenError("network_timeout", "Oxygen API request timed out.", {
                 details: {
@@ -117,9 +123,9 @@ path, options = {}) {
                     timeout_ms: timeoutMs,
                     trace_id: traceId,
                     ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}),
-                    ...unconfirmedWrite,
+                    ...recovery,
                 },
-                exitCode: 1,
+                exitCode: 8,
             });
         }
         throw new OxygenError("network_error", "Unable to reach Oxygen API.", {
@@ -127,9 +133,9 @@ path, options = {}) {
                 api_url: apiUrl,
                 reason: error instanceof Error ? error.message : "unknown",
                 ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}),
-                ...unconfirmedWrite,
+                ...recovery,
             },
-            exitCode: 1,
+            exitCode: 5,
         });
     }
     finally {
@@ -141,12 +147,17 @@ path, options = {}) {
         // calling the gateway's page an invalid envelope.
         if (!(error instanceof OxygenError) || ![502, 503, 504].includes(response.status))
             throw error;
-        throw new OxygenError("invalid_response", `Oxygen API did not answer in time (HTTP ${response.status}); the outcome is unknown.`, {
+        const message = options.previewOnly
+            ? `Oxygen API did not answer in time (HTTP ${response.status}); the preview was not returned.`
+            : readOnly
+                ? `Oxygen API did not answer in time (HTTP ${response.status}); the read was not returned.`
+                : `Oxygen API did not answer in time (HTTP ${response.status}); the outcome is unknown.`;
+        throw new OxygenError("invalid_response", message, {
             details: {
                 status: response.status,
                 trace_id: response.headers.get("x-oxygen-trace-id") ?? traceId,
                 ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}),
-                ...(method === "GET" ? {} : { next_step: UNCONFIRMED_WRITE_NEXT_STEP }),
+                ...recovery,
             },
             exitCode: 1,
         });
@@ -173,11 +184,11 @@ path, options = {}) {
         if (error.code === "cli_update_required")
             throw await recoverFromCliFloorRejection(error, endpoint);
         // Any other answer to a write may have written something; never re-run the command after it.
-        if (method !== "GET")
+        if (!readOnly)
             recordMutatingRequestAnswered();
         throw error;
     }
-    if (method !== "GET")
+    if (!readOnly)
         recordMutatingRequestAnswered();
     return envelope.data;
 }