@oxygen-agent/cli 1.287.12 → 1.310.0

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

@@ -15,6 +15,9 @@ export type LogContext = {
     surface?: "mcp" | "cli" | "web" | "worker" | undefined;
 };
 export declare function withLogContext<T>(ctx: LogContext, fn: () => T): T;
+export declare function enterLogContext(ctx: LogContext): void;
+export type LogSink = (record: Record<string, unknown>) => void;
+export declare function setLogSink(sink: LogSink | null): void;
 export declare function log(level: LogLevel, msg: string, fields?: Record<string, unknown>): void;
 export declare function errorId(err: unknown): string;
 export declare function errorFields(err: unknown): Record<string, unknown>;

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

@@ -7,11 +7,63 @@ export function withLogContext(ctx, fn) {
     const merged = { ...(store.getStore() ?? {}), ...ctx };
     return store.run(merged, fn);
 }
+// Next.js route handlers resolve identity imperatively — there is no callback to
+// wrap at the call site, so `withLogContext`'s run-a-callback shape does not fit.
+// This stamps the ambient context for the rest of the request. Without it, every
+// log() emitted deep inside an /api/cli request landed with no surface, no
+// trace_id, and no org_id — only the hand-stamped `cli.command_failed` line was
+// joinable (181k surface-less rows/24h on 2026-07-11, OXY-3712).
+//
+// It MUTATES the active store object rather than calling `enterWith`. `enterWith`
+// rebinds the store only for the async resource that calls it: when a stamper is
+// an async function that `await`s first — `requireCliIdentity` awaits token
+// validation before it stamps — the rebind dies with that resource and never
+// reaches the caller's continuation, so the route logged on. The store object is
+// shared by reference with the caller's context, so assigning into it is visible
+// for the rest of the request. `withLogContext` allocates a fresh object per
+// call, so a concurrent request cannot see this one's identity.
+export function enterLogContext(ctx) {
+    const active = store.getStore();
+    if (active) {
+        Object.assign(active, ctx);
+        return;
+    }
+    store.enterWith({ ...ctx });
+}
 function getLogContext() {
     return store.getStore() ?? {};
 }
+const CANONICAL_SURFACES = new Set(["mcp", "cli", "web", "worker"]);
+// Call-site fields deliberately win over the ambient context (a caller must be able to
+// override org_id, provider, run_id...). `surface` is the one exception: it is a RESERVED
+// dimension that every surface-bucketed monitor and dashboard groups on, and `LogContext`
+// closes it to four values — but `fields` is `Record<string, unknown>`, so a free-form
+// label typechecks and then CLOBBERS the true surface.
+//
+// That is not hypothetical: `crm_signal_bridge.dispatch_failed` passed
+// `surface: "crm_signal_bridge"` and landed 167 rows/30d in a junk bucket no dashboard
+// counts, while the web request that emitted them lost its surface entirely (OXY-3879).
+//
+// So the label is demoted to `component` — kept, never dropped — and the context's surface
+// is restored. A row with no ambient surface stays surface-less rather than inventing a
+// bucket: honest, and countable as the dark spot it is.
+function reserveSurfaceDimension(merged, ctx) {
+    const surface = merged.surface;
+    if (typeof surface !== "string" || CANONICAL_SURFACES.has(surface))
+        return merged;
+    return {
+        ...merged,
+        component: merged.component ?? surface,
+        surface: ctx.surface,
+    };
+}
+let logSink = null;
+export function setLogSink(sink) {
+    logSink = sink;
+}
 export function log(level, msg, fields) {
-    const line = JSON.stringify({
+    const context = getLogContext();
+    const record = {
         ts: new Date().toISOString(),
         level,
         msg,
@@ -25,11 +77,9 @@ export function log(level, msg, fields) {
         sha: process.env.VERCEL_GIT_COMMIT_SHA ?? process.env.OXYGEN_GIT_SHA ?? null,
         region: process.env.VERCEL_REGION ?? null,
         env: process.env.VERCEL_ENV ?? process.env.NODE_ENV ?? null,
-        ...sanitizeLogFields({
-            ...getLogContext(),
-            ...fields,
-        }),
-    });
+        ...sanitizeLogFields(reserveSurfaceDimension({ ...context, ...fields }, context)),
+    };
+    const line = JSON.stringify(record);
     if (level === "error") {
         console.error(line);
     }
@@ -39,6 +89,15 @@ export function log(level, msg, fields) {
     else {
         console.log(line);
     }
+    if (!logSink)
+        return;
+    try {
+        logSink(record);
+    }
+    catch {
+        // Telemetry must never break the code it observes: a failing sink degrades
+        // to stdout-only, which is exactly the pre-sink behavior.
+    }
 }
 // Short, deterministic id grouping similar errors. Hashes name + message +
 // the first stack frame so the same TypeError at the same location dedupes

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

@@ -1,3 +1,4 @@
 export type PrimitiveTelemetryAttribute = string | number | boolean | string[] | number[] | boolean[];
 export declare function sanitizeLogFields(fields: Record<string, unknown> | undefined): Record<string, unknown>;
 export declare function normalizeTelemetryAttributes(attributes: Record<string, unknown> | undefined): Record<string, PrimitiveTelemetryAttribute>;
+export declare function redactSecretsInString(value: string): string;

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

@@ -5,8 +5,20 @@ const OMITTED_KEY_PATTERN = /^(body|payload|prompt|prompts|raw_prompt|raw_prompt
 // fields — most commonly an Authorization header dumped into error_message /
 // error_stack. This matches the HTTP bearer scheme followed by its token (JWT /
 // base64 / opaque, including our `oxy_live_`/`oxy_sess_` prefixes) anywhere in a
-// string.
-const BEARER_TOKEN_PATTERN = /\bBearer\s+[\w.~+/=-]+/gi;
+// string. The scheme match stays case-insensitive because a real leaked header
+// may well be lowercase.
+//
+// The lookahead exists because case-insensitivity also made this match English
+// prose: the static 401 body "A CLI bearer token is required." became "A CLI
+// Bearer[REDACTED] is required." in every log line, which *inverts* the message —
+// a redaction marker tells the reader a credential was sent and scrubbed, when in
+// truth none was sent at all. So decline the match when the credential-shaped run
+// is exactly the word "token"/"tokens": neither carries secret material, and both
+// are far too short to trip the prod sweep (case-sensitive, 12+ chars after
+// "Bearer "). The inner lookahead keeps a credential that merely *starts* with
+// those letters — `Bearer token_AbC123`, `Bearer token.AbC123` — fully redacted,
+// since there the run continues into the token charset.
+const BEARER_TOKEN_PATTERN = /\bBearer\s+(?!tokens?(?![\w.~+/=-]))[\w.~+/=-]+/gi;
 // OXY-139: the prod log-hygiene sweep also flags `sk-…` API keys and DB
 // connection URLs that ride along inside ordinary (non-secret-named) fields, so
 // keyed + Bearer redaction is not enough. We scrub the two shapes that carry real
@@ -135,7 +147,7 @@ function sanitizeAttributeKey(key) {
 // every prod-sweep regex (`Bearer `, `sk-…`, `postgres://…`) — finds nothing, so
 // redaction stays idempotent. Sharing the global regexes is safe because
 // String.replace resets their lastIndex between calls.
-function redactSecretsInString(value) {
+export function redactSecretsInString(value) {
     return value
         .replace(BEARER_TOKEN_PATTERN, "Bearer[REDACTED]")
         .replace(DB_URL_PATTERN, "[REDACTED_DB_URL]")

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

@@ -36,7 +36,7 @@ export type SequenceChannel = (typeof SEQUENCE_CHANNELS)[number];
  * a signal — it's resolved on demand by the dispatcher via a connection branch,
  * `condition: "already_connected"`.)
  */
-export declare const SEQUENCE_SIGNALS: readonly ["linkedin_connected", "linkedin_replied", "email_sent", "email_opened", "email_clicked", "email_replied", "email_bounced", "company_hiring", "company_raised_funds", "job_change", "new_hire", "web_visit", "intent"];
+export declare const SEQUENCE_SIGNALS: readonly ["linkedin_connected", "linkedin_replied", "whatsapp_replied", "email_sent", "email_opened", "email_clicked", "email_replied", "email_bounced", "company_hiring", "company_raised_funds", "job_change", "new_hire", "web_visit", "intent"];
 export type SequenceSignal = (typeof SEQUENCE_SIGNALS)[number];
 /**
  * Email engagement signals that ONLY arrive via the Instantly webhook
@@ -165,8 +165,16 @@ export type SequenceSendWindow = {
     /** row_values key holding the lead's IANA timezone (timezone_mode="recipient"). */
     recipient_timezone_column?: string;
 };
-/** Base content + up to this many alternates per A/B step (base counts as variant "a"). */
-export declare const MAX_STEP_VARIANTS = 5;
+/**
+ * Base content + up to this many alternates per A/B step (base counts as
+ * variant "a", so the ceiling is "a"–"z" — Instantly-class A/Z testing).
+ * NEVER raise past 26: sequenceVariantLabel wraps modulo the alphabet, so a
+ * 27th variant would alias back to "a" and corrupt per-variant stats keying.
+ * Auto-winner semantics at high N are unchanged and intentional: a decision
+ * waits until EVERY active variant clears its min-send/min-conversion
+ * thresholds, so a very wide test decides slowly (deterministic + reversible).
+ */
+export declare const MAX_STEP_VARIANTS = 26;
 /**
  * Metrics a step's opt-in auto-winner (A/B auto-optimize) can decide on. `reply`
  * is the only metric today — open/click require tracking domains (a gated,

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

@@ -39,6 +39,7 @@ export const SEQUENCE_CHANNELS = ["linkedin", "email", "whatsapp"];
 export const SEQUENCE_SIGNALS = [
     "linkedin_connected",
     "linkedin_replied",
+    "whatsapp_replied",
     "email_sent",
     "email_opened",
     "email_clicked",
@@ -243,8 +244,16 @@ export function whatsAppAttendeeIdFromRow(rowValues, phoneColumnKey) {
     }
     return null;
 }
-/** Base content + up to this many alternates per A/B step (base counts as variant "a"). */
-export const MAX_STEP_VARIANTS = 5;
+/**
+ * Base content + up to this many alternates per A/B step (base counts as
+ * variant "a", so the ceiling is "a"–"z" — Instantly-class A/Z testing).
+ * NEVER raise past 26: sequenceVariantLabel wraps modulo the alphabet, so a
+ * 27th variant would alias back to "a" and corrupt per-variant stats keying.
+ * Auto-winner semantics at high N are unchanged and intentional: a decision
+ * waits until EVERY active variant clears its min-send/min-conversion
+ * thresholds, so a very wide test decides slowly (deterministic + reversible).
+ */
+export const MAX_STEP_VARIANTS = 26;
 /**
  * Metrics a step's opt-in auto-winner (A/B auto-optimize) can decide on. `reply`
  * is the only metric today — open/click require tracking domains (a gated,

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

@@ -0,0 +1,10 @@
+/**
+ * Timing primitives shared across every OXYGEN package.
+ */
+/**
+ * Resolve after `ms` milliseconds. The canonical, behavior-free delay used by
+ * retry/backoff/poll loops throughout the codebase — previously duplicated as a
+ * local `sleep` in a dozen files. No jitter, cap, or cancellation: callers that
+ * need those compose them around this primitive.
+ */
+export declare function sleep(ms: number): Promise<void>;

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

@@ -0,0 +1,12 @@
+/**
+ * Timing primitives shared across every OXYGEN package.
+ */
+/**
+ * Resolve after `ms` milliseconds. The canonical, behavior-free delay used by
+ * retry/backoff/poll loops throughout the codebase — previously duplicated as a
+ * local `sleep` in a dozen files. No jitter, cap, or cancellation: callers that
+ * need those compose them around this primitive.
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/node_modules/@oxygen/shared/dist/type-guards.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Canonical structural type guards for @oxygen/shared.
+ *
+ * `isRecord` was the most-duplicated type guard in the repo (OXY-3979): five
+ * byte-equivalent module-local copies across packages/mcp-server/src/tools
+ * alone (plus more elsewhere), in two provably-equivalent variants that differ
+ * only in how they reject `null` — `Boolean(value)` vs `value !== null`, which
+ * agree for every value `typeof value === "object"` admits. This is the one
+ * home; import it instead of re-declaring.
+ */
+/**
+ * True when `value` is a non-null, non-array object usable as
+ * `Record<string, unknown>`. Rejects `null`, arrays, and every primitive.
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/node_modules/@oxygen/shared/dist/type-guards.js

@@ -0,0 +1,17 @@
+/**
+ * Canonical structural type guards for @oxygen/shared.
+ *
+ * `isRecord` was the most-duplicated type guard in the repo (OXY-3979): five
+ * byte-equivalent module-local copies across packages/mcp-server/src/tools
+ * alone (plus more elsewhere), in two provably-equivalent variants that differ
+ * only in how they reject `null` — `Boolean(value)` vs `value !== null`, which
+ * agree for every value `typeof value === "object"` admits. This is the one
+ * home; import it instead of re-declaring.
+ */
+/**
+ * True when `value` is a non-null, non-array object usable as
+ * `Record<string, unknown>`. Rejects `null`, arrays, and every primitive.
+ */
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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

@@ -1,2 +1,3 @@
-export declare const OXYGEN_VERSION = "1.287.12";
+export declare const OXYGEN_VERSION = "1.310.0";
 export declare const OXYGEN_MINIMUM_CLI_VERSION = "1.181.0";
+export declare const MANAGED_INBOX_MINIMUM_CLI_VERSION = "1.298.0";

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

@@ -1,8 +1,39 @@
-export const OXYGEN_VERSION = "1.287.12";
-// Bump this only when deployed CLI/API contracts require a newer CLI.
+export const OXYGEN_VERSION = "1.310.0";
+// 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:
+//
+//     OXYGEN_MINIMUM_CLI_VERSION <= the `latest` dist-tag of @oxygen-agent/cli
+//
+// The CLI is published by .github/workflows/publish-cli-npm.yml, which fires on a
+// *successful production deployment* — the npm publish is always AFTER the server
+// that enforces this floor is already live. A floor above npm's newest CLI is
+// therefore not a race we might lose, it is a guaranteed lockout: every customer's
+// CLI is rejected with `cli_update_required`, and the `oxygen update` the error
+// prints can only reinstall the exact version being rejected. If that publish then
+// fails (npm outage, `npm audit` advisory, CI timeout), the lockout is permanent —
+// on a product whose primary surface is the CLI.
+//
+// So floors LAG one release: publish the CLI in release N, raise the floor to it in
+// release N+1. And a contract change that breaks ONE surface belongs on that
+// surface — pass `minimumCliVersion` to requireCliIdentity/requireCliOrWebIdentity
+// (see MANAGED_INBOX_MINIMUM_CLI_VERSION). A per-route floor fails one command
+// safely; a global floor fails the whole product. OXY-4091.
+//
 // 1.181.0: paid table action runs and background columns run require
 // approved=true in addition to max_credits; older CLIs cannot send the flag.
 // 1.154.0: LinkedIn → Sequencer rename moved the CLI/API/MCP surface
 // (oxygen sequences|inbox|senders, /api/cli/{sequences,inbox,senders}) and
 // removed the old /api/cli/linkedin/* routes — older CLIs would 404.
 export const OXYGEN_MINIMUM_CLI_VERSION = "1.181.0";
+// Per-surface floor for the whitelabel/managed-inbox purchase path, enforced only
+// by /api/cli/managed-inboxes/subscribe.
+//
+// 1.298.0: whitelabel inbox subscribe moved from Oxygen credits to a USD-billed
+// Stripe subscription. Older CLIs send `zapshield` (gone), omit the registrant
+// address the registrar now requires, and read `credits_required` from a preview
+// that no longer returns it — so they would mis-render the price of a PAID order.
+// Refusing them is right; refusing them EVERYWHERE was not. This shipped as a
+// 117-minor raise of the global floor inside an unrelated feature commit and armed
+// a product-wide lockout that nothing would have caught before prod (OXY-4091).
+export const MANAGED_INBOX_MINIMUM_CLI_VERSION = "1.298.0";

package/node_modules/@oxygen/workflows/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./usage-estimate.js";
 export declare const WORKFLOW_MANIFEST_VERSION = 1;
 export declare const WORKFLOW_COMPILER_VERSION = "oxygen-workflows-v1";
 export declare const DURABLE_RECIPE_COMPILER_VERSION = "oxygen-recipes-v2";
@@ -840,4 +841,3 @@ export declare function evaluateWorkflowRunSpendCap(input: {
     creditsUsed: number;
     estimatedCredits?: number | null;
 }): WorkflowSpendCapDecision;
-export {};

package/node_modules/@oxygen/workflows/dist/index.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import * as vm from "node:vm"; // skipcq: JS-C1003
+export * from "./usage-estimate.js";
 export const WORKFLOW_MANIFEST_VERSION = 1;
 export const WORKFLOW_COMPILER_VERSION = "oxygen-workflows-v1";
 export const DURABLE_RECIPE_COMPILER_VERSION = "oxygen-recipes-v2";

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

@@ -0,0 +1,41 @@
+export type WorkflowAutomationUsageEstimate = {
+    actionsPerRunFloor: number;
+    scheduledRunsPer30Days: number | null;
+    scheduledActionsPer30DaysFloor: number | null;
+    dynamicRuntimeActions: boolean;
+    perRowFanout: boolean;
+};
+export declare function estimateWorkflowRunAutomationActionsFloor(manifest: unknown): number;
+export declare function estimateWorkflowAutomationUsage(manifest: unknown, cron?: string | null): WorkflowAutomationUsageEstimate | null;
+export declare function estimateCronRunsPer30Days(cron: string): number | null;
+export type CronCadenceAssessment = {
+    scheduledRunsPer30Days: number;
+    actionsPerRunFloor: number;
+    floorActionsPer30Days: number;
+    includedActions: number;
+    floorShareOfIncluded: number;
+    minimumViableIntervalMinutes: number | null;
+    verdict: "fits" | "impossible";
+};
+export declare function assessCronCadenceViability(input: {
+    manifest: unknown;
+    cron: string | null | undefined;
+    includedActions: number | null;
+    overageEnabled: boolean;
+}): CronCadenceAssessment | null;
+export type ObservedAutomationUsageProjection = {
+    runSample: number;
+    actionsPerRunAvg: number;
+    projectedActionsPer30Days: number | null;
+    projectedExhaustionAt: string | null;
+    projectedOverAllowance: boolean;
+};
+export declare function projectObservedAutomationUsage(input: {
+    perRunActions: number[];
+    scheduledRunsPer30Days: number | null;
+    includedActions: number | null;
+    remainingActions: number | null;
+    overageEnabled: boolean;
+    windowEnd?: Date | string | null;
+    now?: Date;
+}): ObservedAutomationUsageProjection | null;

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

@@ -0,0 +1,203 @@
+// Static automation-action usage estimation shared by the web workflow page
+// and the worker scheduler's admission gate. The per-run count derived from a
+// manifest is a FLOOR, never a projection: runtime metering bills 1 action per
+// EMITTED checkpoint (recipe code loops multiply), 1 per row written by
+// oxygen.rows_upsert (see estimateAutomationActionsForTool in
+// @oxygen/integrations automation-usage.ts), and retried attempts bill again.
+// Surfaces must present these numbers as minimums; observed run history is the
+// honest projection (projectObservedAutomationUsage below).
+const ROW_FANOUT_TOOL_IDS = new Set(["oxygen.rows_upsert"]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Tolerant of raw DB json (the scheduler feeds unvalidated manifest rows):
+// steps-array manifests count 1 per step; everything else is treated as a
+// recipe shape (1 + max(visual checkpoints, declared tools)). Byte-compatible
+// with the two prior copies in workflow-scheduler.ts and the web page.
+export function estimateWorkflowRunAutomationActionsFloor(manifest) {
+    if (!isRecord(manifest))
+        return 1;
+    const steps = Array.isArray(manifest.steps) ? manifest.steps : null;
+    if (steps)
+        return Math.max(1, steps.length);
+    const visualPlan = isRecord(manifest.visual_plan) ? manifest.visual_plan : null;
+    const visualSteps = Array.isArray(visualPlan?.steps) ? visualPlan.steps : [];
+    const checkpointCount = visualSteps.filter((step) => isRecord(step) && (step.kind !== "branch" || typeof step.checkpoint_id === "string")).length;
+    const toolsUsed = Array.isArray(manifest.tools_used) ? manifest.tools_used : [];
+    return 1 + Math.max(checkpointCount, toolsUsed.length, 0);
+}
+function manifestIsRecipeShaped(manifest) {
+    return isRecord(manifest) && !Array.isArray(manifest.steps);
+}
+function manifestWritesRowsPerRun(manifest) {
+    if (!isRecord(manifest))
+        return false;
+    const steps = Array.isArray(manifest.steps) ? manifest.steps : null;
+    if (steps) {
+        return steps.some((step) => isRecord(step) && step.kind === "tool" && typeof step.tool === "string" && ROW_FANOUT_TOOL_IDS.has(step.tool));
+    }
+    const toolsUsed = Array.isArray(manifest.tools_used) ? manifest.tools_used : [];
+    return toolsUsed.some((tool) => typeof tool === "string" && ROW_FANOUT_TOOL_IDS.has(tool));
+}
+export function estimateWorkflowAutomationUsage(manifest, cron) {
+    if (!isRecord(manifest))
+        return null;
+    const actionsPerRunFloor = estimateWorkflowRunAutomationActionsFloor(manifest);
+    const scheduledRunsPer30Days = cron ? estimateCronRunsPer30Days(cron) : null;
+    return {
+        actionsPerRunFloor,
+        scheduledRunsPer30Days,
+        scheduledActionsPer30DaysFloor: scheduledRunsPer30Days === null ? null : scheduledRunsPer30Days * actionsPerRunFloor,
+        dynamicRuntimeActions: manifestIsRecipeShaped(manifest),
+        perRowFanout: manifestWritesRowsPerRun(manifest),
+    };
+}
+// Fixed 30-day month, minute and hour fields treated independently; timezone
+// is deliberately ignored — the result sizes a schedule, it does not simulate
+// a calendar. Unparseable or non-5-field crons return null ("on demand").
+export function estimateCronRunsPer30Days(cron) {
+    const fields = cron.trim().split(/\s+/);
+    const [minuteField, hourField, dayOfMonthField, monthField, dayOfWeekField, ...extraFields] = fields;
+    if (extraFields.length > 0
+        || !minuteField
+        || !hourField
+        || !dayOfMonthField
+        || !monthField
+        || !dayOfWeekField) {
+        return null;
+    }
+    const minuteCount = countCronFieldValues(minuteField, 0, 59);
+    const hourCount = countCronFieldValues(hourField, 0, 23);
+    const dayOfMonthCount = countCronFieldValues(dayOfMonthField, 1, 31);
+    const monthCount = countCronFieldValues(monthField, 1, 12);
+    const dayOfWeekCount = countCronFieldValues(dayOfWeekField, 0, 7);
+    if (minuteCount === null
+        || hourCount === null
+        || dayOfMonthCount === null
+        || monthCount === null
+        || dayOfWeekCount === null) {
+        return null;
+    }
+    const monthFactor = monthField === "*" ? 1 : Math.min(1, monthCount / 12);
+    const dayOfMonthFactor = dayOfMonthField === "*" ? 1 : Math.min(1, dayOfMonthCount / 30);
+    const dayOfWeekFactor = dayOfWeekField === "*" ? 1 : Math.min(1, dayOfWeekCount / 7);
+    // Cron OR-semantics: when both day fields are restricted, a slot fires if
+    // either matches, so the factors add (capped at daily).
+    const dayFactor = dayOfMonthField !== "*" && dayOfWeekField !== "*"
+        ? Math.min(1, dayOfMonthFactor + dayOfWeekFactor)
+        : Math.min(dayOfMonthFactor, dayOfWeekFactor);
+    const runs = minuteCount * hourCount * 30 * monthFactor * dayFactor;
+    return Math.max(1, Math.round(runs));
+}
+function countCronFieldValues(field, min, max) {
+    const values = new Set();
+    for (const part of field.split(",")) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            return null;
+        const match = trimmed.match(/^(\*|\d+(?:-\d+)?)(?:\/(\d+))?$/);
+        if (!match)
+            return null;
+        const rangePart = match[1];
+        const stepPart = match[2];
+        if (!rangePart)
+            return null;
+        const step = stepPart ? Number(stepPart) : 1;
+        if (!Number.isInteger(step) || step <= 0)
+            return null;
+        let start = min;
+        let end = max;
+        if (rangePart !== "*") {
+            const [startRaw, endRaw] = rangePart.split("-");
+            start = Number(startRaw);
+            end = endRaw === undefined ? start : Number(endRaw);
+        }
+        if (!Number.isInteger(start)
+            || !Number.isInteger(end)
+            || start < min
+            || end > max
+            || end < start) {
+            return null;
+        }
+        for (let value = start; value <= end; value += step) {
+            values.add(normalizeCronFieldValue(value, min, max));
+        }
+    }
+    return values.size;
+}
+function normalizeCronFieldValue(value, min, max) {
+    if (min === 0 && max === 7 && value === 7)
+        return 0;
+    return value;
+}
+const MINUTES_PER_30_DAYS = 43_200;
+// Cadence-vs-allowance arithmetic for a cron trigger, using the manifest FLOOR
+// (see the header): the cheapest run this workflow can physically have. A
+// verdict of "impossible" is therefore a lower bound that already overruns the
+// plan — the real run cost is only ever higher, because row fan-out is added at
+// runtime and is unbounded.
+//
+// Returns null when the question is not decidable or not meaningful:
+// no cron (on-demand), an unparseable cron, an unlimited allowance, or overage
+// 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)
+        return null;
+    if (!Number.isFinite(input.includedActions) || input.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);
+    return {
+        scheduledRunsPer30Days,
+        actionsPerRunFloor,
+        floorActionsPer30Days,
+        includedActions: input.includedActions,
+        floorShareOfIncluded: floorActionsPer30Days / input.includedActions,
+        minimumViableIntervalMinutes: runsAllowedPer30Days > 0
+            ? Math.ceil(MINUTES_PER_30_DAYS / runsAllowedPer30Days)
+            : null,
+        verdict: floorActionsPer30Days > input.includedActions ? "impossible" : "fits",
+    };
+}
+export function projectObservedAutomationUsage(input) {
+    const billedRuns = input.perRunActions.filter((actions) => Number.isFinite(actions) && actions > 0);
+    if (billedRuns.length === 0)
+        return null;
+    const total = billedRuns.reduce((sum, actions) => sum + actions, 0);
+    const avg = total / billedRuns.length;
+    const projected = input.scheduledRunsPer30Days === null
+        ? null
+        : Math.round(avg * input.scheduledRunsPer30Days);
+    const overAllowance = projected !== null
+        && input.includedActions !== null
+        && !input.overageEnabled
+        && projected > input.includedActions;
+    let exhaustionAt = null;
+    if (projected !== null
+        && projected > 0
+        && input.remainingActions !== null
+        && !input.overageEnabled) {
+        const perDay = projected / 30;
+        if (perDay > 0) {
+            const days = Math.max(0, input.remainingActions) / perDay;
+            const now = input.now ?? new Date();
+            const exhaustion = new Date(now.getTime() + days * 24 * 60 * 60 * 1000);
+            const windowEnd = input.windowEnd ? new Date(input.windowEnd) : null;
+            exhaustionAt = windowEnd && !Number.isNaN(windowEnd.getTime()) && exhaustion > windowEnd
+                ? null
+                : exhaustion.toISOString();
+        }
+    }
+    return {
+        runSample: billedRuns.length,
+        actionsPerRunAvg: Math.round(avg),
+        projectedActionsPer30Days: projected,
+        projectedExhaustionAt: exhaustionAt,
+        projectedOverAllowance: overAllowance,
+    };
+}

package/package.json

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