@particle-academy/fancy-flow 0.65.1 → 0.66.0

package/dist/ux.d.cts

@@ -1,7 +1,7 @@
 import { EffectRegistry, DispatchActor } from '@particle-academy/fancy-auto-common';
 export { AutoActivityEvent } from '@particle-academy/fancy-auto-common';
-import { a as NodeCategory, C as ConfigField } from './types-D71SKA5A.cjs';
-import { E as ExecutorRegistry } from './types-JFYjPJAG.cjs';
+import { a as NodeCategory, C as ConfigField } from './types-C2ATTmjN.cjs';
+import { E as ExecutorRegistry } from './types-B-Syk9-M.cjs';
 import 'react';
 import '@xyflow/react';
 import './pause-9iT4tCEV.cjs';
@@ -20,6 +20,18 @@ type UxEffectMeta = {
     category?: NodeCategory;
     /** Config form fields = the effect's params. */
     configSchema?: ConfigField[];
+    /**
+     * Include the executor's exact resolved input-port map as `$inputs` in the
+     * effect params. Off by default so existing effects keep their payload shape.
+     */
+    includeInputs?: boolean;
+    /**
+     * Make this UX node an inline step instead of a terminal notification. It
+     * gains an `out` port, waits for the effect Promise, then emits its `in`
+     * payload unchanged. This is the native shape for dialogs/overlays whose
+     * lifetime gates the rest of a workflow.
+     */
+    passThrough?: boolean;
 };
 type FlowRunnerUxOptions = {
     /** Named host UX effects the flow can invoke. */

package/dist/ux.d.ts

@@ -1,7 +1,7 @@
 import { EffectRegistry, DispatchActor } from '@particle-academy/fancy-auto-common';
 export { AutoActivityEvent } from '@particle-academy/fancy-auto-common';
-import { a as NodeCategory, C as ConfigField } from './types-Ckhz-YwC.js';
-import { E as ExecutorRegistry } from './types-JFYjPJAG.js';
+import { a as NodeCategory, C as ConfigField } from './types-VunLGqrn.js';
+import { E as ExecutorRegistry } from './types-B-Syk9-M.js';
 import 'react';
 import '@xyflow/react';
 import './pause-9iT4tCEV.js';
@@ -20,6 +20,18 @@ type UxEffectMeta = {
     category?: NodeCategory;
     /** Config form fields = the effect's params. */
     configSchema?: ConfigField[];
+    /**
+     * Include the executor's exact resolved input-port map as `$inputs` in the
+     * effect params. Off by default so existing effects keep their payload shape.
+     */
+    includeInputs?: boolean;
+    /**
+     * Make this UX node an inline step instead of a terminal notification. It
+     * gains an `out` port, waits for the effect Promise, then emits its `in`
+     * payload unchanged. This is the native shape for dialogs/overlays whose
+     * lifetime gates the rest of a workflow.
+     */
+    passThrough?: boolean;
 };
 type FlowRunnerUxOptions = {
     /** Named host UX effects the flow can invoke. */

package/dist/ux.js

@@ -1,6 +1,6 @@
-import { registerNodeKind } from './chunk-JF6WCRBU.js';
+import { registerNodeKind } from './chunk-HQGOFGAL.js';
 import './chunk-F5RPRB7A.js';
-import './chunk-USL4FMFU.js';
+import './chunk-2QXKDLGT.js';
 import { useMemo } from 'react';
 import { createEffectDispatcher } from '@particle-academy/fancy-auto-common';
 
@@ -15,12 +15,15 @@ function createFlowRunnerUx(options) {
   const dispatcher = createEffectDispatcher(effects, { actor, targetKind: "ux" });
   const executors = {};
   for (const name of Object.keys(effects)) {
-    executors[kindFor(name)] = async ({ node }) => {
-      const params = node.data?.config ?? {};
+    executors[kindFor(name)] = async ({ node, inputs }) => {
+      const m = meta[name] ?? {};
+      const config = node.data?.config ?? {};
+      const params = m.includeInputs ? { ...config, $inputs: inputs } : config;
       const result = await dispatcher.dispatch(name, params);
       if (result && typeof result === "object" && ("branch" in result || "__port" in result)) {
         return result;
       }
+      if (m.passThrough) return inputs.in ?? inputs;
       return { effect: name, result };
     };
   }
@@ -35,7 +38,9 @@ function createFlowRunnerUx(options) {
         icon: m.icon ?? "\u2728",
         accent: m.accent ?? "#8b5cf6",
         inputs: [{ id: "in" }],
-        outputs: [],
+        outputs: m.passThrough ? [{ id: "out" }] : [],
+        emits: m.passThrough ? "input" : void 0,
+        sideEffects: "unsafe-to-replay",
         configSchema: m.configSchema
       });
     }

package/dist/ux.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/ux.ts"],"names":[],"mappings":";;;;;;AAyEA,IAAM,cAAA,GAAiB,CAAC,IAAA,KAAiB,CAAA,GAAA,EAAM,IAAI,CAAA,CAAA;AAG5C,SAAS,mBAAmB,OAAA,EAA4C;AAC7E,EAAA,MAAM;AAAA,IACJ,OAAA;AAAA,IACA,OAAO,EAAC;AAAA,IACR,KAAA,GAAQ,EAAE,EAAA,EAAI,MAAA,EAAQ,QAAQ,MAAA,EAAO;AAAA,IACrC,OAAA,GAAU;AAAA,GACZ,GAAI,OAAA;AAEJ,EAAA,MAAM,aAAa,sBAAA,CAAuB,OAAA,EAAS,EAAE,KAAA,EAAO,UAAA,EAAY,MAAM,CAAA;AAE9E,EAAA,MAAM,YAA8B,EAAC;AACrC,EAAA,KAAA,MAAW,IAAA,IAAQ,MAAA,CAAO,IAAA,CAAK,OAAO,CAAA,EAAG;AACvC,IAAA,SAAA,CAAU,QAAQ,IAAI,CAAC,IAAI,OAAO,EAAE,MAAK,KAA0B;AACjE,MAAA,MAAM,MAAA,GAAU,IAAA,CAAK,IAAA,EAA2D,MAAA,IAAU,EAAC;AAC3F,MAAA,MAAM,MAAA,GAAS,MAAM,UAAA,CAAW,QAAA,CAAS,MAAM,MAAM,CAAA;AAKrD,MAAA,IAAI,UAAU,OAAO,MAAA,KAAW,aAAa,QAAA,IAAY,MAAA,IAAU,YAAY,MAAA,CAAA,EAAS;AACtF,QAAA,OAAO,MAAA;AAAA,MACT;AACA,MAAA,OAAO,EAAE,MAAA,EAAQ,IAAA,EAAM,MAAA,EAAO;AAAA,IAChC,CAAA;AAAA,EACF;AAEA,EAAA,MAAM,gBAAgB,MAAM;AAC1B,IAAA,KAAA,MAAW,IAAA,IAAQ,MAAA,CAAO,IAAA,CAAK,OAAO,CAAA,EAAG;AACvC,MAAA,MAAM,CAAA,GAAI,IAAA,CAAK,IAAI,CAAA,IAAK,EAAC;AACzB,MAAA,gBAAA,CAAiB;AAAA,QACf,IAAA,EAAM,QAAQ,IAAI,CAAA;AAAA,QAClB,QAAA,EAAU,EAAE,QAAA,IAAY,QAAA;AAAA,QACxB,KAAA,EAAO,EAAE,KAAA,IAAS,IAAA;AAAA,QAClB,WAAA,EAAa,CAAA,CAAE,WAAA,IAAe,CAAA,uBAAA,EAA0B,IAAI,CAAA,CAAA,CAAA;AAAA,QAC5D,IAAA,EAAM,EAAE,IAAA,IAAQ,QAAA;AAAA,QAChB,MAAA,EAAQ,EAAE,MAAA,IAAU,SAAA;AAAA,QACpB,MAAA,EAAQ,CAAC,EAAE,EAAA,EAAI,MAAM,CAAA;AAAA,QACrB,SAAS,EAAC;AAAA,QACV,cAAc,CAAA,CAAE;AAAA,OACjB,CAAA;AAAA,IACH;AAAA,EACF,CAAA;AAEA,EAAA,OAAO;AAAA,IACL,SAAA;AAAA,IACA,UAAU,UAAA,CAAW,QAAA;AAAA,IACrB,aAAa,UAAA,CAAW,KAAA;AAAA,IACxB;AAAA,GACF;AACF;AAMO,SAAS,gBAAgB,OAAA,EAA4C;AAC1E,EAAA,MAAM,MAAM,CAAA,EAAG,MAAA,CAAO,IAAA,CAAK,OAAA,CAAQ,OAAO,CAAA,CAAE,IAAA,EAAK,CAAE,IAAA,CAAK,GAAG,CAAC,CAAA,CAAA,EAAI,OAAA,CAAQ,KAAA,EAAO,MAAM,MAAM,CAAA,CAAA;AAE3F,EAAA,OAAO,QAAQ,MAAM,kBAAA,CAAmB,OAAO,CAAA,EAAG,CAAC,GAAG,CAAC,CAAA;AACzD","file":"ux.js","sourcesContent":["/**\n * FlowRunnerUx — the **flow-driven UX** bridge. The headless counterpart to\n * agent-integrations: where that wires an *agent* to host UI surfaces, this\n * wires a *running flow* to host UX. Both share the same primitives from\n * `@particle-academy/fancy-auto-common` (activity bus, effect dispatch).\n *\n * The host registers named UX effects (toast, navigate, confirm, …); this turns\n * each into a flow executor keyed by a node kind (`ux_<effect>` by default), so\n * dropping a `ux_toast` node into a `<FlowEditor>` and running it fires the\n * host's toast. Every dispatch broadcasts an `AutoActivityEvent` (source:\"flow\")\n * for presence / logging. Human-in-the-loop is free: an effect that returns a\n * Promise (e.g. an approval dialog) pauses the run until the user resolves it.\n *\n *   const ux = createFlowRunnerUx({\n *     effects: {\n *       toast:   ({ message }) => toast({ title: message }),\n *       navigate:({ to })      => router.visit(to),\n *       confirm: ({ prompt })  => new Promise(res => openDialog(prompt, res)), // pauses the run\n *     },\n *   });\n *   ux.registerKinds();                       // adds ux_toast / ux_navigate / ux_confirm to the palette\n *   <FlowEditor initial={graph} executors={ux.executors} />\n */\nimport { useMemo } from \"react\";\nimport {\n  createEffectDispatcher,\n  type DispatchActor,\n  type EffectRegistry,\n} from \"@particle-academy/fancy-auto-common\";\nimport { registerNodeKind } from \"./registry/registry\";\nimport type { ConfigField, NodeCategory } from \"./registry/types\";\nimport type { ExecutorRegistry, FlowNode } from \"./types\";\n\nexport type { AutoActivityEvent } from \"@particle-academy/fancy-auto-common\";\n\n/** Per-effect presentation for the palette node kind that drives it. */\nexport type UxEffectMeta = {\n  /** Palette label. Default: the effect name. */\n  label?: string;\n  /** One-line palette description. */\n  description?: string;\n  /** Emoji / glyph for the node header. */\n  icon?: string;\n  /** Header accent color. */\n  accent?: string;\n  /** Palette grouping. Default \"output\". */\n  category?: NodeCategory;\n  /** Config form fields = the effect's params. */\n  configSchema?: ConfigField[];\n};\n\nexport type FlowRunnerUxOptions = {\n  /** Named host UX effects the flow can invoke. */\n  effects: EffectRegistry;\n  /** Optional per-effect palette metadata (used by `registerKinds`). */\n  meta?: Record<string, UxEffectMeta>;\n  /** Identifies the flow run in emitted activity. Default `{ id: \"flow\", source: \"flow\" }`. */\n  actor?: DispatchActor;\n  /** Map an effect name to its node-kind name. Default `ux_<effect>`. */\n  kindFor?: (effectName: string) => string;\n};\n\nexport type FlowRunnerUx = {\n  /** Executor registry to hand to `<FlowEditor executors>` or `runFlow`. */\n  executors: ExecutorRegistry;\n  /** Invoke an effect imperatively (also emits activity). */\n  dispatch: <R = unknown>(name: string, params?: unknown) => Promise<R>;\n  /** All effect names. */\n  effectNames: () => string[];\n  /** Register a palette node kind per effect (`ux_<effect>`). Idempotent. */\n  registerKinds: () => void;\n};\n\nconst defaultKindFor = (name: string) => `ux_${name}`;\n\n/** Build a FlowRunnerUx from a set of host effects. Framework-agnostic. */\nexport function createFlowRunnerUx(options: FlowRunnerUxOptions): FlowRunnerUx {\n  const {\n    effects,\n    meta = {},\n    actor = { id: \"flow\", source: \"flow\" },\n    kindFor = defaultKindFor,\n  } = options;\n\n  const dispatcher = createEffectDispatcher(effects, { actor, targetKind: \"ux\" });\n\n  const executors: ExecutorRegistry = {};\n  for (const name of Object.keys(effects)) {\n    executors[kindFor(name)] = async ({ node }: { node: FlowNode }) => {\n      const params = (node.data as { config?: Record<string, unknown> } | undefined)?.config ?? {};\n      const result = await dispatcher.dispatch(name, params);\n      // A UX effect can drive flow control: if it returns the decision sugar\n      // (`{ branch }` or `{ __port }`) — e.g. an interactive \"choose\" effect that\n      // awaits a human pick and returns the chosen port — pass it straight\n      // through so runFlow routes on it. Otherwise wrap the result for the feed.\n      if (result && typeof result === \"object\" && (\"branch\" in result || \"__port\" in result)) {\n        return result;\n      }\n      return { effect: name, result };\n    };\n  }\n\n  const registerKinds = () => {\n    for (const name of Object.keys(effects)) {\n      const m = meta[name] ?? {};\n      registerNodeKind({\n        name: kindFor(name),\n        category: m.category ?? \"output\",\n        label: m.label ?? name,\n        description: m.description ?? `Flow-driven UX effect: ${name}.`,\n        icon: m.icon ?? \"✨\",\n        accent: m.accent ?? \"#8b5cf6\",\n        inputs: [{ id: \"in\" }],\n        outputs: [],\n        configSchema: m.configSchema,\n      });\n    }\n  };\n\n  return {\n    executors,\n    dispatch: dispatcher.dispatch as FlowRunnerUx[\"dispatch\"],\n    effectNames: dispatcher.names,\n    registerKinds,\n  };\n}\n\n/**\n * React hook form — memoizes on the effect-name set + actor id so the returned\n * executors keep a stable identity across renders.\n */\nexport function useFlowRunnerUx(options: FlowRunnerUxOptions): FlowRunnerUx {\n  const key = `${Object.keys(options.effects).sort().join(\",\")}|${options.actor?.id ?? \"flow\"}`;\n  // eslint-disable-next-line react-hooks/exhaustive-deps\n  return useMemo(() => createFlowRunnerUx(options), [key]);\n}\n"]}
+{"version":3,"sources":["../src/ux.ts"],"names":[],"mappings":"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","file":"ux.js","sourcesContent":["/**\n * FlowRunnerUx — the **flow-driven UX** bridge. The headless counterpart to\n * agent-integrations: where that wires an *agent* to host UI surfaces, this\n * wires a *running flow* to host UX. Both share the same primitives from\n * `@particle-academy/fancy-auto-common` (activity bus, effect dispatch).\n *\n * The host registers named UX effects (toast, navigate, confirm, …); this turns\n * each into a flow executor keyed by a node kind (`ux_<effect>` by default), so\n * dropping a `ux_toast` node into a `<FlowEditor>` and running it fires the\n * host's toast. Every dispatch broadcasts an `AutoActivityEvent` (source:\"flow\")\n * for presence / logging. Human-in-the-loop is free: an effect that returns a\n * Promise (e.g. an approval dialog) pauses the run until the user resolves it.\n *\n *   const ux = createFlowRunnerUx({\n *     effects: {\n *       toast:   ({ message }) => toast({ title: message }),\n *       navigate:({ to })      => router.visit(to),\n *       confirm: ({ prompt })  => new Promise(res => openDialog(prompt, res)), // pauses the run\n *     },\n *   });\n *   ux.registerKinds();                       // adds ux_toast / ux_navigate / ux_confirm to the palette\n *   <FlowEditor initial={graph} executors={ux.executors} />\n */\nimport { useMemo } from \"react\";\nimport {\n  createEffectDispatcher,\n  type DispatchActor,\n  type EffectRegistry,\n} from \"@particle-academy/fancy-auto-common\";\nimport { registerNodeKind } from \"./registry/registry\";\nimport type { ConfigField, NodeCategory } from \"./registry/types\";\nimport type { ExecutorRegistry, FlowNode } from \"./types\";\n\nexport type { AutoActivityEvent } from \"@particle-academy/fancy-auto-common\";\n\n/** Per-effect presentation for the palette node kind that drives it. */\nexport type UxEffectMeta = {\n  /** Palette label. Default: the effect name. */\n  label?: string;\n  /** One-line palette description. */\n  description?: string;\n  /** Emoji / glyph for the node header. */\n  icon?: string;\n  /** Header accent color. */\n  accent?: string;\n  /** Palette grouping. Default \"output\". */\n  category?: NodeCategory;\n  /** Config form fields = the effect's params. */\n  configSchema?: ConfigField[];\n  /**\n   * Include the executor's exact resolved input-port map as `$inputs` in the\n   * effect params. Off by default so existing effects keep their payload shape.\n   */\n  includeInputs?: boolean;\n  /**\n   * Make this UX node an inline step instead of a terminal notification. It\n   * gains an `out` port, waits for the effect Promise, then emits its `in`\n   * payload unchanged. This is the native shape for dialogs/overlays whose\n   * lifetime gates the rest of a workflow.\n   */\n  passThrough?: boolean;\n};\n\nexport type FlowRunnerUxOptions = {\n  /** Named host UX effects the flow can invoke. */\n  effects: EffectRegistry;\n  /** Optional per-effect palette metadata (used by `registerKinds`). */\n  meta?: Record<string, UxEffectMeta>;\n  /** Identifies the flow run in emitted activity. Default `{ id: \"flow\", source: \"flow\" }`. */\n  actor?: DispatchActor;\n  /** Map an effect name to its node-kind name. Default `ux_<effect>`. */\n  kindFor?: (effectName: string) => string;\n};\n\nexport type FlowRunnerUx = {\n  /** Executor registry to hand to `<FlowEditor executors>` or `runFlow`. */\n  executors: ExecutorRegistry;\n  /** Invoke an effect imperatively (also emits activity). */\n  dispatch: <R = unknown>(name: string, params?: unknown) => Promise<R>;\n  /** All effect names. */\n  effectNames: () => string[];\n  /** Register a palette node kind per effect (`ux_<effect>`). Idempotent. */\n  registerKinds: () => void;\n};\n\nconst defaultKindFor = (name: string) => `ux_${name}`;\n\n/** Build a FlowRunnerUx from a set of host effects. Framework-agnostic. */\nexport function createFlowRunnerUx(options: FlowRunnerUxOptions): FlowRunnerUx {\n  const {\n    effects,\n    meta = {},\n    actor = { id: \"flow\", source: \"flow\" },\n    kindFor = defaultKindFor,\n  } = options;\n\n  const dispatcher = createEffectDispatcher(effects, { actor, targetKind: \"ux\" });\n\n  const executors: ExecutorRegistry = {};\n  for (const name of Object.keys(effects)) {\n    executors[kindFor(name)] = async ({ node, inputs }: { node: FlowNode; inputs: Record<string, unknown> }) => {\n      const m = meta[name] ?? {};\n      const config = (node.data as { config?: Record<string, unknown> } | undefined)?.config ?? {};\n      const params = m.includeInputs ? { ...config, $inputs: inputs } : config;\n      const result = await dispatcher.dispatch(name, params);\n      // A UX effect can drive flow control: if it returns the decision sugar\n      // (`{ branch }` or `{ __port }`) — e.g. an interactive \"choose\" effect that\n      // awaits a human pick and returns the chosen port — pass it straight\n      // through so runFlow routes on it. Otherwise wrap the result for the feed.\n      if (result && typeof result === \"object\" && (\"branch\" in result || \"__port\" in result)) {\n        return result;\n      }\n      if (m.passThrough) return inputs.in ?? inputs;\n      return { effect: name, result };\n    };\n  }\n\n  const registerKinds = () => {\n    for (const name of Object.keys(effects)) {\n      const m = meta[name] ?? {};\n      registerNodeKind({\n        name: kindFor(name),\n        category: m.category ?? \"output\",\n        label: m.label ?? name,\n        description: m.description ?? `Flow-driven UX effect: ${name}.`,\n        icon: m.icon ?? \"✨\",\n        accent: m.accent ?? \"#8b5cf6\",\n        inputs: [{ id: \"in\" }],\n        outputs: m.passThrough ? [{ id: \"out\" }] : [],\n        emits: m.passThrough ? \"input\" : undefined,\n        sideEffects: \"unsafe-to-replay\",\n        configSchema: m.configSchema,\n      });\n    }\n  };\n\n  return {\n    executors,\n    dispatch: dispatcher.dispatch as FlowRunnerUx[\"dispatch\"],\n    effectNames: dispatcher.names,\n    registerKinds,\n  };\n}\n\n/**\n * React hook form — memoizes on the effect-name set + actor id so the returned\n * executors keep a stable identity across renders.\n */\nexport function useFlowRunnerUx(options: FlowRunnerUxOptions): FlowRunnerUx {\n  const key = `${Object.keys(options.effects).sort().join(\",\")}|${options.actor?.id ?? \"flow\"}`;\n  // eslint-disable-next-line react-hooks/exhaustive-deps\n  return useMemo(() => createFlowRunnerUx(options), [key]);\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/fancy-flow",
-  "version": "0.65.1",
+  "version": "0.66.0",
   "description": "Workflow editor + runner. Six built-in node kits (trigger / action / decision / output / note / subgraph), tokenized theme, topological execution with per-node status. React-flow bundled; consumers npm install fancy-flow and get nothing extra.",
   "repository": {
     "type": "git",
@@ -134,6 +134,16 @@
         "default": "./dist/llm/prism.cjs"
       }
     },
+    "./terminal/fancy-term-host": {
+      "import": {
+        "types": "./dist/terminal/fancy-term-host.d.ts",
+        "default": "./dist/terminal/fancy-term-host.js"
+      },
+      "require": {
+        "types": "./dist/terminal/fancy-term-host.d.cts",
+        "default": "./dist/terminal/fancy-term-host.cjs"
+      }
+    },
     "./fields/react-fancy": {
       "import": {
         "types": "./dist/fields/react-fancy.d.ts",

package/dist/capabilities-BYa5p5jw.d.cts

@@ -1,112 +0,0 @@
-import { F as FlowGraph } from './types-JFYjPJAG.cjs';
-
-/**
- * Host capabilities — the services core nodes need but must never depend on.
- *
- * A node that imports a provider SDK forces every consumer to install it: a
- * workflow app that never calls a model should not inherit an LLM dependency.
- * So core declares the CONTRACT and the host supplies the implementation, the
- * same arrangement `renderDocumentField` already uses for documents.
- *
- * That keeps opinionated nodes in core without their opinions: `llm_branch`
- * ships the routing semantics, port derivation and config UI, while whichever
- * client the host registers — Prism, an OpenAI SDK, a local model, a fake in a
- * test — decides how the question actually gets asked.
- *
- * Registration is deliberately explicit and typed per capability rather than a
- * stringly-keyed bag, so a missing one is a clear error at the seam instead of
- * an undefined somewhere downstream.
- */
-type LlmRoute = {
-    port: string;
-    description?: string;
-};
-type LlmRouteRequest = {
-    /** Optional framing for the decision. */
-    system?: string;
-    /** What the model is deciding about. */
-    prompt: string;
-    /** The ports it must choose between. */
-    routes: LlmRoute[];
-    provider?: string;
-    model?: string;
-    /** Host-resolved credential reference, never a raw key. */
-    credential?: string;
-};
-type LlmRouteChoice = {
-    /** Must be one of the requested route ports. */
-    port: string;
-    /** Why — carried down the chosen port so a run is explainable afterwards. */
-    reason?: string;
-};
-/**
- * The only thing core asks of an LLM: given routes, pick one.
- *
- * Deliberately not a general chat interface. A narrow contract is one a host
- * can satisfy in a few lines over any SDK, and it keeps the choice
- * machine-checkable — an implementation should constrain the model to the
- * declared ports (structured output / enum) rather than parsing prose.
- */
-type LlmClient = {
-    chooseRoute: (request: LlmRouteRequest) => Promise<LlmRouteChoice> | LlmRouteChoice;
-};
-/** Install the host's LLM client. Returns an unregister function. */
-declare function registerLlmClient(client: LlmClient): () => void;
-declare function getLlmClient(): LlmClient | null;
-/**
- * Why a workflow reference could not be resolved.
- *
- * `missing` and `version-mismatch` are deliberately distinct. Collapsing them
- * into a bare null makes "no such workflow" indistinguishable from "that
- * workflow exists, but it is not the one you pinned" — and the second wants an
- * error naming both versions, because it is the interesting failure.
- */
-type WorkflowResolutionFailure = {
-    reason: "missing" | "version-mismatch";
-    /** The version the host actually holds, when it holds one. */
-    available?: number;
-    message?: string;
-};
-type WorkflowResolution = FlowGraph | WorkflowResolutionFailure | null;
-/**
- * Resolve a workflow reference to a runnable graph.
- *
- * `subflow` names another workflow rather than embedding it, so the host owns
- * where workflows live — a database, a file, an API.
- *
- * ## Why `version` is here
- *
- * A workflow another workflow depends on is an INTERFACE, and interfaces need
- * pins. Without a version, a parent goes on calling `invoice-triage`, someone
- * edits that child, and the parent now runs different logic having reported
- * success the whole time — correct-looking, no error, wrong behaviour. The same
- * failure family as the 0.9.0 routing divergence.
- *
- * The parameter lives on the resolver rather than being encoded into the ref
- * string (`invoice-triage@3`) because a stringly-typed protocol is one every
- * host invents differently — the "three vocabularies for one node" problem.
- *
- * Raised by the MOIC Suite consumer, whose `workflow_ref` pins versions and
- * fails loudly on mismatch. Their point: a host COULD NOT implement pinning
- * before this, because the node had no way to ask and the resolver no way to
- * receive.
- *
- * Returning `null` still means "no such workflow". Return a
- * {@link WorkflowResolutionFailure} to distinguish a version mismatch.
- */
-type WorkflowResolver = (ref: string, version?: number) => Promise<WorkflowResolution> | WorkflowResolution;
-/** Narrow a resolver's return value to an explicit failure. */
-declare function isResolutionFailure(value: WorkflowResolution): value is WorkflowResolutionFailure;
-/** Install the host's workflow resolver. Returns an unregister function. */
-declare function registerWorkflowResolver(resolver: WorkflowResolver): () => void;
-declare function getWorkflowResolver(): WorkflowResolver | null;
-type CapabilityId = "llm" | "workflow_resolver" | "document";
-/**
- * Which capabilities are currently satisfied.
- *
- * Exists so a host (or the CLI, or an agent over MCP) can answer "what does
- * this graph need that I haven't wired?" BEFORE a run fails halfway through.
- */
-declare function capabilityStatus(): Record<CapabilityId, boolean>;
-
-export { type CapabilityId as C, type LlmClient as L, type WorkflowResolver as W, type LlmRouteRequest as a, type LlmRoute as b, type LlmRouteChoice as c, type WorkflowResolution as d, type WorkflowResolutionFailure as e, capabilityStatus as f, getLlmClient as g, getWorkflowResolver as h, isResolutionFailure as i, registerWorkflowResolver as j, registerLlmClient as r };

package/dist/capabilities-COOXRiNL.d.ts

@@ -1,112 +0,0 @@
-import { F as FlowGraph } from './types-JFYjPJAG.js';
-
-/**
- * Host capabilities — the services core nodes need but must never depend on.
- *
- * A node that imports a provider SDK forces every consumer to install it: a
- * workflow app that never calls a model should not inherit an LLM dependency.
- * So core declares the CONTRACT and the host supplies the implementation, the
- * same arrangement `renderDocumentField` already uses for documents.
- *
- * That keeps opinionated nodes in core without their opinions: `llm_branch`
- * ships the routing semantics, port derivation and config UI, while whichever
- * client the host registers — Prism, an OpenAI SDK, a local model, a fake in a
- * test — decides how the question actually gets asked.
- *
- * Registration is deliberately explicit and typed per capability rather than a
- * stringly-keyed bag, so a missing one is a clear error at the seam instead of
- * an undefined somewhere downstream.
- */
-type LlmRoute = {
-    port: string;
-    description?: string;
-};
-type LlmRouteRequest = {
-    /** Optional framing for the decision. */
-    system?: string;
-    /** What the model is deciding about. */
-    prompt: string;
-    /** The ports it must choose between. */
-    routes: LlmRoute[];
-    provider?: string;
-    model?: string;
-    /** Host-resolved credential reference, never a raw key. */
-    credential?: string;
-};
-type LlmRouteChoice = {
-    /** Must be one of the requested route ports. */
-    port: string;
-    /** Why — carried down the chosen port so a run is explainable afterwards. */
-    reason?: string;
-};
-/**
- * The only thing core asks of an LLM: given routes, pick one.
- *
- * Deliberately not a general chat interface. A narrow contract is one a host
- * can satisfy in a few lines over any SDK, and it keeps the choice
- * machine-checkable — an implementation should constrain the model to the
- * declared ports (structured output / enum) rather than parsing prose.
- */
-type LlmClient = {
-    chooseRoute: (request: LlmRouteRequest) => Promise<LlmRouteChoice> | LlmRouteChoice;
-};
-/** Install the host's LLM client. Returns an unregister function. */
-declare function registerLlmClient(client: LlmClient): () => void;
-declare function getLlmClient(): LlmClient | null;
-/**
- * Why a workflow reference could not be resolved.
- *
- * `missing` and `version-mismatch` are deliberately distinct. Collapsing them
- * into a bare null makes "no such workflow" indistinguishable from "that
- * workflow exists, but it is not the one you pinned" — and the second wants an
- * error naming both versions, because it is the interesting failure.
- */
-type WorkflowResolutionFailure = {
-    reason: "missing" | "version-mismatch";
-    /** The version the host actually holds, when it holds one. */
-    available?: number;
-    message?: string;
-};
-type WorkflowResolution = FlowGraph | WorkflowResolutionFailure | null;
-/**
- * Resolve a workflow reference to a runnable graph.
- *
- * `subflow` names another workflow rather than embedding it, so the host owns
- * where workflows live — a database, a file, an API.
- *
- * ## Why `version` is here
- *
- * A workflow another workflow depends on is an INTERFACE, and interfaces need
- * pins. Without a version, a parent goes on calling `invoice-triage`, someone
- * edits that child, and the parent now runs different logic having reported
- * success the whole time — correct-looking, no error, wrong behaviour. The same
- * failure family as the 0.9.0 routing divergence.
- *
- * The parameter lives on the resolver rather than being encoded into the ref
- * string (`invoice-triage@3`) because a stringly-typed protocol is one every
- * host invents differently — the "three vocabularies for one node" problem.
- *
- * Raised by the MOIC Suite consumer, whose `workflow_ref` pins versions and
- * fails loudly on mismatch. Their point: a host COULD NOT implement pinning
- * before this, because the node had no way to ask and the resolver no way to
- * receive.
- *
- * Returning `null` still means "no such workflow". Return a
- * {@link WorkflowResolutionFailure} to distinguish a version mismatch.
- */
-type WorkflowResolver = (ref: string, version?: number) => Promise<WorkflowResolution> | WorkflowResolution;
-/** Narrow a resolver's return value to an explicit failure. */
-declare function isResolutionFailure(value: WorkflowResolution): value is WorkflowResolutionFailure;
-/** Install the host's workflow resolver. Returns an unregister function. */
-declare function registerWorkflowResolver(resolver: WorkflowResolver): () => void;
-declare function getWorkflowResolver(): WorkflowResolver | null;
-type CapabilityId = "llm" | "workflow_resolver" | "document";
-/**
- * Which capabilities are currently satisfied.
- *
- * Exists so a host (or the CLI, or an agent over MCP) can answer "what does
- * this graph need that I haven't wired?" BEFORE a run fails halfway through.
- */
-declare function capabilityStatus(): Record<CapabilityId, boolean>;
-
-export { type CapabilityId as C, type LlmClient as L, type WorkflowResolver as W, type LlmRouteRequest as a, type LlmRoute as b, type LlmRouteChoice as c, type WorkflowResolution as d, type WorkflowResolutionFailure as e, capabilityStatus as f, getLlmClient as g, getWorkflowResolver as h, isResolutionFailure as i, registerWorkflowResolver as j, registerLlmClient as r };