@withone/cli 1.23.0 → 1.25.0

package/dist/{chunk-Z45IBT5P.js → chunk-ONGJ2QKB.js}

@@ -447,6 +447,22 @@ var execAsync = promisify(exec);
 function sleep2(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+var StepTimeoutError = class extends Error {
+  errorCode = "TIMEOUT";
+  constructor(stepId, timeoutMs) {
+    super(`Step "${stepId}" exceeded timeout of ${timeoutMs}ms`);
+    this.name = "StepTimeoutError";
+  }
+};
+function withTimeout(promise, timeoutMs, stepId) {
+  let timer;
+  const timeoutPromise = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new StepTimeoutError(stepId, timeoutMs)), timeoutMs);
+  });
+  return Promise.race([promise, timeoutPromise]).finally(() => {
+    if (timer) clearTimeout(timer);
+  });
+}
 function computeRetryDelay(onError, attempt) {
   const base = onError.retryDelayMs ?? 1e3;
   const max = onError.maxDelayMs ?? 3e4;
@@ -898,7 +914,7 @@ async function executeSubflowStep(step, context, api, permissions, allowedAction
   if (flowStack.includes(resolvedKey)) {
     throw new Error(`Circular flow detected: ${[...flowStack, resolvedKey].join(" \u2192 ")}`);
   }
-  const { loadFlowWithMeta: loadFlowWithMeta2 } = await import("./flow-runner-DFUFU2LM.js");
+  const { loadFlowWithMeta: loadFlowWithMeta2 } = await import("./flow-runner-MXRNWG4Y.js");
   const { flow: subFlow, rootDir: subRootDir } = loadFlowWithMeta2(resolvedKey);
   const subContext = await executeFlow(
     subFlow,
@@ -910,10 +926,35 @@ async function executeSubflowStep(step, context, api, permissions, allowedAction
     void 0,
     [...flowStack, resolvedKey]
   );
+  const finalStep = subFlow.steps[subFlow.steps.length - 1];
+  const finalOutput = finalStep ? subContext.steps[finalStep.id]?.output : void 0;
+  let flattenedOutput;
+  if (finalOutput && typeof finalOutput === "object" && !Array.isArray(finalOutput)) {
+    const collisions = Object.keys(finalOutput).filter(
+      (k) => k in subContext.steps
+    );
+    if (collisions.length > 0) {
+      options.onEvent?.({
+        event: "flow:warning",
+        message: `Sub-flow "${resolvedKey}" final step output fields [${collisions.join(", ")}] collide with sub-step ids \u2014 flattened fields take precedence.`
+      });
+    }
+    flattenedOutput = {
+      ...subContext.steps,
+      ...finalOutput,
+      _steps: subContext.steps
+    };
+  } else {
+    flattenedOutput = {
+      ...subContext.steps,
+      _steps: subContext.steps,
+      ...finalOutput !== void 0 ? { _finalOutput: finalOutput } : {}
+    };
+  }
   return {
     status: "success",
-    output: subContext.steps,
-    response: subContext.steps
+    output: flattenedOutput,
+    response: flattenedOutput
   };
 }
 async function executePaginateStep(step, context, api, permissions, allowedActionIds, options) {
@@ -986,6 +1027,35 @@ async function executeBashStep(step, context, options) {
     response: { stdout: stdout.trim(), stderr: stderr.trim(), exitCode: 0 }
   };
 }
+function isMissing(value) {
+  if (value === void 0 || value === null) return true;
+  if (typeof value === "string" && value.length === 0) return true;
+  if (Array.isArray(value) && value.length === 0) return true;
+  return false;
+}
+function explainMissing(selector, context) {
+  const parts = selector.slice(2).split(".");
+  if (parts[0] !== "steps" || parts.length < 2) return "";
+  const stepId = parts[1].replace(/\[.*$/, "");
+  const upstream = context.steps[stepId];
+  if (!upstream) return ` (upstream step "${stepId}" has not run)`;
+  if (upstream.status === "skipped") return ` (upstream step "${stepId}" was skipped)`;
+  if (upstream.status === "failed") return ` (upstream step "${stepId}" failed: ${upstream.error ?? "unknown error"})`;
+  if (upstream.status === "timeout") return ` (upstream step "${stepId}" timed out)`;
+  return "";
+}
+function checkRequires(step, context) {
+  if (!step.requires || step.requires.length === 0) return;
+  for (const selector of step.requires) {
+    const value = resolveSelector(selector, context);
+    if (isMissing(value)) {
+      const why = explainMissing(selector, context);
+      throw new Error(
+        `Step "${step.id}" requires ${selector} but it resolved to ${value === void 0 ? "undefined" : value === null ? "null" : Array.isArray(value) ? "an empty array" : "an empty string"}${why}`
+      );
+    }
+  }
+}
 async function executeSingleStep(step, context, api, permissions, allowedActionIds, options, flowStack = []) {
   if (step.if) {
     const condResult = evaluateExpression(step.if, context);
@@ -1019,6 +1089,7 @@ async function executeSingleStep(step, context, api, permissions, allowedActionI
         });
         await sleep2(delay);
       }
+      checkRequires(step, context);
       if (options.mock && (step.type === "action" || step.type === "paginate" || step.type === "bash")) {
         const resolvedConfig = step[step.type] ? resolveValue(step[step.type], context) : {};
         options.onEvent?.({ event: "step:mock", stepId: step.id, type: step.type, config: resolvedConfig });
@@ -1031,47 +1102,37 @@ async function executeSingleStep(step, context, api, permissions, allowedActionI
         context.steps[step.id] = result2;
         return result2;
       }
-      let result;
-      switch (step.type) {
-        case "action":
-          result = await executeActionStep(step, context, api, permissions, allowedActionIds);
-          break;
-        case "transform":
-          result = executeTransformStep(step, context);
-          break;
-        case "code":
-          result = await executeCodeStep(step, context, options);
-          break;
-        case "condition":
-          result = await executeConditionStep(step, context, api, permissions, allowedActionIds, options, flowStack);
-          break;
-        case "loop":
-          result = await executeLoopStep(step, context, api, permissions, allowedActionIds, options, flowStack);
-          break;
-        case "parallel":
-          result = await executeParallelStep(step, context, api, permissions, allowedActionIds, options, flowStack);
-          break;
-        case "file-read":
-          result = executeFileReadStep(step, context);
-          break;
-        case "file-write":
-          result = executeFileWriteStep(step, context);
-          break;
-        case "while":
-          result = await executeWhileStep(step, context, api, permissions, allowedActionIds, options, flowStack);
-          break;
-        case "flow":
-          result = await executeSubflowStep(step, context, api, permissions, allowedActionIds, options, flowStack);
-          break;
-        case "paginate":
-          result = await executePaginateStep(step, context, api, permissions, allowedActionIds, options);
-          break;
-        case "bash":
-          result = await executeBashStep(step, context, options);
-          break;
-        default:
-          throw new Error(`Unknown step type: ${step.type}`);
-      }
+      const dispatch = async () => {
+        switch (step.type) {
+          case "action":
+            return await executeActionStep(step, context, api, permissions, allowedActionIds);
+          case "transform":
+            return executeTransformStep(step, context);
+          case "code":
+            return await executeCodeStep(step, context, options);
+          case "condition":
+            return await executeConditionStep(step, context, api, permissions, allowedActionIds, options, flowStack);
+          case "loop":
+            return await executeLoopStep(step, context, api, permissions, allowedActionIds, options, flowStack);
+          case "parallel":
+            return await executeParallelStep(step, context, api, permissions, allowedActionIds, options, flowStack);
+          case "file-read":
+            return executeFileReadStep(step, context);
+          case "file-write":
+            return executeFileWriteStep(step, context);
+          case "while":
+            return await executeWhileStep(step, context, api, permissions, allowedActionIds, options, flowStack);
+          case "flow":
+            return await executeSubflowStep(step, context, api, permissions, allowedActionIds, options, flowStack);
+          case "paginate":
+            return await executePaginateStep(step, context, api, permissions, allowedActionIds, options);
+          case "bash":
+            return await executeBashStep(step, context, options);
+          default:
+            throw new Error(`Unknown step type: ${step.type}`);
+        }
+      };
+      const result = step.timeoutMs ? await withTimeout(dispatch(), step.timeoutMs, step.id) : await dispatch();
       result.durationMs = Date.now() - startTime;
       if (attempt > 1) {
         result.retries = attempt - 1;
@@ -1093,10 +1154,13 @@ async function executeSingleStep(step, context, api, permissions, allowedActionI
   const errorMessage = lastError?.message || "Unknown error";
   const strategy = step.onError?.strategy || "fail";
   const retriesUsed = Math.max(0, maxAttempts - 1);
+  const isTimeout = lastError instanceof StepTimeoutError;
+  const errorCode = lastError?.errorCode;
   if (strategy === "continue") {
     const result = {
-      status: "failed",
+      status: isTimeout ? "timeout" : "failed",
       error: errorMessage,
+      ...errorCode ? { errorCode } : {},
       durationMs: Date.now() - startTime,
       retries: retriesUsed
     };
@@ -1105,8 +1169,9 @@ async function executeSingleStep(step, context, api, permissions, allowedActionI
   }
   if (strategy === "fallback" && step.onError?.fallbackStepId) {
     const result = {
-      status: "failed",
+      status: isTimeout ? "timeout" : "failed",
       error: errorMessage,
+      ...errorCode ? { errorCode } : {},
       durationMs: Date.now() - startTime,
       retries: retriesUsed
     };
@@ -1243,7 +1308,9 @@ var FLOW_SCHEMA = {
     name: { type: "string", required: true, description: "Human-readable step label" },
     type: { type: "string", required: true, description: "Step type (determines which config object is required)" },
     if: { type: "string", required: false, description: "JS expression \u2014 skip step if falsy" },
-    unless: { type: "string", required: false, description: "JS expression \u2014 skip step if truthy" }
+    unless: { type: "string", required: false, description: "JS expression \u2014 skip step if truthy" },
+    timeoutMs: { type: "number", required: false, description: 'Wall-clock timeout (ms). On expiry the step fails with errorCode:"TIMEOUT"; with onError:continue the result gets status:"timeout".' },
+    requires: { type: "array", required: false, description: "Presence preconditions: array of $.input.X or $.steps.X.output... selectors that must resolve to a non-empty value before the step runs. Failures honor onError." }
   },
   stepTypes: [
     {
@@ -1751,6 +1818,39 @@ Every completed step produces both \`output\` and \`response\`:
 - **Code/transform steps**: \`output\` is the return value. \`response\` is an alias for \`output\`.
 - **In practice**: Use \`$.steps.stepId.response\` for action steps (API data) and \`$.steps.stepId.output\` for code/transform steps (computed data). Both work interchangeably, but using the semantically correct one makes flows easier to read.
 
+### Step result metadata (\`status\`, \`error\`, \`errorCode\`)
+
+Every step result also exposes execution metadata that downstream steps can inspect:
+
+| Field | Values | When set |
+|-------|--------|----------|
+| \`$.steps.X.status\` | \`"success"\` \\| \`"skipped"\` \\| \`"failed"\` \\| \`"timeout"\` | Always |
+| \`$.steps.X.error\` | error message string | When status is \`failed\` or \`timeout\` |
+| \`$.steps.X.errorCode\` | machine-readable code (e.g. \`"TIMEOUT"\`) | When the error has a code |
+| \`$.steps.X.durationMs\` | number | Always |
+| \`$.steps.X.retries\` | number | When the step was retried |
+
+This lets downstream steps distinguish \`skipped\` (\`if\` condition false) from \`failed\` (error, \`onError:continue\`) from \`timeout\` (exceeded \`timeoutMs\`) \u2014 e.g. \`"if": "$.steps.enrichment.status === 'timeout'"\` to retry with a longer window.
+
+### Sub-flow output (flattened)
+
+When a step has \`type: "flow"\`, the sub-flow's final step output is flattened onto the parent step's \`output\`:
+
+\`\`\`jsonc
+// Sub-flow "sub-consts" has a final step "load" that returns { CHART_URL, API_KEY }
+
+// Preferred (flattened):
+"{{$.steps.loadConfig.output.CHART_URL}}"
+
+// Legacy nested path (still works for backward compatibility):
+"{{$.steps.loadConfig.output.load.output.CHART_URL}}"
+
+// Escape hatch for programmatic access to the full sub-flow steps map:
+"{{$.steps.loadConfig.output._steps.load.output.CHART_URL}}"
+\`\`\`
+
+If a sub-step id collides with a flattened field name, the flattened field wins and the engine emits a \`flow:warning\` event.
+
 ## Error Handling
 
 \`\`\`json

package/dist/{flow-runner-DFUFU2LM.js → flow-runner-MXRNWG4Y.js}

@@ -11,7 +11,7 @@ import {
   saveFlow,
   summarizeFlowInputs,
   walkSteps
-} from "./chunk-Z45IBT5P.js";
+} from "./chunk-ONGJ2QKB.js";
 export {
   FlowRunner,
   collectStepTypes,

package/dist/index.js

@@ -16,7 +16,7 @@ import {
   loadFlowWithMeta,
   resolveFlowPath,
   saveFlow
-} from "./chunk-Z45IBT5P.js";
+} from "./chunk-ONGJ2QKB.js";
 
 // src/index.ts
 import { createRequire as createRequire2 } from "module";
@@ -2320,6 +2320,20 @@ function validateStepsArray(steps, pathPrefix, errors) {
       errors.push({ path: `${path8}.type`, message: `Step type must be one of: ${validTypes.join(", ")}` });
       continue;
     }
+    if (s.requires !== void 0) {
+      if (!Array.isArray(s.requires)) {
+        errors.push({ path: `${path8}.requires`, message: '"requires" must be an array of selector strings (e.g. ["$.steps.foo.output.bar"])' });
+      } else {
+        for (let r = 0; r < s.requires.length; r++) {
+          const sel = s.requires[r];
+          if (typeof sel !== "string") {
+            errors.push({ path: `${path8}.requires[${r}]`, message: '"requires" entry must be a selector string' });
+          } else if (!sel.startsWith("$.")) {
+            errors.push({ path: `${path8}.requires[${r}]`, message: `"requires" entry "${sel}" must be a selector starting with "$." (e.g. "$.steps.foo.output.bar")` });
+          }
+        }
+      }
+    }
     if (s.onError && typeof s.onError === "object") {
       const oe = s.onError;
       if (!FLOW_SCHEMA.errorStrategies.includes(oe.strategy)) {
@@ -2529,6 +2543,14 @@ function validateSelectorReferences(flow2) {
   function checkStep(step, pathPrefix, preceding2) {
     if (step.if) checkSelectors(extractSelectors(step.if), `${pathPrefix}.if`, preceding2);
     if (step.unless) checkSelectors(extractSelectors(step.unless), `${pathPrefix}.unless`, preceding2);
+    if (Array.isArray(step.requires)) {
+      const reqs = step.requires;
+      reqs.forEach((sel, i) => {
+        if (typeof sel === "string" && sel.startsWith("$.")) {
+          checkSelectors([sel], `${pathPrefix}.requires[${i}]`, preceding2);
+        }
+      });
+    }
     const descriptor = getStepTypeDescriptor(step.type);
     if (descriptor) {
       const config2 = step[descriptor.configKey];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/cli",
-  "version": "1.23.0",
+  "version": "1.25.0",
   "description": "CLI for managing One",
   "type": "module",
   "files": [

package/skills/one/references/flows.md

@@ -424,6 +424,35 @@ Alternatively, pass values as environment variables (also shell-safe) and refere
 }
 ```
 
+## Step Input Contracts (`requires`)
+
+Declare the data a step depends on so the engine fails fast — with a useful error — when an upstream value is missing. Without `requires`, a skipped or failed upstream step silently leaves `undefined` in the context and the consumer either crashes deep in user code or burns an LLM call on empty input.
+
+```json
+{
+  "id": "summarizeFounder",
+  "type": "code",
+  "requires": [
+    "$.steps.fetchProfile.output.bio",
+    "$.input.founderName"
+  ],
+  "code": { "module": "lib/summarize.mjs" }
+}
+```
+
+Each entry is a `$.input.X` or `$.steps.X.output...` selector. A selector is considered missing when it resolves to `undefined`, `null`, `""`, or `[]` (empty objects are allowed). On a miss, the engine throws **before** the step runs:
+
+```
+Step "summarizeFounder" requires $.steps.fetchProfile.output.bio but it
+resolved to undefined (upstream step "fetchProfile" was skipped)
+```
+
+The "because…" suffix tells you exactly why — skipped, failed, or timed out — so you can fix the upstream wiring instead of guessing.
+
+`requires` failures honor the step's `onError` strategy: pair `requires` with `onError: { strategy: "continue" }` to skip optional consumers gracefully, or leave the default `fail` to halt the flow on contract violations.
+
+Forward references are caught at flow load time: if `requires` points at a step declared after the current step, validation rejects the flow.
+
 ## Error Handling
 
 ```json