@particle-academy/fancy-flow 0.14.0 → 0.15.1

package/dist/llm/vercel-ai.d.cts

@@ -1,6 +1,6 @@
 import { LanguageModel } from 'ai';
-import { L as LlmRouteRequest, a as LlmClient } from '../capabilities-D-V9Rxv1.cjs';
-import '../types-fc0fFKkf.cjs';
+import { L as LlmRouteRequest, a as LlmClient } from '../capabilities-BEbLqnJU.cjs';
+import '../types-sOmpCitB.cjs';
 import '@xyflow/react';
 
 /**

package/dist/llm/vercel-ai.d.ts

@@ -1,6 +1,6 @@
 import { LanguageModel } from 'ai';
-import { L as LlmRouteRequest, a as LlmClient } from '../capabilities-B6r1Snfj.js';
-import '../types-fc0fFKkf.js';
+import { L as LlmRouteRequest, a as LlmClient } from '../capabilities-CI3gw0C7.js';
+import '../types-sOmpCitB.js';
 import '@xyflow/react';
 
 /**

package/dist/pause-9iT4tCEV.d.cts

@@ -0,0 +1,96 @@
+/**
+ * The human-pause contract.
+ *
+ * A workflow that waits for a person is not an error, but it travels the same
+ * channel as one: the executor aborts, the engine records a reason string, and
+ * the durable runner decides whether that string meant "failed" or "waiting".
+ *
+ * That seam existed before this module, as two `str_starts_with` checks in the
+ * Laravel run job against constants owned by two BUILTIN executors. It worked,
+ * and it was invisible: a third-party human-input node had no way to announce
+ * that it pauses, and nothing stopped a refactor from removing the mechanism
+ * out from under published packages. Reported by the MOIC Suite consumer, who
+ * needed exactly that and had to reach for a private constant to get it.
+ *
+ * So the encoding is now public, typed, and versioned by prefix rather than
+ * implied. The wire format stays a plain string on purpose — it survives the
+ * existing abort → `RunResult.error` path unchanged, crosses a queue boundary,
+ * and decodes identically in PHP, none of which a thrown class would do.
+ *
+ * @see decodePause — the one function a durable runner needs.
+ */
+/**
+ * What the run is waiting for.
+ *
+ * `approval` and `input` are the shapes both runtimes ship. The type stays open
+ * because the whole point is that a marketplace node can define its own —
+ * a signature step, a payment confirmation, a review queue — and a runner that
+ * does not recognise one should report it rather than guess.
+ */
+type PauseAwaiting = "approval" | "input" | (string & {});
+/** A run halted, waiting for a person. */
+type PauseSignal = {
+    /** The node that paused — where a submission gets injected on resume. */
+    nodeId: string;
+    awaiting: PauseAwaiting;
+    /**
+     * Kind-supplied context for whoever renders the wait — a form schema, the
+     * question being asked, a diff to approve. Must be JSON-serializable: it
+     * crosses a queue boundary and, for durable runs, a database column.
+     */
+    detail?: unknown;
+};
+/** Marks a reason string as a pause rather than a failure. */
+declare const PAUSE_PREFIX = "fancy-flow:pause:";
+/**
+ * Reason prefixes shipped before this contract, kept decodable forever.
+ *
+ * These are what `DurableApprovalExecutor` and `DurableUserInputExecutor`
+ * emitted, and they are written into the `error` column of every run that
+ * paused under an older version. Dropping them would strand those runs
+ * mid-flight — a resume path that only works for new runs is not a resume path.
+ */
+declare const LEGACY_PAUSE_PREFIXES: ReadonlyArray<readonly [string, PauseAwaiting]>;
+/**
+ * Encode a pause as the reason string an executor aborts with.
+ *
+ * The payload is JSON rather than delimited fields because a node id may
+ * contain a colon, and a positional encoding that breaks on user data is the
+ * kind of bug that only shows up in someone else's graph.
+ */
+declare function encodePause(signal: PauseSignal): string;
+/**
+ * Decode a run's error reason into a pause, or null if it was a real failure.
+ *
+ * This is the whole contract from a runner's side: call it on `result.error`,
+ * and if it returns non-null, persist the run as waiting on `signal.nodeId`
+ * instead of failing it. Accepts the legacy prefixes, so a runner written
+ * against this handles runs that paused under an older version.
+ */
+declare function decodePause(reason: string | null | undefined): PauseSignal | null;
+/** True when a run's error reason is actually a pause. */
+declare function isPause(reason: string | null | undefined): boolean;
+/**
+ * Abort the current node as a pause.
+ *
+ * Called from inside an executor with its own context. Node authors should
+ * reach for this rather than hand-encoding a reason, so the format stays ours
+ * to change:
+ *
+ * ```ts
+ * const values = ctx.inputs.values;
+ * if (values === undefined) pauseForHuman(ctx, "input", { fields });
+ * return values;
+ * ```
+ *
+ * Note the `undefined` check — an empty submission (`{}`) is a real answer and
+ * must resume. Truthiness here pauses forever on an empty form.
+ */
+declare function pauseForHuman(ctx: {
+    node: {
+        id: string;
+    };
+    abort: (reason?: string) => never;
+}, awaiting: PauseAwaiting, detail?: unknown): never;
+
+export { LEGACY_PAUSE_PREFIXES as L, type PauseAwaiting as P, PAUSE_PREFIX as a, type PauseSignal as b, decodePause as d, encodePause as e, isPause as i, pauseForHuman as p };

package/dist/pause-9iT4tCEV.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The human-pause contract.
+ *
+ * A workflow that waits for a person is not an error, but it travels the same
+ * channel as one: the executor aborts, the engine records a reason string, and
+ * the durable runner decides whether that string meant "failed" or "waiting".
+ *
+ * That seam existed before this module, as two `str_starts_with` checks in the
+ * Laravel run job against constants owned by two BUILTIN executors. It worked,
+ * and it was invisible: a third-party human-input node had no way to announce
+ * that it pauses, and nothing stopped a refactor from removing the mechanism
+ * out from under published packages. Reported by the MOIC Suite consumer, who
+ * needed exactly that and had to reach for a private constant to get it.
+ *
+ * So the encoding is now public, typed, and versioned by prefix rather than
+ * implied. The wire format stays a plain string on purpose — it survives the
+ * existing abort → `RunResult.error` path unchanged, crosses a queue boundary,
+ * and decodes identically in PHP, none of which a thrown class would do.
+ *
+ * @see decodePause — the one function a durable runner needs.
+ */
+/**
+ * What the run is waiting for.
+ *
+ * `approval` and `input` are the shapes both runtimes ship. The type stays open
+ * because the whole point is that a marketplace node can define its own —
+ * a signature step, a payment confirmation, a review queue — and a runner that
+ * does not recognise one should report it rather than guess.
+ */
+type PauseAwaiting = "approval" | "input" | (string & {});
+/** A run halted, waiting for a person. */
+type PauseSignal = {
+    /** The node that paused — where a submission gets injected on resume. */
+    nodeId: string;
+    awaiting: PauseAwaiting;
+    /**
+     * Kind-supplied context for whoever renders the wait — a form schema, the
+     * question being asked, a diff to approve. Must be JSON-serializable: it
+     * crosses a queue boundary and, for durable runs, a database column.
+     */
+    detail?: unknown;
+};
+/** Marks a reason string as a pause rather than a failure. */
+declare const PAUSE_PREFIX = "fancy-flow:pause:";
+/**
+ * Reason prefixes shipped before this contract, kept decodable forever.
+ *
+ * These are what `DurableApprovalExecutor` and `DurableUserInputExecutor`
+ * emitted, and they are written into the `error` column of every run that
+ * paused under an older version. Dropping them would strand those runs
+ * mid-flight — a resume path that only works for new runs is not a resume path.
+ */
+declare const LEGACY_PAUSE_PREFIXES: ReadonlyArray<readonly [string, PauseAwaiting]>;
+/**
+ * Encode a pause as the reason string an executor aborts with.
+ *
+ * The payload is JSON rather than delimited fields because a node id may
+ * contain a colon, and a positional encoding that breaks on user data is the
+ * kind of bug that only shows up in someone else's graph.
+ */
+declare function encodePause(signal: PauseSignal): string;
+/**
+ * Decode a run's error reason into a pause, or null if it was a real failure.
+ *
+ * This is the whole contract from a runner's side: call it on `result.error`,
+ * and if it returns non-null, persist the run as waiting on `signal.nodeId`
+ * instead of failing it. Accepts the legacy prefixes, so a runner written
+ * against this handles runs that paused under an older version.
+ */
+declare function decodePause(reason: string | null | undefined): PauseSignal | null;
+/** True when a run's error reason is actually a pause. */
+declare function isPause(reason: string | null | undefined): boolean;
+/**
+ * Abort the current node as a pause.
+ *
+ * Called from inside an executor with its own context. Node authors should
+ * reach for this rather than hand-encoding a reason, so the format stays ours
+ * to change:
+ *
+ * ```ts
+ * const values = ctx.inputs.values;
+ * if (values === undefined) pauseForHuman(ctx, "input", { fields });
+ * return values;
+ * ```
+ *
+ * Note the `undefined` check — an empty submission (`{}`) is a real answer and
+ * must resume. Truthiness here pauses forever on an empty form.
+ */
+declare function pauseForHuman(ctx: {
+    node: {
+        id: string;
+    };
+    abort: (reason?: string) => never;
+}, awaiting: PauseAwaiting, detail?: unknown): never;
+
+export { LEGACY_PAUSE_PREFIXES as L, type PauseAwaiting as P, PAUSE_PREFIX as a, type PauseSignal as b, decodePause as d, encodePause as e, isPause as i, pauseForHuman as p };

package/dist/registry/index.d.cts

@@ -1,8 +1,9 @@
-import { a as NodeKindDefinition, P as PortSpec } from '../types-H60tQAxr.cjs';
-export { C as ConfigField, b as CredentialConfigField, D as DocumentConfigField, E as ExpressionConfigField, J as JsonConfigField, K as KeyValueConfigField, N as NodeCategory, c as NumberConfigField, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField, S as SelectConfigField, f as SwitchConfigField, T as TextConfigField, g as TextareaConfigField } from '../types-H60tQAxr.cjs';
-import { a as FlowNode, P as PortDescriptor, N as NodeExecutor } from '../types-fc0fFKkf.cjs';
-import { b as LlmRoute } from '../capabilities-D-V9Rxv1.cjs';
-export { C as CapabilityId, a as LlmClient, c as LlmRouteChoice, L as LlmRouteRequest, W as WorkflowResolver, d as capabilityStatus, g as getLlmClient, e as getWorkflowResolver, r as registerLlmClient, f as registerWorkflowResolver } from '../capabilities-D-V9Rxv1.cjs';
+import { a as NodeKindDefinition, P as PortSpec } from '../types-D_jOR3Z2.cjs';
+export { C as ConfigField, b as CredentialConfigField, D as DocumentConfigField, E as ExpressionConfigField, J as JsonConfigField, K as KeyValueConfigField, N as NodeCategory, c as NumberConfigField, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField, S as SelectConfigField, f as SwitchConfigField, T as TextConfigField, g as TextareaConfigField } from '../types-D_jOR3Z2.cjs';
+import { b as FlowNode, P as PortDescriptor, N as NodeExecutor } from '../types-sOmpCitB.cjs';
+import { b as LlmRoute } from '../capabilities-BEbLqnJU.cjs';
+export { C as CapabilityId, a as LlmClient, c as LlmRouteChoice, L as LlmRouteRequest, W as WorkflowResolver, d as capabilityStatus, g as getLlmClient, e as getWorkflowResolver, r as registerLlmClient, f as registerWorkflowResolver } from '../capabilities-BEbLqnJU.cjs';
+export { L as LEGACY_PAUSE_PREFIXES, a as PAUSE_PREFIX, P as PauseAwaiting, b as PauseSignal, d as decodePause, e as encodePause, i as isPause, p as pauseForHuman } from '../pause-9iT4tCEV.cjs';
 import * as react from 'react';
 import { ComponentType, ReactNode } from 'react';
 import { NodeProps, NodeTypes } from '@xyflow/react';

package/dist/registry/index.d.ts

@@ -1,8 +1,9 @@
-import { a as NodeKindDefinition, P as PortSpec } from '../types-CnnKPnpt.js';
-export { C as ConfigField, b as CredentialConfigField, D as DocumentConfigField, E as ExpressionConfigField, J as JsonConfigField, K as KeyValueConfigField, N as NodeCategory, c as NumberConfigField, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField, S as SelectConfigField, f as SwitchConfigField, T as TextConfigField, g as TextareaConfigField } from '../types-CnnKPnpt.js';
-import { a as FlowNode, P as PortDescriptor, N as NodeExecutor } from '../types-fc0fFKkf.js';
-import { b as LlmRoute } from '../capabilities-B6r1Snfj.js';
-export { C as CapabilityId, a as LlmClient, c as LlmRouteChoice, L as LlmRouteRequest, W as WorkflowResolver, d as capabilityStatus, g as getLlmClient, e as getWorkflowResolver, r as registerLlmClient, f as registerWorkflowResolver } from '../capabilities-B6r1Snfj.js';
+import { a as NodeKindDefinition, P as PortSpec } from '../types-NerkPtHS.js';
+export { C as ConfigField, b as CredentialConfigField, D as DocumentConfigField, E as ExpressionConfigField, J as JsonConfigField, K as KeyValueConfigField, N as NodeCategory, c as NumberConfigField, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField, S as SelectConfigField, f as SwitchConfigField, T as TextConfigField, g as TextareaConfigField } from '../types-NerkPtHS.js';
+import { b as FlowNode, P as PortDescriptor, N as NodeExecutor } from '../types-sOmpCitB.js';
+import { b as LlmRoute } from '../capabilities-CI3gw0C7.js';
+export { C as CapabilityId, a as LlmClient, c as LlmRouteChoice, L as LlmRouteRequest, W as WorkflowResolver, d as capabilityStatus, g as getLlmClient, e as getWorkflowResolver, r as registerLlmClient, f as registerWorkflowResolver } from '../capabilities-CI3gw0C7.js';
+export { L as LEGACY_PAUSE_PREFIXES, a as PAUSE_PREFIX, P as PauseAwaiting, b as PauseSignal, d as decodePause, e as encodePause, i as isPause, p as pauseForHuman } from '../pause-9iT4tCEV.js';
 import * as react from 'react';
 import { ComponentType, ReactNode } from 'react';
 import { NodeProps, NodeTypes } from '@xyflow/react';

package/dist/registry.cjs

@@ -66,6 +66,42 @@ function capabilityStatus() {
   };
 }
 
+// src/registry/pause.ts
+var PAUSE_PREFIX = "fancy-flow:pause:";
+var LEGACY_PAUSE_PREFIXES = [
+  ["awaiting-approval:", "approval"],
+  ["awaiting-input:", "input"]
+];
+function encodePause(signal) {
+  const { nodeId, awaiting, detail } = signal;
+  return PAUSE_PREFIX + JSON.stringify(detail === void 0 ? { nodeId, awaiting } : { nodeId, awaiting, detail });
+}
+function decodePause(reason) {
+  if (typeof reason !== "string") return null;
+  if (reason.startsWith(PAUSE_PREFIX)) {
+    const body = reason.slice(PAUSE_PREFIX.length);
+    try {
+      const parsed = JSON.parse(body);
+      if (typeof parsed?.nodeId !== "string" || typeof parsed?.awaiting !== "string") return null;
+      return "detail" in parsed ? { nodeId: parsed.nodeId, awaiting: parsed.awaiting, detail: parsed.detail } : { nodeId: parsed.nodeId, awaiting: parsed.awaiting };
+    } catch {
+      return null;
+    }
+  }
+  for (const [prefix, awaiting] of LEGACY_PAUSE_PREFIXES) {
+    if (reason.startsWith(prefix)) {
+      return { nodeId: reason.slice(prefix.length), awaiting };
+    }
+  }
+  return null;
+}
+function isPause(reason) {
+  return decodePause(reason) !== null;
+}
+function pauseForHuman(ctx, awaiting, detail) {
+  return ctx.abort(encodePause({ nodeId: ctx.node.id, awaiting, detail }));
+}
+
 // src/registry/registry.ts
 var kinds = /* @__PURE__ */ new Map();
 var aliases = /* @__PURE__ */ new Map();
@@ -9636,6 +9672,7 @@ var KINDS = [
   {
     name: "@particle-academy/user_input",
     aliases: ["user_input", "@fancy/user_input"],
+    pausesForHuman: "input",
     category: "human",
     label: "User Input",
     description: "Pause the flow until the user submits the configured form.",
@@ -9677,6 +9714,7 @@ var KINDS = [
   {
     name: "@particle-academy/rich_user_input",
     aliases: ["rich_user_input", "@fancy/rich_user_input"],
+    pausesForHuman: "input",
     category: "human",
     label: "Rich User Input",
     description: "Pause the flow on a fully authored page \u2014 content, required reading, multi-section forms.",
@@ -10205,6 +10243,7 @@ var KINDS = [
   {
     name: "@particle-academy/human_approval",
     aliases: ["human_approval", "@fancy/human_approval"],
+    pausesForHuman: "approval",
     category: "human",
     label: "Human Approval",
     description: "Pause until a human approves or denies.",
@@ -10289,17 +10328,22 @@ function buildNodeTypes() {
 
 exports.BUILTIN_KINDS = BUILTIN_KINDS;
 exports.DEFAULT_MAX_DEPTH = DEFAULT_MAX_DEPTH;
+exports.LEGACY_PAUSE_PREFIXES = LEGACY_PAUSE_PREFIXES;
+exports.PAUSE_PREFIX = PAUSE_PREFIX;
 exports.RegistryNode = RegistryNode;
 exports.RichInputPreview = RichInputPreview;
 exports.buildNodeTypes = buildNodeTypes;
 exports.capabilityStatus = capabilityStatus;
 exports.categoryAccent = categoryAccent;
 exports.declaredRoutes = declaredRoutes;
+exports.decodePause = decodePause;
 exports.defaultConfigFor = defaultConfigFor;
+exports.encodePause = encodePause;
 exports.getLlmClient = getLlmClient;
 exports.getNodeKind = getNodeKind;
 exports.getRichInputAdapter = getRichInputAdapter;
 exports.getWorkflowResolver = getWorkflowResolver;
+exports.isPause = isPause;
 exports.isRichInputEnabled = isRichInputEnabled;
 exports.kindIds = kindIds;
 exports.listNodeKinds = listNodeKinds;
@@ -10308,6 +10352,7 @@ exports.llmRouterExecutor = llmRouterExecutor;
 exports.nodeConfig = nodeConfig;
 exports.onNodeKindsChanged = onNodeKindsChanged;
 exports.onRichInputAdapterChanged = onRichInputAdapterChanged;
+exports.pauseForHuman = pauseForHuman;
 exports.registerBuiltinKinds = registerBuiltinKinds;
 exports.registerLlmClient = registerLlmClient;
 exports.registerNodeKind = registerNodeKind;