@particle-academy/fancy-flow 0.15.0 → 0.16.0

package/dist/index.d.cts

@@ -12,7 +12,7 @@ export { UseFlowRunOptions, UseFlowRunReturn, UseFlowStateReturn, applyStatusesT
 export { BUILTIN_KINDS, RegistryNode, RichInputAdapter, RichInputPreview, buildNodeTypes, categoryAccent, defaultConfigFor, getNodeKind, getRichInputAdapter, isRichInputEnabled, listNodeKinds, onNodeKindsChanged, onRichInputAdapterChanged, registerBuiltinKinds, registerNodeKind, registerRichInputAdapter, resolveNodePorts, resolvePortSpec, validateConfig } from './registry/index.cjs';
 export { R as RunOptions, a as RunResult, r as runFlow } from './run-flow-VKm57Hcj.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 './capabilities-BEbLqnJU.cjs';
+import './capabilities-ChE3Xi8R.cjs';
 
 type FlowCanvasProps = Omit<ReactFlowProps<FlowNode, Edge>, "nodes" | "edges" | "height"> & {
     nodes: FlowNode[];

package/dist/index.d.ts

@@ -12,7 +12,7 @@ export { UseFlowRunOptions, UseFlowRunReturn, UseFlowStateReturn, applyStatusesT
 export { BUILTIN_KINDS, RegistryNode, RichInputAdapter, RichInputPreview, buildNodeTypes, categoryAccent, defaultConfigFor, getNodeKind, getRichInputAdapter, isRichInputEnabled, listNodeKinds, onNodeKindsChanged, onRichInputAdapterChanged, registerBuiltinKinds, registerNodeKind, registerRichInputAdapter, resolveNodePorts, resolvePortSpec, validateConfig } from './registry/index.js';
 export { R as RunOptions, a as RunResult, r as runFlow } from './run-flow-ChBi6q-W.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 './capabilities-CI3gw0C7.js';
+import './capabilities-DUhAc-EJ.js';
 
 type FlowCanvasProps = Omit<ReactFlowProps<FlowNode, Edge>, "nodes" | "edges" | "height"> & {
     nodes: FlowNode[];

package/dist/index.js

@@ -1,7 +1,7 @@
 import { useFlowState, useFlowRun, applyStatusesToNodes } from './chunk-MFMRTRPO.js';
 export { applyStatusesToNodes, useFlowRun, useFlowState } from './chunk-MFMRTRPO.js';
-import { buildNodeTypes, registerBuiltinKinds } from './chunk-ZQBWPYTI.js';
-export { BUILTIN_KINDS, RegistryNode, buildNodeTypes, registerBuiltinKinds } from './chunk-ZQBWPYTI.js';
+import { buildNodeTypes, registerBuiltinKinds } from './chunk-M2QTDA3B.js';
+export { BUILTIN_KINDS, RegistryNode, buildNodeTypes, registerBuiltinKinds } from './chunk-M2QTDA3B.js';
 import { ReactFlowProvider, useReactFlow, addEdge, applyEdgeChanges, applyNodeChanges, Position, Handle, index, BackgroundVariant, Background, Controls, MiniMap } from './chunk-NF6NPY5N.js';
 export { LEGACY_PAUSE_PREFIXES, PAUSE_PREFIX, decodePause, encodePause, isPause, pauseForHuman } from './chunk-UEOE6B52.js';
 export { runFlow } from './chunk-L4AX73Q6.js';
@@ -12,7 +12,7 @@ import { onNodeKindsChanged, listNodeKinds, getNodeKind, defaultConfigFor, valid
 export { categoryAccent, defaultConfigFor, getNodeKind, listNodeKinds, onNodeKindsChanged, registerNodeKind, validateConfig } from './chunk-U5F22BHV.js';
 import { getRichInputAdapter } from './chunk-F5RPRB7A.js';
 export { RichInputPreview, getRichInputAdapter, isRichInputEnabled, onRichInputAdapterChanged, registerRichInputAdapter } from './chunk-F5RPRB7A.js';
-import './chunk-BB45F6S3.js';
+import './chunk-USL4FMFU.js';
 import { memo, createContext, forwardRef, useState, useEffect, useMemo, useCallback, useImperativeHandle, useRef, useContext } from 'react';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 

package/dist/llm/vercel-ai.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/registry/capabilities.ts","../../src/llm/vercel-ai.ts"],"names":["generateText","Output"],"mappings":";;;;;AA2DO,SAAS,kBAAkB,MAAA,EAA+B;AAE/D,EAAA,OAAO,MAAM;AAC2B,EACxC,CAAA;AACF;;;ACpBO,SAAS,wBAAwB,OAAA,EAAqC;AAC3E,EAAA,OAAO;AAAA,IACL,MAAM,YAAY,OAAA,EAAS;AACzB,MAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,YAAA,GAAe,OAAO,KAAK,OAAA,CAAQ,KAAA;AAMzD,MAAA,MAAM,MAAA,GAAS,MAAMA,eAAA,CAAa;AAAA,QAChC,KAAA;AAAA,QACA,QAAQ,OAAA,CAAQ,MAAA;AAAA,QAChB,MAAA,EAAQ,YAAY,OAAO,CAAA;AAAA,QAC3B,MAAA,EAAQC,UAAO,MAAA,CAAO;AAAA,UACpB,SAAS,OAAA,CAAQ,MAAA,CAAO,IAAI,CAAC,CAAA,KAAM,EAAE,IAAI,CAAA;AAAA,UACzC,IAAA,EAAM,OAAA;AAAA,UACN,WAAA,EAAa;AAAA,SACd,CAAA;AAAA,QACD,GAAI,OAAA,CAAQ,WAAA,IAAe;AAAC,OACpB,CAAA;AAEV,MAAA,MAAM,IAAA,GAAO,MAAA,CAAQ,MAAA,CAAgC,MAAA,IAAU,EAAE,CAAA;AACjE,MAAA,OAAO;AAAA,QACL,IAAA;AAAA;AAAA;AAAA,QAGA,MAAA,EAAQ,CAAA,UAAA,EAAa,aAAA,CAAc,KAAK,CAAC,CAAA;AAAA,OAC3C;AAAA,IACF;AAAA,GACF;AACF;AAGO,SAAS,wBAAwB,OAAA,EAAsC;AAC5E,EAAA,OAAO,iBAAA,CAAkD,CAAA;AAC3D;AASO,SAAS,YAAY,OAAA,EAAkC;AAC5D,EAAA,MAAM,YAAY,OAAA,CAAQ,MAAA,CAAO,OAAO,CAAC,CAAA,KAAM,EAAE,WAAW,CAAA;AAC5D,EAAA,IAAI,SAAA,CAAU,MAAA,KAAW,CAAA,EAAG,OAAO,OAAA,CAAQ,MAAA;AAE3C,EAAA,MAAM,KAAA,GAAQ,SAAA,CAAU,GAAA,CAAI,CAAC,MAAM,CAAA,EAAA,EAAK,CAAA,CAAE,IAAI,CAAA,EAAA,EAAK,CAAA,CAAE,WAAW,CAAA,CAAE,CAAA,CAAE,KAAK,IAAI,CAAA;AAC7E,EAAA,OAAO,CAAA,EAAG,QAAQ,MAAM;;AAAA;AAAA,EAAgB,KAAK,CAAA,CAAA;AAC/C;AAEA,SAAS,cAAc,KAAA,EAA8B;AACnD,EAAA,IAAI,OAAO,KAAA,KAAU,QAAA,EAAU,OAAO,KAAA;AACtC,EAAA,MAAM,KAAM,KAAA,CAA+B,OAAA;AAC3C,EAAA,OAAO,EAAA,IAAM,sBAAA;AACf","file":"vercel-ai.cjs","sourcesContent":["import type { FlowGraph } from \"../types\";\n\n/**\n * Host capabilities — the services core nodes need but must never depend on.\n *\n * A node that imports a provider SDK forces every consumer to install it: a\n * workflow app that never calls a model should not inherit an LLM dependency.\n * So core declares the CONTRACT and the host supplies the implementation, the\n * same arrangement `renderDocumentField` already uses for documents.\n *\n * That keeps opinionated nodes in core without their opinions: `llm_branch`\n * ships the routing semantics, port derivation and config UI, while whichever\n * client the host registers — Prism, an OpenAI SDK, a local model, a fake in a\n * test — decides how the question actually gets asked.\n *\n * Registration is deliberately explicit and typed per capability rather than a\n * stringly-keyed bag, so a missing one is a clear error at the seam instead of\n * an undefined somewhere downstream.\n */\n\n// ── LLM ─────────────────────────────────────────────────────────────────────\n\nexport type LlmRoute = { port: string; description?: string };\n\nexport type LlmRouteRequest = {\n  /** Optional framing for the decision. */\n  system?: string;\n  /** What the model is deciding about. */\n  prompt: string;\n  /** The ports it must choose between. */\n  routes: LlmRoute[];\n  provider?: string;\n  model?: string;\n  /** Host-resolved credential reference, never a raw key. */\n  credential?: string;\n};\n\nexport type LlmRouteChoice = {\n  /** Must be one of the requested route ports. */\n  port: string;\n  /** Why — carried down the chosen port so a run is explainable afterwards. */\n  reason?: string;\n};\n\n/**\n * The only thing core asks of an LLM: given routes, pick one.\n *\n * Deliberately not a general chat interface. A narrow contract is one a host\n * can satisfy in a few lines over any SDK, and it keeps the choice\n * machine-checkable — an implementation should constrain the model to the\n * declared ports (structured output / enum) rather than parsing prose.\n */\nexport type LlmClient = {\n  chooseRoute: (request: LlmRouteRequest) => Promise<LlmRouteChoice> | LlmRouteChoice;\n};\n\nlet llmClient: LlmClient | null = null;\n\n/** Install the host's LLM client. Returns an unregister function. */\nexport function registerLlmClient(client: LlmClient): () => void {\n  llmClient = client;\n  return () => {\n    if (llmClient === client) llmClient = null;\n  };\n}\n\nexport function getLlmClient(): LlmClient | null {\n  return llmClient;\n}\n\n// ── Workflow resolution ─────────────────────────────────────────────────────\n\n/**\n * Resolve a workflow reference to a runnable graph.\n *\n * `subflow` names another workflow rather than embedding it, so the host owns\n * where workflows live — a database, a file, an API. Returning null means \"no\n * such workflow\", which the node reports as an error rather than silently\n * running nothing.\n */\nexport type WorkflowResolver = (ref: string) => Promise<FlowGraph | null> | FlowGraph | null;\n\nlet workflowResolver: WorkflowResolver | null = null;\n\n/** Install the host's workflow resolver. Returns an unregister function. */\nexport function registerWorkflowResolver(resolver: WorkflowResolver): () => void {\n  workflowResolver = resolver;\n  return () => {\n    if (workflowResolver === resolver) workflowResolver = null;\n  };\n}\n\nexport function getWorkflowResolver(): WorkflowResolver | null {\n  return workflowResolver;\n}\n\n// ── Introspection ───────────────────────────────────────────────────────────\n\nexport type CapabilityId = \"llm\" | \"workflow_resolver\" | \"document\";\n\n/**\n * Which capabilities are currently satisfied.\n *\n * Exists so a host (or the CLI, or an agent over MCP) can answer \"what does\n * this graph need that I haven't wired?\" BEFORE a run fails halfway through.\n */\nexport function capabilityStatus(): Record<CapabilityId, boolean> {\n  // Imported lazily to avoid dragging the React-dependent rich-input module\n  // into the headless engine.\n  let documentReady = false;\n  try {\n    // eslint-disable-next-line @typescript-eslint/no-var-requires, no-undef\n    documentReady = Boolean((globalThis as any).__fancyFlowDocumentAdapter);\n  } catch {\n    documentReady = false;\n  }\n  return {\n    llm: llmClient !== null,\n    workflow_resolver: workflowResolver !== null,\n    document: documentReady,\n  };\n}\n","/**\n * `@particle-academy/fancy-flow/llm/vercel-ai` — an LLM client backed by the\n * Vercel AI SDK.\n *\n * Core ships the routing but never a provider, so `llm_branch` needs a client\n * before it can run. Making every consumer hand-write one is not \"fully\n * functional\" — so this adapter ships in the box, on an opt-in subpath, exactly\n * like `/rich-input` wires fancy-cms.\n *\n * The AI SDK is chosen because it fronts every provider (Anthropic, OpenAI,\n * Google, local models). Picking it does NOT force it: `registerLlmClient()`\n * takes any implementation, so a different SDK or a hand-rolled fetch works\n * just as well.\n *\n * ```ts\n * import { anthropic } from \"@ai-sdk/anthropic\";\n * import { useVercelAiForLlmBranch } from \"@particle-academy/fancy-flow/llm/vercel-ai\";\n *\n * useVercelAiForLlmBranch({ model: anthropic(\"claude-sonnet-4-5\") });\n * ```\n *\n * `ai` is an OPTIONAL peer — required only by this subpath. The main entry\n * never imports it, so a flow with no AI node pays nothing.\n */\nimport { Output, generateText, type LanguageModel } from \"ai\";\nimport { registerLlmClient, type LlmClient, type LlmRouteRequest } from \"../registry/capabilities\";\n\nexport type VercelAiOptions = {\n  /** The model to route with, e.g. `anthropic(\"claude-sonnet-4-5\")`. */\n  model: LanguageModel;\n  /**\n   * Resolve a per-node model. `llm_branch` config can name a provider/model,\n   * and only the host knows how to turn those strings into a model instance —\n   * core deliberately never maps a name to a provider.\n   */\n  resolveModel?: (request: LlmRouteRequest) => LanguageModel | undefined;\n  /** Extra options merged into every call (temperature, headers, …). */\n  callOptions?: Record<string, unknown>;\n};\n\n/**\n * Build the client without registering it — handy for tests, or for a host\n * that wants to wrap it.\n */\nexport function createVercelAiLlmClient(options: VercelAiOptions): LlmClient {\n  return {\n    async chooseRoute(request) {\n      const model = options.resolveModel?.(request) ?? options.model;\n\n      // Constrain the model to the declared ports instead of parsing prose.\n      // A choice that can only BE one of the ports is the difference between a\n      // routing decision and a guess, and it means the \"hallucinated port\"\n      // guard in the node is a backstop rather than the primary defence.\n      const result = await generateText({\n        model,\n        system: request.system,\n        prompt: buildPrompt(request),\n        output: Output.choice({\n          options: request.routes.map((r) => r.port),\n          name: \"route\",\n          description: \"The single route this input should follow.\",\n        }),\n        ...(options.callOptions ?? {}),\n      } as never);\n\n      const port = String((result as { output?: unknown }).output ?? \"\");\n      return {\n        port,\n        // The SDK returns the choice, not an explanation. Say where the answer\n        // came from rather than inventing a rationale the model never gave.\n        reason: `chosen by ${describeModel(model)}`,\n      };\n    },\n  };\n}\n\n/** Build the client and install it. Returns an unregister function. */\nexport function useVercelAiForLlmBranch(options: VercelAiOptions): () => void {\n  return registerLlmClient(createVercelAiLlmClient(options));\n}\n\n/**\n * Fold the route descriptions into the prompt.\n *\n * The port ids alone are often terse (`billing`, `support`); the descriptions\n * are what the author wrote to distinguish them, so a model that never sees\n * them is choosing on the strength of a label.\n */\nexport function buildPrompt(request: LlmRouteRequest): string {\n  const described = request.routes.filter((r) => r.description);\n  if (described.length === 0) return request.prompt;\n\n  const lines = described.map((r) => `- ${r.port}: ${r.description}`).join(\"\\n\");\n  return `${request.prompt}\\n\\nRoutes:\\n${lines}`;\n}\n\nfunction describeModel(model: LanguageModel): string {\n  if (typeof model === \"string\") return model;\n  const id = (model as { modelId?: string }).modelId;\n  return id ?? \"the configured model\";\n}\n"]}
+{"version":3,"sources":["../../src/registry/capabilities.ts","../../src/llm/vercel-ai.ts"],"names":["generateText","Output"],"mappings":";;;;;AA2DO,SAAS,kBAAkB,MAAA,EAA+B;AAE/D,EAAA,OAAO,MAAM;AAC2B,EACxC,CAAA;AACF;;;ACpBO,SAAS,wBAAwB,OAAA,EAAqC;AAC3E,EAAA,OAAO;AAAA,IACL,MAAM,YAAY,OAAA,EAAS;AACzB,MAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,YAAA,GAAe,OAAO,KAAK,OAAA,CAAQ,KAAA;AAMzD,MAAA,MAAM,MAAA,GAAS,MAAMA,eAAA,CAAa;AAAA,QAChC,KAAA;AAAA,QACA,QAAQ,OAAA,CAAQ,MAAA;AAAA,QAChB,MAAA,EAAQ,YAAY,OAAO,CAAA;AAAA,QAC3B,MAAA,EAAQC,UAAO,MAAA,CAAO;AAAA,UACpB,SAAS,OAAA,CAAQ,MAAA,CAAO,IAAI,CAAC,CAAA,KAAM,EAAE,IAAI,CAAA;AAAA,UACzC,IAAA,EAAM,OAAA;AAAA,UACN,WAAA,EAAa;AAAA,SACd,CAAA;AAAA,QACD,GAAI,OAAA,CAAQ,WAAA,IAAe;AAAC,OACpB,CAAA;AAEV,MAAA,MAAM,IAAA,GAAO,MAAA,CAAQ,MAAA,CAAgC,MAAA,IAAU,EAAE,CAAA;AACjE,MAAA,OAAO;AAAA,QACL,IAAA;AAAA;AAAA;AAAA,QAGA,MAAA,EAAQ,CAAA,UAAA,EAAa,aAAA,CAAc,KAAK,CAAC,CAAA;AAAA,OAC3C;AAAA,IACF;AAAA,GACF;AACF;AAGO,SAAS,wBAAwB,OAAA,EAAsC;AAC5E,EAAA,OAAO,iBAAA,CAAkD,CAAA;AAC3D;AASO,SAAS,YAAY,OAAA,EAAkC;AAC5D,EAAA,MAAM,YAAY,OAAA,CAAQ,MAAA,CAAO,OAAO,CAAC,CAAA,KAAM,EAAE,WAAW,CAAA;AAC5D,EAAA,IAAI,SAAA,CAAU,MAAA,KAAW,CAAA,EAAG,OAAO,OAAA,CAAQ,MAAA;AAE3C,EAAA,MAAM,KAAA,GAAQ,SAAA,CAAU,GAAA,CAAI,CAAC,MAAM,CAAA,EAAA,EAAK,CAAA,CAAE,IAAI,CAAA,EAAA,EAAK,CAAA,CAAE,WAAW,CAAA,CAAE,CAAA,CAAE,KAAK,IAAI,CAAA;AAC7E,EAAA,OAAO,CAAA,EAAG,QAAQ,MAAM;;AAAA;AAAA,EAAgB,KAAK,CAAA,CAAA;AAC/C;AAEA,SAAS,cAAc,KAAA,EAA8B;AACnD,EAAA,IAAI,OAAO,KAAA,KAAU,QAAA,EAAU,OAAO,KAAA;AACtC,EAAA,MAAM,KAAM,KAAA,CAA+B,OAAA;AAC3C,EAAA,OAAO,EAAA,IAAM,sBAAA;AACf","file":"vercel-ai.cjs","sourcesContent":["import type { FlowGraph } from \"../types\";\n\n/**\n * Host capabilities — the services core nodes need but must never depend on.\n *\n * A node that imports a provider SDK forces every consumer to install it: a\n * workflow app that never calls a model should not inherit an LLM dependency.\n * So core declares the CONTRACT and the host supplies the implementation, the\n * same arrangement `renderDocumentField` already uses for documents.\n *\n * That keeps opinionated nodes in core without their opinions: `llm_branch`\n * ships the routing semantics, port derivation and config UI, while whichever\n * client the host registers — Prism, an OpenAI SDK, a local model, a fake in a\n * test — decides how the question actually gets asked.\n *\n * Registration is deliberately explicit and typed per capability rather than a\n * stringly-keyed bag, so a missing one is a clear error at the seam instead of\n * an undefined somewhere downstream.\n */\n\n// ── LLM ─────────────────────────────────────────────────────────────────────\n\nexport type LlmRoute = { port: string; description?: string };\n\nexport type LlmRouteRequest = {\n  /** Optional framing for the decision. */\n  system?: string;\n  /** What the model is deciding about. */\n  prompt: string;\n  /** The ports it must choose between. */\n  routes: LlmRoute[];\n  provider?: string;\n  model?: string;\n  /** Host-resolved credential reference, never a raw key. */\n  credential?: string;\n};\n\nexport type LlmRouteChoice = {\n  /** Must be one of the requested route ports. */\n  port: string;\n  /** Why — carried down the chosen port so a run is explainable afterwards. */\n  reason?: string;\n};\n\n/**\n * The only thing core asks of an LLM: given routes, pick one.\n *\n * Deliberately not a general chat interface. A narrow contract is one a host\n * can satisfy in a few lines over any SDK, and it keeps the choice\n * machine-checkable — an implementation should constrain the model to the\n * declared ports (structured output / enum) rather than parsing prose.\n */\nexport type LlmClient = {\n  chooseRoute: (request: LlmRouteRequest) => Promise<LlmRouteChoice> | LlmRouteChoice;\n};\n\nlet llmClient: LlmClient | null = null;\n\n/** Install the host's LLM client. Returns an unregister function. */\nexport function registerLlmClient(client: LlmClient): () => void {\n  llmClient = client;\n  return () => {\n    if (llmClient === client) llmClient = null;\n  };\n}\n\nexport function getLlmClient(): LlmClient | null {\n  return llmClient;\n}\n\n// ── Workflow resolution ─────────────────────────────────────────────────────\n\n/**\n * Why a workflow reference could not be resolved.\n *\n * `missing` and `version-mismatch` are deliberately distinct. Collapsing them\n * into a bare null makes \"no such workflow\" indistinguishable from \"that\n * workflow exists, but it is not the one you pinned\" — and the second wants an\n * error naming both versions, because it is the interesting failure.\n */\nexport type WorkflowResolutionFailure = {\n  reason: \"missing\" | \"version-mismatch\";\n  /** The version the host actually holds, when it holds one. */\n  available?: number;\n  message?: string;\n};\n\nexport type WorkflowResolution = FlowGraph | WorkflowResolutionFailure | null;\n\n/**\n * Resolve a workflow reference to a runnable graph.\n *\n * `subflow` names another workflow rather than embedding it, so the host owns\n * where workflows live — a database, a file, an API.\n *\n * ## Why `version` is here\n *\n * A workflow another workflow depends on is an INTERFACE, and interfaces need\n * pins. Without a version, a parent goes on calling `invoice-triage`, someone\n * edits that child, and the parent now runs different logic having reported\n * success the whole time — correct-looking, no error, wrong behaviour. The same\n * failure family as the 0.9.0 routing divergence.\n *\n * The parameter lives on the resolver rather than being encoded into the ref\n * string (`invoice-triage@3`) because a stringly-typed protocol is one every\n * host invents differently — the \"three vocabularies for one node\" problem.\n *\n * Raised by the MOIC Suite consumer, whose `workflow_ref` pins versions and\n * fails loudly on mismatch. Their point: a host COULD NOT implement pinning\n * before this, because the node had no way to ask and the resolver no way to\n * receive.\n *\n * Returning `null` still means \"no such workflow\". Return a\n * {@link WorkflowResolutionFailure} to distinguish a version mismatch.\n */\nexport type WorkflowResolver = (\n  ref: string,\n  version?: number,\n) => Promise<WorkflowResolution> | WorkflowResolution;\n\n/** Narrow a resolver's return value to an explicit failure. */\nexport function isResolutionFailure(value: WorkflowResolution): value is WorkflowResolutionFailure {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    \"reason\" in value &&\n    (value as WorkflowResolutionFailure).reason !== undefined\n  );\n}\n\nlet workflowResolver: WorkflowResolver | null = null;\n\n/** Install the host's workflow resolver. Returns an unregister function. */\nexport function registerWorkflowResolver(resolver: WorkflowResolver): () => void {\n  workflowResolver = resolver;\n  return () => {\n    if (workflowResolver === resolver) workflowResolver = null;\n  };\n}\n\nexport function getWorkflowResolver(): WorkflowResolver | null {\n  return workflowResolver;\n}\n\n// ── Introspection ───────────────────────────────────────────────────────────\n\nexport type CapabilityId = \"llm\" | \"workflow_resolver\" | \"document\";\n\n/**\n * Which capabilities are currently satisfied.\n *\n * Exists so a host (or the CLI, or an agent over MCP) can answer \"what does\n * this graph need that I haven't wired?\" BEFORE a run fails halfway through.\n */\nexport function capabilityStatus(): Record<CapabilityId, boolean> {\n  // Imported lazily to avoid dragging the React-dependent rich-input module\n  // into the headless engine.\n  let documentReady = false;\n  try {\n    // eslint-disable-next-line @typescript-eslint/no-var-requires, no-undef\n    documentReady = Boolean((globalThis as any).__fancyFlowDocumentAdapter);\n  } catch {\n    documentReady = false;\n  }\n  return {\n    llm: llmClient !== null,\n    workflow_resolver: workflowResolver !== null,\n    document: documentReady,\n  };\n}\n","/**\n * `@particle-academy/fancy-flow/llm/vercel-ai` — an LLM client backed by the\n * Vercel AI SDK.\n *\n * Core ships the routing but never a provider, so `llm_branch` needs a client\n * before it can run. Making every consumer hand-write one is not \"fully\n * functional\" — so this adapter ships in the box, on an opt-in subpath, exactly\n * like `/rich-input` wires fancy-cms.\n *\n * The AI SDK is chosen because it fronts every provider (Anthropic, OpenAI,\n * Google, local models). Picking it does NOT force it: `registerLlmClient()`\n * takes any implementation, so a different SDK or a hand-rolled fetch works\n * just as well.\n *\n * ```ts\n * import { anthropic } from \"@ai-sdk/anthropic\";\n * import { useVercelAiForLlmBranch } from \"@particle-academy/fancy-flow/llm/vercel-ai\";\n *\n * useVercelAiForLlmBranch({ model: anthropic(\"claude-sonnet-4-5\") });\n * ```\n *\n * `ai` is an OPTIONAL peer — required only by this subpath. The main entry\n * never imports it, so a flow with no AI node pays nothing.\n */\nimport { Output, generateText, type LanguageModel } from \"ai\";\nimport { registerLlmClient, type LlmClient, type LlmRouteRequest } from \"../registry/capabilities\";\n\nexport type VercelAiOptions = {\n  /** The model to route with, e.g. `anthropic(\"claude-sonnet-4-5\")`. */\n  model: LanguageModel;\n  /**\n   * Resolve a per-node model. `llm_branch` config can name a provider/model,\n   * and only the host knows how to turn those strings into a model instance —\n   * core deliberately never maps a name to a provider.\n   */\n  resolveModel?: (request: LlmRouteRequest) => LanguageModel | undefined;\n  /** Extra options merged into every call (temperature, headers, …). */\n  callOptions?: Record<string, unknown>;\n};\n\n/**\n * Build the client without registering it — handy for tests, or for a host\n * that wants to wrap it.\n */\nexport function createVercelAiLlmClient(options: VercelAiOptions): LlmClient {\n  return {\n    async chooseRoute(request) {\n      const model = options.resolveModel?.(request) ?? options.model;\n\n      // Constrain the model to the declared ports instead of parsing prose.\n      // A choice that can only BE one of the ports is the difference between a\n      // routing decision and a guess, and it means the \"hallucinated port\"\n      // guard in the node is a backstop rather than the primary defence.\n      const result = await generateText({\n        model,\n        system: request.system,\n        prompt: buildPrompt(request),\n        output: Output.choice({\n          options: request.routes.map((r) => r.port),\n          name: \"route\",\n          description: \"The single route this input should follow.\",\n        }),\n        ...(options.callOptions ?? {}),\n      } as never);\n\n      const port = String((result as { output?: unknown }).output ?? \"\");\n      return {\n        port,\n        // The SDK returns the choice, not an explanation. Say where the answer\n        // came from rather than inventing a rationale the model never gave.\n        reason: `chosen by ${describeModel(model)}`,\n      };\n    },\n  };\n}\n\n/** Build the client and install it. Returns an unregister function. */\nexport function useVercelAiForLlmBranch(options: VercelAiOptions): () => void {\n  return registerLlmClient(createVercelAiLlmClient(options));\n}\n\n/**\n * Fold the route descriptions into the prompt.\n *\n * The port ids alone are often terse (`billing`, `support`); the descriptions\n * are what the author wrote to distinguish them, so a model that never sees\n * them is choosing on the strength of a label.\n */\nexport function buildPrompt(request: LlmRouteRequest): string {\n  const described = request.routes.filter((r) => r.description);\n  if (described.length === 0) return request.prompt;\n\n  const lines = described.map((r) => `- ${r.port}: ${r.description}`).join(\"\\n\");\n  return `${request.prompt}\\n\\nRoutes:\\n${lines}`;\n}\n\nfunction describeModel(model: LanguageModel): string {\n  if (typeof model === \"string\") return model;\n  const id = (model as { modelId?: string }).modelId;\n  return id ?? \"the configured model\";\n}\n"]}

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

@@ -1,5 +1,5 @@
 import { LanguageModel } from 'ai';
-import { L as LlmRouteRequest, a as LlmClient } from '../capabilities-BEbLqnJU.cjs';
+import { L as LlmRouteRequest, a as LlmClient } from '../capabilities-ChE3Xi8R.cjs';
 import '../types-sOmpCitB.cjs';
 import '@xyflow/react';
 

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

@@ -1,5 +1,5 @@
 import { LanguageModel } from 'ai';
-import { L as LlmRouteRequest, a as LlmClient } from '../capabilities-CI3gw0C7.js';
+import { L as LlmRouteRequest, a as LlmClient } from '../capabilities-DUhAc-EJ.js';
 import '../types-sOmpCitB.js';
 import '@xyflow/react';
 

package/dist/llm/vercel-ai.js

@@ -1,4 +1,4 @@
-import { registerLlmClient } from '../chunk-BB45F6S3.js';
+import { registerLlmClient } from '../chunk-USL4FMFU.js';
 import { generateText, Output } from 'ai';
 
 function createVercelAiLlmClient(options) {

package/dist/registry/index.d.cts

@@ -1,8 +1,8 @@
 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';
+import { b as LlmRoute } from '../capabilities-ChE3Xi8R.cjs';
+export { C as CapabilityId, a as LlmClient, c as LlmRouteChoice, L as LlmRouteRequest, W as WorkflowResolution, d as WorkflowResolutionFailure, e as WorkflowResolver, f as capabilityStatus, g as getLlmClient, h as getWorkflowResolver, i as isResolutionFailure, r as registerLlmClient, j as registerWorkflowResolver } from '../capabilities-ChE3Xi8R.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';

package/dist/registry/index.d.ts

@@ -1,8 +1,8 @@
 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';
+import { b as LlmRoute } from '../capabilities-DUhAc-EJ.js';
+export { C as CapabilityId, a as LlmClient, c as LlmRouteChoice, L as LlmRouteRequest, W as WorkflowResolution, d as WorkflowResolutionFailure, e as WorkflowResolver, f as capabilityStatus, g as getLlmClient, h as getWorkflowResolver, i as isResolutionFailure, r as registerLlmClient, j as registerWorkflowResolver } from '../capabilities-DUhAc-EJ.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';

package/dist/registry.cjs

@@ -42,6 +42,9 @@ function registerLlmClient(client) {
 function getLlmClient() {
   return llmClient;
 }
+function isResolutionFailure(value) {
+  return typeof value === "object" && value !== null && "reason" in value && value.reason !== void 0;
+}
 var workflowResolver = null;
 function registerWorkflowResolver(resolver) {
   workflowResolver = resolver;
@@ -427,7 +430,14 @@ var subflowExecutor = async (ctx) => {
       `subflow depth limit reached (${maxDepth}) at "${ref}" \u2014 a workflow is referencing itself, directly or through a chain.`
     );
   }
-  const child = await resolver(ref);
+  const pinned = config.version === void 0 || config.version === "" ? void 0 : Number(config.version);
+  if (pinned !== void 0 && !Number.isInteger(pinned)) {
+    ctx.abort(`subflow "${ref}" has a non-integer version pin (${String(config.version)}).`);
+  }
+  const resolved = await resolver(ref, pinned);
+  const child = isResolutionFailure(resolved) ? ctx.abort(
+    resolved.reason === "version-mismatch" ? resolved.message ?? `subflow "${ref}" is pinned to version ${pinned}, but the host has ${resolved.available ?? "a different version"}.` : resolved.message ?? `subflow could not resolve workflow "${ref}"`
+  ) : resolved;
   if (!child) ctx.abort(`subflow could not resolve workflow "${ref}"`);
   const mode = subflowMode(config);
   const streaming = mode === "stream" || mode === "both";
@@ -9759,6 +9769,12 @@ var KINDS = [
         placeholder: "onboarding-v2",
         description: "Reference resolved by the host's registerWorkflowResolver()."
       },
+      {
+        type: "number",
+        key: "version",
+        label: "Pin to version",
+        description: "Optional. Leave blank to always run the child's current version. Pinning fails the run loudly if the child has moved on \u2014 without it, someone edits the child and this flow silently runs different logic."
+      },
       {
         type: "select",
         key: "mode",
@@ -10344,6 +10360,7 @@ exports.getNodeKind = getNodeKind;
 exports.getRichInputAdapter = getRichInputAdapter;
 exports.getWorkflowResolver = getWorkflowResolver;
 exports.isPause = isPause;
+exports.isResolutionFailure = isResolutionFailure;
 exports.isRichInputEnabled = isRichInputEnabled;
 exports.kindIds = kindIds;
 exports.listNodeKinds = listNodeKinds;