@oxygen-agent/cli 1.177.1 → 1.209.6

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

@@ -8,6 +8,9 @@ export const BLUEPRINT_COMPILER_VERSION = "oxygen-blueprints-v1";
 export const MAX_RECIPE_BUNDLE_BYTES = 2_000_000;
 export const MAX_BLUEPRINT_BYTES = 4_000_000;
 export const DEFAULT_WORKFLOW_CRON_TIMEZONE = "UTC";
+// Step ids that must not be used: they collide with JavaScript object internals
+// when the runtime assembles ctx.steps, so their outputs would be silently lost.
+const RESERVED_STEP_IDS = new Set(["__proto__", "constructor", "prototype"]);
 // Compatibility and determinism lint only. The Vercel sandbox process,
 // denied network policy, and runtime global guards are the security boundary.
 const UNSAFE_RECIPE_BUNDLE_PATTERNS = [
@@ -18,7 +21,11 @@ const UNSAFE_RECIPE_BUNDLE_PATTERNS = [
     { token: "XMLHttpRequest", pattern: /\bXMLHttpRequest\b/ }, // skipcq: SCT-A000
     { token: "WebSocket", pattern: /\bWebSocket\b/ },
     { token: "EventSource", pattern: /\bEventSource\b/ }, // skipcq: SCT-A000
-    { token: "require", pattern: /\brequire\b/ },
+    // Block CommonJS require(...) but allow a `.require` method access (the
+    // ctx.approvals.require() durable-approval API). A real global require is a
+    // bare identifier; any X.require on a dangerous global (globalThis/process/…)
+    // is already caught by that global's own rule above.
+    { token: "require", pattern: /(?<!\.)\brequire\b/ },
     { token: "dynamic import", pattern: /\bimport(?:\s|\/\*[\s\S]*?\*\/)*\(/ }, // skipcq: SCT-A000
     { token: "node module import", pattern: /\b(?:node:)?(?:fs|child_process|net|tls|http|https|dns|dgram|worker_threads)\b/ }, // skipcq: SCT-A000
     { token: "eval", pattern: /\beval\b/ },
@@ -44,6 +51,7 @@ export function defineWorkflow(input) {
         ...(input.specification ? { specification: input.specification } : {}),
         ...(input.trigger ? { trigger: input.trigger } : {}),
         ...(input.inputSchema ? { inputSchema: input.inputSchema } : {}),
+        ...(input.maxCredits != null ? { maxCredits: input.maxCredits } : {}),
         steps: input.steps,
     };
 }
@@ -85,18 +93,49 @@ export function eventTrigger(input) {
         ...(input.status ? { status: input.status } : {}),
     };
 }
+// Lookahead window for the next cron run. Must exceed the largest gap a *valid*
+// schedule can have, or legitimate sparse crons get falsely rejected: the worst
+// case is "Feb 29" across a century boundary (e.g. 2096 → 2104, an ~8-year gap,
+// since 2100 is not a leap year). The day-skipping scan below keeps even this
+// wide window cheap (~one zonedDateParts call per non-matching day).
+const MAX_CRON_LOOKAHEAD_DAYS = 366 * 8 + 2;
 export function nextCronRunAfter(input) {
     const schedule = parseCronSchedule(input.cron);
     const timezone = input.timezone?.trim() || DEFAULT_WORKFLOW_CRON_TIMEZONE;
     let candidate = roundUpToNextMinute(input.after ?? new Date());
-    const deadline = candidate.getTime() + 370 * 24 * 60 * 60 * 1000;
+    const deadline = candidate.getTime() + MAX_CRON_LOOKAHEAD_DAYS * 24 * 60 * 60 * 1000;
     while (candidate.getTime() <= deadline) {
-        if (matchesCronSchedule(schedule, zonedDateParts(candidate, timezone))) {
+        const parts = zonedDateParts(candidate, timezone);
+        if (matchesCronSchedule(schedule, parts)) {
             return candidate;
         }
-        candidate = new Date(candidate.getTime() + 60_000);
+        // If the calendar date itself can't match, no minute that day matches —
+        // jump to the next day instead of scanning all 1440 minutes. This keeps
+        // sparse schedules (e.g. "0 9 29 2 *") and unsatisfiable ones fast over the
+        // multi-year window. The jump targets ~00:00 of the next day, so a
+        // subsequently matching date is scanned from its start (no missed minutes).
+        if (!matchesCronDate(schedule, parts)) {
+            const minutesToNextDay = Math.max(1, 24 * 60 - (parts.hour * 60 + parts.minute));
+            let next = new Date(candidate.getTime() + minutesToNextDay * 60_000);
+            // minutesToNextDay is a LOCAL-clock count added to a UTC instant. On a
+            // spring-forward day the local day is < 24h, so the jump overshoots the
+            // next local midnight and lands at ~01:00 — skipping an early-of-day match
+            // (e.g. "0 0 …"), which can push the next run a full year out. If the jump
+            // crossed into the next local day but past midnight, pull it back to that
+            // midnight. (A fall-back day is > 24h: the jump undershoots and stays on
+            // the same date, which the next iteration advances — left as-is.)
+            const landed = zonedDateParts(next, timezone);
+            const intoNextLocalDay = landed.hour * 60 + landed.minute;
+            if (landed.dayOfMonth !== parts.dayOfMonth && intoNextLocalDay > 0) {
+                next = new Date(next.getTime() - intoNextLocalDay * 60_000);
+            }
+            candidate = next;
+        }
+        else {
+            candidate = new Date(candidate.getTime() + 60_000);
+        }
     }
-    throw new Error("Cron expression has no matching run time in the next 370 days.");
+    throw new Error(`Cron expression has no matching run time in the next ${MAX_CRON_LOOKAHEAD_DAYS} days.`);
 }
 export function transformStep(input) {
     return {
@@ -116,9 +155,23 @@ export function toolStep(input) {
         tool: input.tool,
         ...(input.effect ? { effect: input.effect } : {}),
         ...(input.mode ? { mode: input.mode } : {}),
+        ...(input.maxCredits != null ? { maxCredits: input.maxCredits } : {}),
         payload: input.payload,
     };
 }
+/**
+ * Conditional step. `condition` is evaluated; control then flows by mode:
+ *
+ * - then only (no `else`, no `join`) — GUARD: truthy continues to `then` (steps
+ *   between the branch and `then` are skipped); falsy skips straight to the end
+ *   of the workflow (no step after the branch runs) and the run completes.
+ * - then + else (no `join`) — skip-until-target jump to `then`/`else`; from the
+ *   chosen target, the remaining steps run sequentially through the end.
+ * - then + else + join — real if/else: the non-chosen arm is skipped and `join`
+ *   is the convergence point where shared downstream work resumes.
+ *
+ * All targets must be ids of later steps (branches are forward-only).
+ */
 export function branchStep(input) {
     return {
         __oxygen_workflow_step: true,
@@ -161,6 +214,7 @@ definition, options = {}) {
         ...(definition.specification ? { specification: definition.specification } : {}),
         ...(definition.trigger ? { trigger: definition.trigger } : {}),
         ...(definition.inputSchema ? { input_schema: definition.inputSchema } : {}),
+        ...(definition.maxCredits != null ? { max_credits: definition.maxCredits } : {}),
         steps: definition.steps.map((step) => {
             if (step.kind === "transform") {
                 return {
@@ -188,6 +242,7 @@ definition, options = {}) {
                 tool: step.tool,
                 effect: step.effect ?? "external_read",
                 ...(step.mode ? { mode: step.mode } : {}),
+                ...(step.maxCredits != null ? { max_credits: step.maxCredits } : {}),
                 payload_source: serializeWorkflowFunction(step.payload, `steps.${step.id}.payload`),
             };
         }),
@@ -218,12 +273,23 @@ export function buildRecipeManifest(input) {
         bundle_format: "esm",
         tools_used: Array.from(new Set((input.toolsUsed ?? []).filter(Boolean))).sort(),
         ...(input.visualPlan ? { visual_plan: input.visualPlan } : {}),
+        ...(input.maxCredits != null ? { max_credits: input.maxCredits } : {}),
         source_hash: sourceHash,
         compiler_version: DURABLE_RECIPE_COMPILER_VERSION,
         created_at: (input.createdAt ?? new Date()).toISOString(),
     };
     return manifest;
 }
+// Shared positive-finite validator for the optional per-run / per-step
+// max_credits caps (Gap 2). `undefined` is valid (no cap); anything else must be
+// a positive finite number, or lint rejects the manifest.
+function validateOptionalMaxCredits(value, path, add) {
+    if (value === undefined)
+        return;
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        add(path, "invalid_max_credits", "max_credits must be a positive number.");
+    }
+}
 export function lintWorkflowManifest(// skipcq: JS-R1005
 value, options = {}) {
     if (isRecord(value)
@@ -255,6 +321,7 @@ value, options = {}) {
     }
     if (value.trigger !== undefined)
         validateTrigger(value.trigger, "$.trigger", add);
+    validateOptionalMaxCredits(value.max_credits, "$.max_credits", add);
     if (!Array.isArray(value.steps) || value.steps.length === 0) {
         add("$.steps", "missing_steps", "At least one workflow step is required.");
     }
@@ -278,6 +345,15 @@ value, options = {}) {
             if (!isNonEmptyString(step.id)) {
                 add(`${path}.id`, "invalid_step_id", "Step id is required.");
             }
+            else if (RESERVED_STEP_IDS.has(step.id)) {
+                // Step ids become keys on the ctx.steps object the runtime assembles.
+                // "__proto__" / "constructor" / "prototype" collide with JavaScript
+                // object internals: assigning ctx.steps["__proto__"] = output hits the
+                // prototype setter, so the output is silently dropped from step outputs
+                // and unreadable downstream while the run still reports success. Reject
+                // at authoring time instead of letting that data loss happen at runtime.
+                add(`${path}.id`, "reserved_step_id", `Step id '${step.id}' is reserved (it collides with a JavaScript object key and would be dropped from step outputs). Choose another id.`);
+            }
             else if (ids.has(step.id)) {
                 add(`${path}.id`, "duplicate_step_id", `Step id '${step.id}' is duplicated.`);
             }
@@ -320,6 +396,7 @@ value, options = {}) {
                     && step.mode !== "smoke_test") {
                     add(`${path}.mode`, "invalid_step_mode", "Step mode is invalid.");
                 }
+                validateOptionalMaxCredits(step.max_credits, `${path}.max_credits`, add);
                 return;
             }
             if (step.kind === "branch") {
@@ -390,6 +467,7 @@ value, options = {}) {
     if (value.bundle_format !== "esm") {
         add("$.bundle_format", "invalid_bundle_format", "Recipe bundle_format must be 'esm'.");
     }
+    validateOptionalMaxCredits(value.max_credits, "$.max_credits", add);
     if (value.runtime !== "durable") {
         add("$.runtime", "invalid_recipe_runtime", "Durable recipe manifests must set runtime to durable.");
     }
@@ -802,25 +880,52 @@ export async function runPureWorkflowFunction(input) {
     sandbox.setImmediate = undefined;
     sandbox.queueMicrotask = undefined;
     sandbox.WebAssembly = undefined;
-    const script = new vm.Script(`"use strict";\n`
-        + `const __oxygen_context = JSON.parse(__oxygen_context_json);\n`
+    const script = new vm.Script('"use strict";\n'
+        + 'const __oxygen_context = JSON.parse(__oxygen_context_json);\n'
         + `const __oxygen_fn = (${input.source});\n`
-        + `__oxygen_fn(__oxygen_context);`);
+        + '__oxygen_fn(__oxygen_context);');
     // Disable dynamic code generation in the sandboxed context. Combined with
     // the JSON re-parse above, this means every prototype-walk path to
     // Function — direct, via context.constructor.constructor, or any other
     // reachable Function instance — throws EvalError when called with source.
-    const result = script.runInNewContext(sandbox, {
-        timeout: timeoutMs,
-        contextCodeGeneration: {
-            strings: false,
-            wasm: false,
-        },
-    });
-    const resolved = isPromiseLike(result)
-        ? await withTimeout(result, timeoutMs)
-        : result;
-    return enforceJsonOutput(resolved, maxOutputBytes);
+    try {
+        const result = script.runInNewContext(sandbox, {
+            timeout: timeoutMs,
+            contextCodeGeneration: {
+                strings: false,
+                wasm: false,
+            },
+        });
+        const resolved = isPromiseLike(result)
+            ? await withTimeout(result, timeoutMs)
+            : result;
+        return enforceJsonOutput(resolved, maxOutputBytes);
+    }
+    catch (error) {
+        throw normalizeSandboxThrow(error);
+    }
+}
+// A throw from inside the vm sandbox is constructed with the sandbox realm's
+// Error, so `error instanceof Error` is false in the host worker — and
+// serializeOxygenError then drops the message and reports a generic
+// "Workflow run failed.", leaving a failing transform/branch undebuggable.
+// Reconstruct a host-realm Error preserving the user's message/name. Host-realm
+// throws (vm timeout, enforceJsonOutput's workflow_output_too_large) already
+// pass instanceof and are returned unchanged.
+function normalizeSandboxThrow(error) {
+    if (error instanceof Error)
+        return error;
+    if (error && typeof error === "object") {
+        const record = error;
+        const message = typeof record.message === "string" && record.message
+            ? record.message
+            : "Workflow function threw.";
+        const normalized = new Error(message);
+        if (typeof record.name === "string" && record.name)
+            normalized.name = record.name;
+        return normalized;
+    }
+    return new Error(typeof error === "string" && error ? error : "Workflow function threw a non-error value.");
 }
 export const workflowApplySchema = {
     $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -1077,6 +1182,19 @@ value, path, add) {
                 add(`${path}.cron`, "invalid_cron", error instanceof Error ? error.message : "Cron expression is invalid.");
             }
         }
+        // Validate the timezone here so an unknown zone fails lint with a typed
+        // issue, rather than passing lint and blowing up at apply time (the
+        // scheduler's Intl.DateTimeFormat throws on an unknown zone). null/empty
+        // are allowed — the scheduler falls back to UTC.
+        const { timezone } = value;
+        if (timezone !== undefined && timezone !== null) {
+            if (typeof timezone !== "string") {
+                add(`${path}.timezone`, "invalid_timezone", "Cron trigger timezone must be a string IANA timezone.");
+            }
+            else if (timezone.trim() && !isValidTimeZone(timezone.trim())) {
+                add(`${path}.timezone`, "invalid_timezone", `Unknown timezone '${timezone}'. Use an IANA timezone such as 'America/New_York' or 'UTC'.`);
+            }
+        }
         return;
     }
     if (value.type === "event") {
@@ -1272,11 +1390,9 @@ function normalizeDaysOfWeek(values) {
     }
     return normalized;
 }
-function matchesCronSchedule(schedule, parts) {
-    if (!schedule.minutes.has(parts.minute))
-        return false;
-    if (!schedule.hours.has(parts.hour))
-        return false;
+// Date-only match (month + day-of-month/day-of-week), excluding hour/minute.
+// Lets nextCronRunAfter skip whole non-matching days in one jump.
+function matchesCronDate(schedule, parts) {
     if (!schedule.months.has(parts.month))
         return false;
     const dayOfMonthMatches = schedule.daysOfMonth.has(parts.dayOfMonth);
@@ -1286,6 +1402,13 @@ function matchesCronSchedule(schedule, parts) {
     }
     return dayOfMonthMatches && dayOfWeekMatches;
 }
+function matchesCronSchedule(schedule, parts) {
+    if (!schedule.minutes.has(parts.minute))
+        return false;
+    if (!schedule.hours.has(parts.hour))
+        return false;
+    return matchesCronDate(schedule, parts);
+}
 function roundUpToNextMinute(value) {
     const result = new Date(value.getTime());
     result.setUTCSeconds(0, 0);
@@ -1309,6 +1432,17 @@ function zonedDateParts(date, timezone) {
         dayOfWeek: weekdayToNumber(parts.get("weekday") ?? ""),
     };
 }
+function isValidTimeZone(timezone) {
+    try {
+        // Throws RangeError for an unknown IANA zone; same mechanism the scheduler
+        // uses, so lint accepts exactly the zones the runtime can resolve.
+        new Intl.DateTimeFormat("en-US", { timeZone: timezone }).format(0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function getZonedFormatter(timezone) {
     const cached = zonedFormatters.get(timezone);
     if (cached)
@@ -1349,6 +1483,25 @@ function weekdayToNumber(value) {
 function hashWorkflowSource(source) {
     return createHash("sha256").update(source).digest("hex");
 }
+// Deterministic plan hash (Gap 4): binds an approval decision to the exact
+// reviewed plan + cost so it cannot be replayed against a changed plan. The
+// durable mid-run approval gate (recipe-context) hashes its relevant fields
+// through this; binding the imperative `workflows call` admission path the same
+// way is a flagged follow-up. Canonical (sorted-key) JSON keeps the hash stable
+// regardless of key order or undefined fields.
+export function computeWorkflowPlanHash(input) {
+    return hashWorkflowSource(canonicalJsonStringify(input));
+}
+function canonicalJsonStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJsonStringify).join(",")}]`;
+    const entries = Object.entries(value)
+        .filter(([, entryValue]) => entryValue !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([key, entryValue]) => `${JSON.stringify(key)}:${canonicalJsonStringify(entryValue)}`).join(",")}}`;
+}
 function workflowJsonReplacer(_key, value) {
     return typeof value === "function" ? Function.prototype.toString.call(value) : value;
 }
@@ -1416,6 +1569,28 @@ export function readWorkflowRunMaxCredits(metadata) {
         return null;
     return parsed;
 }
+// Approval labels the run's enqueue route already collected SYNCHRONOUS human
+// approval for (a CLI/MCP `approved=true` gate before the run was created), and
+// recorded in run metadata as `preapproved_labels`. A live ctx.approvals.require()
+// call whose `label` is in this set is honored immediately by both recipe
+// executors instead of parking on a durable decision row (local) or failing
+// closed with approval_requires_local_executor (sandbox). Every other label
+// still goes through the full durable gate, and the max_credits spend cap is
+// enforced separately per paid tool step, so a pre-approved label never widens
+// spend. Only trusted server code (the enqueue route) sets this — it is read
+// from run metadata, never from user-suppliable workflow input.
+export function readWorkflowRunPreApprovedLabels(metadata) {
+    if (!isRecord(metadata))
+        return [];
+    const raw = metadata.preapproved_labels ?? metadata.preApprovedLabels;
+    if (!Array.isArray(raw))
+        return [];
+    const labels = raw
+        .filter((entry) => typeof entry === "string")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    return Array.from(new Set(labels));
+}
 // Managed tool runs attach `meta.billing` with the credits the run charged
 // (`managed_credit_estimate` is reserved and captured in full). BYOK and
 // user-connection runs consume no OXYGEN credits, so they never count

package/oxygen.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./dist/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxygen-agent/cli",
-  "version": "1.177.1",
+  "version": "1.209.6",
   "private": false,
   "license": "UNLICENSED",
   "type": "module",
@@ -12,7 +12,7 @@
     "directory": "packages/cli"
   },
   "bin": {
-    "oxygen": "./dist/index.js"
+    "oxygen": "./oxygen.js"
   },
   "exports": {
     ".": {