@oxygen-agent/cli 1.782.1 → 1.799.1

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.782.1
+Version: 1.799.1

package/dist/index.js

@@ -6998,7 +6998,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--label <label>", "Display label for the new column. Required unless --prompt-key supplies a default title.")
         .option("--key <key>", "Optional stable column key. Defaults to a normalized label.")
         .option("--data-type <type>", "Column data type: text, numeric, boolean, jsonb, or timestamptz.")
-        .option("--kind <kind>", "Column kind: manual, research, ai, formula, enrichment, tool, bind, or lookup. Defaults to manual. Use research for anything you would look up on the web.")
+        .option("--kind <kind>", "Column kind: manual, research, ai, formula, enrichment, tool, bind, or lookup. Defaults to manual. Use research for anything you would look up on the web. `lookup` reads a value out of another table; to LINK two tables row-to-row use `oxygen tables relate` instead \u2014 relation columns are two-sided and cannot be added here.")
         .option("--semantic-type <type>", "Optional semantic type such as company_domain.")
         .option("--definition-json <json>", "Optional JSON object with column definition metadata.")
         .option("--prompt <text-or-file>", "AI or research column prompt, or a path to a prompt file — a value that resolves to a readable file is read as one, matching --prompt everywhere else in this CLI. On its own it sets kind=ai and picks the data type (text, or jsonb with an output schema); pair it with --kind research to search the web per row instead. Reference other columns inline as {{column_key}} — no --input-mapping needed; unknown keys are rejected here instead of failing per row. Merges into --definition-json (the escape hatch for everything else); a `prompt` in both is an error.")
@@ -14722,13 +14722,21 @@ Run completion:
         .description("List workflow automations.")
         .addOption(new Option("--include-archived", "Deprecated no-op retained for compatibility.").hideHelp())
         .option("--tag <tag>", "Only workflows carrying this workspace tag (see `oxygen tags list`).")
+        .option("--node-testable", "Only canonical graph workflows, the ones `workflows call --node` can scope a test to. Legacy recipes and v1 step lists own their own execution order and are excluded.")
+        .option("--search <text>", "Match on name, slug, trigger event, or an integration the workflow uses — so \"meeting\" or \"hubspot\" finds it without knowing what someone named it.")
         .option("--json", "Print a JSON envelope.")
+        .addHelpText("after", "\nEach row carries `format` (graph, recipe or steps) and `nodeTestable`, so you can tell which workflows support single-step testing without opening them.\n")
         .action(async (options) => {
         await handleAsyncAction("workflows list", options, async () => {
             const params = new URLSearchParams();
             const tag = readOption(options.tag);
             if (tag)
                 params.set("tag", tag);
+            if (options.nodeTestable)
+                params.set("node_testable", "true");
+            const search = readOption(options.search);
+            if (search)
+                params.set("search", search);
             const qs = params.toString() ? `?${params.toString()}` : "";
             const data = await requestOxygen(`/api/cli/workflows${qs}`);
             if (!options.json)
@@ -14785,41 +14793,52 @@ Run completion:
         }), options));
     }))
         .addCommand(new Command("call")
-        .description("Enqueue a workflow run asynchronously and directly without simulating its trigger. Follow the returned run_id with `oxygen workflows tail <run_id>`.")
+        .description("Run a workflow — or preview it first. `--preview` shows every step that leaves Oxygen, the accounts it would use, and what one run costs, without running anything. Enqueues asynchronously without simulating the trigger; follow the returned run_id with `oxygen workflows tail <run_id>`.")
         .argument("[workflow]", "Workflow id, slug, or name.")
         .option("--workflow <workflow>", "Workflow id, slug, or name.")
         .option("--workflow-id <workflow_id>", "Workflow id or slug.")
         .option("--workflow-name <workflow_name>", "Workflow name.")
         .option("--input-json <json>", "Workflow input object. Defaults to {}.")
-        .requiredOption("--mode <mode>", "Execution mode. smoke-test/dry-run: 0 credits, no paid provider calls or external writes; internal reads still execute. live: may spend/write and requires approval + cap.")
+        .option("--mode <mode>", "Execution mode. smoke-test/dry-run: 0 credits, no paid provider calls or external writes; internal reads still execute. live: may spend/write and requires approval + cap. Not needed with --preview, which runs nothing.")
         .option("--idempotency-key <key>", "Optional idempotency key.")
         .option("--max-credits <n>", "Required credit ceiling for live calls.")
         .option("--approved", "Required for live calls after inspecting a dry run.")
         .option("--revision <n>", "Run a specific saved version instead of the live one. Dry-run and smoke-test only: publish a version to run it live.")
         .option("--node <node_id>", "Test one node: runs that node plus only the predecessors it needs, from the same saved graph. Dry-run and smoke-test only.")
-        .option("--preview", "Show what a live run of this exact version would do — every step that leaves Oxygen, the accounts it would use, and the billable-step floor — without running anything.")
+        .option("--preview", "Show what a live run of this exact version would do — every step that leaves Oxygen, the accounts it would use, and the minimum number of billable steps and credits it would cost — without running anything. AI and enrichment steps bill per row and can cost more than that floor. Needs no --mode: it always describes a live run.")
         .option("--include-bundle", "Include durable recipe bundles in JSON output.")
         .option("--json", "Print a JSON envelope.")
         .addHelpText("after", "\nSafety: smoke_test and dry_run share one boundary: 0 credits, no paid provider calls, no external writes. Oxygen internal reads use current workspace data, and oxygen.http_json_request may make a real outbound GET. Every mode creates an inspectable Workflow run record.\n\n--node scopes a test to one step. Oxygen plans the slice on the server from the exact saved version and records it on the run, so the run shows precisely which nodes were allowed to execute; you never submit a node list. Selecting the trigger, a disabled node, or a node unreachable from the trigger is refused with the reason. Only canonical graph workflows support it.\n")
         .action(async (workflowArg, options) => {
         const maxCredits = readPositiveNumber(options.maxCredits);
         const revisionVersion = readPositiveNumber(options.revision);
-        await handleAsyncAction("workflows call", options, async () => prepareWorkflowCliOutput(await requestOxygen("/api/cli/workflows/call", {
-            method: "POST",
-            body: {
-                workflow: readOption(workflowArg) ?? readOption(options.workflow),
-                ...(readOption(options.workflowId) ? { workflow_id: readOption(options.workflowId) } : {}),
-                ...(readOption(options.workflowName) ? { workflow_name: readOption(options.workflowName) } : {}),
-                input: options.inputJson ? parseJsonObject(options.inputJson) : {},
-                ...(readOption(options.mode) ? { mode: readOption(options.mode) } : {}),
-                ...(readOption(options.idempotencyKey) ? { idempotency_key: readOption(options.idempotencyKey) } : {}),
-                ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
-                ...(options.approved ? { approved: true } : {}),
-                ...(revisionVersion !== undefined ? { revision_version: revisionVersion } : {}),
-                ...(readOption(options.node) ? { test_node_id: readOption(options.node) } : {}),
-                ...(options.preview ? { preview: true } : {}),
-            },
-        }), options));
+        await handleAsyncAction("workflows call", options, async () => {
+            // --mode stopped being a commander requiredOption so that --preview,
+            // which executes nothing, no longer forces the caller to pick a mode
+            // the server then discards. A real call still needs one. Thrown
+            // INSIDE handleAsyncAction so it prints the CLI's error envelope and
+            // exits 2 like any other usage error — thrown outside, it escaped as
+            // an unhandled rejection and showed the user a Node stack trace.
+            if (!options.preview && !readOption(options.mode)) {
+                throw new OxygenError("invalid_request", "--mode is required. Use smoke-test, dry-run, or live. To see what a live run would do without running it, use --preview — it runs nothing and needs no mode.", { exitCode: 2 });
+            }
+            return prepareWorkflowCliOutput(await requestOxygen("/api/cli/workflows/call", {
+                method: "POST",
+                body: {
+                    workflow: readOption(workflowArg) ?? readOption(options.workflow),
+                    ...(readOption(options.workflowId) ? { workflow_id: readOption(options.workflowId) } : {}),
+                    ...(readOption(options.workflowName) ? { workflow_name: readOption(options.workflowName) } : {}),
+                    input: options.inputJson ? parseJsonObject(options.inputJson) : {},
+                    ...(readOption(options.mode) ? { mode: readOption(options.mode) } : {}),
+                    ...(readOption(options.idempotencyKey) ? { idempotency_key: readOption(options.idempotencyKey) } : {}),
+                    ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(revisionVersion !== undefined ? { revision_version: revisionVersion } : {}),
+                    ...(readOption(options.node) ? { test_node_id: readOption(options.node) } : {}),
+                    ...(options.preview ? { preview: true } : {}),
+                },
+            }), options);
+        });
     }))
         .addCommand(new Command("webhooks")
         .description("Workflow webhook trigger utilities.")
@@ -15018,9 +15037,12 @@ Full trigger schema: oxygen workflows schema --subject trigger --json
         .option("--workflow <workflow>", "Workflow id, slug, or name.")
         .option("--workflow-id <workflow_id>", "Workflow id or slug.")
         .option("--status <status>", "Filter by queued, running, waiting, awaiting_approval, completed, failed, canceling, or canceled.")
+        .option("--mode <mode>", "Filter by execution mode: smoke_test, dry_run, or live.")
+        .option("--cursor <cursor>", "Continue from a previous page. Pass the nextCursor the last response returned.")
         .option("--limit <n>", "Maximum runs to return. Defaults to 50.")
         .option("--include-bundle", "Include durable recipe bundles in JSON output.")
         .option("--json", "Print a JSON envelope.")
+        .addHelpText("after", "\nPaging is anchored to the exact last run of the previous page, so runs arriving while you page are never skipped or repeated. A null nextCursor means the history ended.\n")
         .action(async (options) => {
         await handleAsyncAction("workflows runs", options, async () => {
             const query = new URLSearchParams();
@@ -15029,6 +15051,10 @@ Full trigger schema: oxygen workflows schema --subject trigger --json
                 query.set("workflow", workflow);
             if (readOption(options.status))
                 query.set("status", readOption(options.status) ?? "");
+            if (readOption(options.mode))
+                query.set("mode", readOption(options.mode) ?? "");
+            if (readOption(options.cursor))
+                query.set("cursor", readOption(options.cursor) ?? "");
             const limit = readPositiveInt(options.limit);
             if (limit)
                 query.set("limit", String(limit));

package/node_modules/@oxygen/shared/dist/error-redaction.d.ts

@@ -78,6 +78,24 @@ export declare function readWorkflowStepFailure(error: unknown): WorkflowStepFai
  */
 export declare const AUTOMATION_ACTIONS_EXCEEDED_ERROR_CODE = "automation_actions_exceeded";
 export declare function isAutomationUsageQuotaError(error: unknown): boolean;
+/**
+ * The credit-era sibling of the code above, and the one most callers actually want.
+ *
+ * `automation_actions_exceeded` can only be thrown when the plan carries a non-null
+ * `monthlyAutomationActions`. Pricing Model 2.0 ([v1.330.0]) set that field to null on
+ * every base plan, so on current plans the admission gate in captureAutomationActions()
+ * is unreachable and assertAutomationActionsAvailable() refuses with `insufficient_credits`
+ * instead — actions bill AUTOMATION_ACTION_CREDITS each out of the one credit pool.
+ *
+ * Both codes mean the same thing to a caller: "this automation work was REFUSED admission,
+ * the customer must feel it, and the run must stop cleanly." Anything else is a metering
+ * write that failed and must be stepped over. Matching only the quota code is how a
+ * credit-exhausted cron ends up rethrowing out of the scheduler's enqueue loop instead of
+ * taking the graceful pause path — abandoning the lease and every remaining due trigger
+ * for that tenant's sweep.
+ */
+export declare const AUTOMATION_INSUFFICIENT_CREDITS_ERROR_CODE = "insufficient_credits";
+export declare function isAutomationAdmissionRefusal(error: unknown): boolean;
 /**
  * Node network primitives bury the actionable failure in `error.cause`: undici's
  * fetch rejects with a bare TypeError "fetch failed" and puts the real

package/node_modules/@oxygen/shared/dist/error-redaction.js

@@ -215,6 +215,30 @@ export function isAutomationUsageQuotaError(error) {
         && typeof error === "object"
         && error.code === AUTOMATION_ACTIONS_EXCEEDED_ERROR_CODE;
 }
+/**
+ * The credit-era sibling of the code above, and the one most callers actually want.
+ *
+ * `automation_actions_exceeded` can only be thrown when the plan carries a non-null
+ * `monthlyAutomationActions`. Pricing Model 2.0 ([v1.330.0]) set that field to null on
+ * every base plan, so on current plans the admission gate in captureAutomationActions()
+ * is unreachable and assertAutomationActionsAvailable() refuses with `insufficient_credits`
+ * instead — actions bill AUTOMATION_ACTION_CREDITS each out of the one credit pool.
+ *
+ * Both codes mean the same thing to a caller: "this automation work was REFUSED admission,
+ * the customer must feel it, and the run must stop cleanly." Anything else is a metering
+ * write that failed and must be stepped over. Matching only the quota code is how a
+ * credit-exhausted cron ends up rethrowing out of the scheduler's enqueue loop instead of
+ * taking the graceful pause path — abandoning the lease and every remaining due trigger
+ * for that tenant's sweep.
+ */
+export const AUTOMATION_INSUFFICIENT_CREDITS_ERROR_CODE = "insufficient_credits";
+export function isAutomationAdmissionRefusal(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const code = error.code;
+    return code === AUTOMATION_ACTIONS_EXCEEDED_ERROR_CODE
+        || code === AUTOMATION_INSUFFICIENT_CREDITS_ERROR_CODE;
+}
 const MAX_CAUSE_DEPTH = 4;
 const MAX_CAUSE_MESSAGE_LENGTH = 200;
 export function errorCauseChain(error, maxDepth = MAX_CAUSE_DEPTH) {

package/node_modules/@oxygen/shared/dist/version.d.ts

@@ -1,4 +1,4 @@
-export declare const OXYGEN_VERSION = "1.782.1";
+export declare const OXYGEN_VERSION = "1.799.1";
 export declare const OXYGEN_MINIMUM_CLI_VERSION = "1.181.0";
 export declare const MANAGED_INBOX_MINIMUM_CLI_VERSION = "1.326.2";
 export declare const SUPPORT_AGENT_REPLY_MINIMUM_CLI_VERSION = "1.747.0";

package/node_modules/@oxygen/shared/dist/version.js

@@ -1,4 +1,4 @@
-export const OXYGEN_VERSION = "1.782.1";
+export const OXYGEN_VERSION = "1.799.1";
 // The GLOBAL CLI compatibility floor: the oldest CLI allowed to call any
 // operational route. Raising it hard-rejects every older CLI from the entire
 // product, so it obeys one law, enforced by scripts/ci/cli-min-version-gate.mjs:

package/node_modules/@oxygen/workflows/dist/usage-estimate.d.ts

@@ -14,6 +14,9 @@ export type CronCadenceAssessment = {
     floorActionsPer30Days: number;
     includedActions: number;
     floorShareOfIncluded: number;
+    basis: "plan_action_quota" | "plan_monthly_credits";
+    includedCredits: number | null;
+    floorCreditsPer30Days: number | null;
     minimumViableIntervalMinutes: number | null;
     verdict: "fits" | "impossible";
 };
@@ -22,6 +25,8 @@ export declare function assessCronCadenceViability(input: {
     cron: string | null | undefined;
     includedActions: number | null;
     overageEnabled: boolean;
+    includedCredits?: number | null;
+    creditsPerAction?: number | null;
 }): CronCadenceAssessment | null;
 export type CronAggressiveness = {
     level: "aggressive" | "very_aggressive";

package/node_modules/@oxygen/workflows/dist/usage-estimate.js

@@ -287,26 +287,53 @@ const MINUTES_PER_30_DAYS = 43_200;
 // enabled (the org has opted into paying past the cap, so a cadence that
 // overruns it bills instead of failing).
 export function assessCronCadenceViability(input) {
-    if (!input.cron || input.includedActions === null || input.overageEnabled)
+    if (!input.cron || input.overageEnabled)
         return null;
-    if (!Number.isFinite(input.includedActions) || input.includedActions <= 0)
+    const creditsPerAction = typeof input.creditsPerAction === "number"
+        && Number.isFinite(input.creditsPerAction)
+        && input.creditsPerAction > 0
+        ? input.creditsPerAction
+        : null;
+    const includedCredits = typeof input.includedCredits === "number"
+        && Number.isFinite(input.includedCredits)
+        && input.includedCredits > 0
+        ? input.includedCredits
+        : null;
+    // Prefer a real action quota when the plan still has one; otherwise derive the
+    // equivalent action budget from monthly credits.
+    const basis = input.includedActions === null
+        ? "plan_monthly_credits"
+        : "plan_action_quota";
+    const includedActions = basis === "plan_action_quota"
+        ? input.includedActions
+        : (includedCredits !== null && creditsPerAction !== null
+            ? Math.floor(includedCredits / creditsPerAction)
+            : null);
+    if (includedActions === null)
+        return null;
+    if (!Number.isFinite(includedActions) || includedActions <= 0)
         return null;
     const scheduledRunsPer30Days = estimateCronRunsPer30Days(input.cron);
     if (scheduledRunsPer30Days === null)
         return null;
     const actionsPerRunFloor = estimateWorkflowRunAutomationActionsFloor(input.manifest);
     const floorActionsPer30Days = scheduledRunsPer30Days * actionsPerRunFloor;
-    const runsAllowedPer30Days = Math.floor(input.includedActions / actionsPerRunFloor);
+    const runsAllowedPer30Days = Math.floor(includedActions / actionsPerRunFloor);
     return {
         scheduledRunsPer30Days,
         actionsPerRunFloor,
         floorActionsPer30Days,
-        includedActions: input.includedActions,
-        floorShareOfIncluded: floorActionsPer30Days / input.includedActions,
+        includedActions,
+        floorShareOfIncluded: floorActionsPer30Days / includedActions,
+        basis,
+        includedCredits: basis === "plan_monthly_credits" ? includedCredits : null,
+        floorCreditsPer30Days: basis === "plan_monthly_credits" && creditsPerAction !== null
+            ? Math.round(floorActionsPer30Days * creditsPerAction * 1000) / 1000
+            : null,
         minimumViableIntervalMinutes: runsAllowedPer30Days > 0
             ? Math.ceil(MINUTES_PER_30_DAYS / runsAllowedPer30Days)
             : null,
-        verdict: floorActionsPer30Days > input.includedActions ? "impossible" : "fits",
+        verdict: floorActionsPer30Days > includedActions ? "impossible" : "fits",
     };
 }
 // Warn (never block) below this cadence; the billing gate above stays the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxygen-agent/cli",
-  "version": "1.782.1",
+  "version": "1.799.1",
   "private": false,
   "license": "UNLICENSED",
   "type": "module",