@foresthubai/workflow-core 0.3.0 → 0.4.0

package/src/parameter/OutputParameter.ts

@@ -1,68 +1,68 @@
-import type { Reference } from "../api";
-import { DataType, FromArgs, unwrapFromArgs } from "./Parameter";
-
-// ============================================================================
-// RUNTIME VALUES
-// ============================================================================
-
-/**
- * Runtime binding stored for a static output. `active=false` means the output
- * is discarded — no variable is produced or assigned. mode/name/target are kept
- * as draft state when inactive so the row can round-trip through an off→on
- * toggle without losing the user's prior choice. The slot's dataType comes from
- * the StaticOutput definition — not carried here.
- */
-export type OutputBinding = { active: boolean; mode: "emit"; name: string } | { active: boolean; mode: "assign"; target: Reference };
-
-/**
- * Runtime entry stored in a list output. Each entry is a user-authored
- * output declaration: either a new variable (emit) with its own uid/name/dataType,
- * or a routing to an existing variable (assign). `name` doubles as the JSON
- * property name in the LLM's structured response and (for emit) the new
- * variable's display name in canvas scope; it must be non-empty and unique
- * within the OutputList parameter (validated by diagnostics).
- *
- * Unlike OutputBinding, the slot's dataType is carried on the declaration
- * itself as a contract — staleness against the target (assign mode) is a
- * diagnostic, not a silent retype. No "discard" mode: removing the entry is
- * how you discard it.
- */
-export type OutputDeclaration =
-  | { mode: "emit"; uid: string; name: string; dataType: DataType }
-  | { mode: "assign"; name: string; dataType: DataType; target: Reference };
-
-// ============================================================================
-// OUTPUT PARAMETER DEFINITIONS
-// ============================================================================
-
-/**
- * A fixed output produced by every instance of this node type. The `id` is
- * both the field name inside `node.arguments` where the OutputBinding lives
- * and the default emit variable name (overridable via the binding's `name`).
- * The dataType may be static or an args-derived lambda.
- */
-export interface StaticOutput {
-  id: string;
-  label: string;
-  type: "static";
-  dataType: FromArgs<DataType>;
-}
-
-/** Resolve a StaticOutput's dataType for the current node arguments. */
-export function resolveStaticOutputDataType(output: StaticOutput, args: Record<string, unknown>): DataType {
-  return unwrapFromArgs(output.dataType, args);
-}
-
-/**
- * A user-managed list of outputs. Entries live in `node.arguments[id]` as
- * `OutputDeclaration[]` — the UI CRUDs the list directly, and each entry
- * contributes one output. Used for Agent's outputDeclarations.
- */
-export interface OutputList {
-  id: string;
-  label: string;
-  type: "list";
-}
-
-/** Output parameters mirror input parameters: intersected with ParameterBase for id/label/etc. */
-export type OutputParameter = StaticOutput | OutputList;
+import type { Reference } from "../api";
+import { DataType, FromArgs, unwrapFromArgs } from "./Parameter";
+
+// ============================================================================
+// RUNTIME VALUES
+// ============================================================================
+
+/**
+ * Runtime binding stored for a static output. `active=false` means the output
+ * is discarded — no variable is produced or assigned. mode/name/target are kept
+ * as draft state when inactive so the row can round-trip through an off→on
+ * toggle without losing the user's prior choice. The slot's dataType comes from
+ * the StaticOutput definition — not carried here.
+ */
+export type OutputBinding = { active: boolean; mode: "emit"; name: string } | { active: boolean; mode: "assign"; target: Reference };
+
+/**
+ * Runtime entry stored in a list output. Each entry is a user-authored
+ * output declaration: either a new variable (emit) with its own uid/name/dataType,
+ * or a routing to an existing variable (assign). `name` doubles as the JSON
+ * property name in the LLM's structured response and (for emit) the new
+ * variable's display name in canvas scope; it must be non-empty and unique
+ * within the OutputList parameter (validated by diagnostics).
+ *
+ * Unlike OutputBinding, the slot's dataType is carried on the declaration
+ * itself as a contract — staleness against the target (assign mode) is a
+ * diagnostic, not a silent retype. No "discard" mode: removing the entry is
+ * how you discard it.
+ */
+export type OutputDeclaration =
+  | { mode: "emit"; uid: string; name: string; dataType: DataType }
+  | { mode: "assign"; name: string; dataType: DataType; target: Reference };
+
+// ============================================================================
+// OUTPUT PARAMETER DEFINITIONS
+// ============================================================================
+
+/**
+ * A fixed output produced by every instance of this node type. The `id` is
+ * both the field name inside `node.arguments` where the OutputBinding lives
+ * and the default emit variable name (overridable via the binding's `name`).
+ * The dataType may be static or an args-derived lambda.
+ */
+export interface StaticOutput {
+  id: string;
+  label: string;
+  type: "static";
+  dataType: FromArgs<DataType>;
+}
+
+/** Resolve a StaticOutput's dataType for the current node arguments. */
+export function resolveStaticOutputDataType(output: StaticOutput, args: Record<string, unknown>): DataType {
+  return unwrapFromArgs(output.dataType, args);
+}
+
+/**
+ * A user-managed list of outputs. Entries live in `node.arguments[id]` as
+ * `OutputDeclaration[]` — the UI CRUDs the list directly, and each entry
+ * contributes one output. Used for Agent's outputDeclarations.
+ */
+export interface OutputList {
+  id: string;
+  label: string;
+  type: "list";
+}
+
+/** Output parameters mirror input parameters: intersected with ParameterBase for id/label/etc. */
+export type OutputParameter = StaticOutput | OutputList;

package/src/parameter/Parameter.ts

@@ -1,243 +1,243 @@
-import type { Expression, Reference } from "../api";
-import type { ChannelType } from "../channel";
-import type { MemoryType } from "../memory";
-import type { ModelType, ModelCapability } from "../model";
-import { refToLookupKey } from "../variable";
-import type { Schemas } from "../api";
-
-export type DataType = Schemas["DataType"];
-
-/**
- * A field that is either a static value of T, or a function that derives T
- * from the owning node's current arguments. Scope is strictly args-only —
- * no access to variables, IO labels, or other canvas state. For wider
- * context, use a purpose-named accessor (e.g. resolveExpressionType).
- */
-export type FromArgs<T> = T | ((args: Record<string, unknown>) => T);
-
-/** Unwrap a FromArgs value against the current node arguments. */
-export function unwrapFromArgs<T>(value: FromArgs<T>, args: Record<string, unknown>): T {
-  return typeof value === "function" ? (value as (args: Record<string, unknown>) => T)(args) : value;
-}
-
-// ============================================================================
-// Parameter definitions
-// ============================================================================
-
-export interface ParameterBase {
-  id: string;
-  label: string;
-  description: string;
-  optional?: boolean;
-  /** Parameter is only active (visible, validated, serialized) when all rules are met. */
-  activationRules?: ActivationRule[];
-}
-
-export interface BasicParam {
-  type: "int" | "float" | "time";
-  default?: number | string;
-}
-
-export interface StringParam {
-  type: "string";
-  multiline?: boolean;
-  default?: string;
-}
-
-export interface BoolParam {
-  type: "bool";
-  default: boolean;
-}
-
-export interface WeekdaysParam {
-  type: "weekdays";
-  default: string[];
-}
-
-export interface SelectionParam {
-  type: "selection";
-  options: Array<{ value: string; label: string }>;
-  default?: string;
-}
-
-export interface ExpressionParam {
-  type: "expression";
-  /** Type can be dynamic (static value or args-only lambda). */
-  expressionType: FromArgs<DataType>;
-  /**
-   * Escape hatch for the variableSelect case: when set, points to the id of a sibling
-   * variableSelect parameter. If that parameter holds a live Reference, the expressionType
-   * is taken from the referenced variable. Falls back to `expressionType` otherwise.
-   */
-  fromReference?: string;
-  /**
-   * Required: An expression always has a value object never an unset state.
-   */
-  default: Expression;
-}
-
-// Reference-select parameters: pick an external entity by id. No `default`.
-
-export interface VariableSelectParam {
-  type: "variableSelect";
-  default?: never;
-}
-
-// Model reference parameter — selects a model id from the static catalog (props)
-// unioned with declared custom models, filtered by model type and capability.
-export interface ModelSelectParam {
-  type: "modelSelect";
-  /** Model types this slot accepts (e.g. ["LLMModel"]). Static list or args-derived lambda. */
-  modelType: FromArgs<ModelType[]>;
-  /** Optional capability filter (e.g. ["chat"]) applied to catalog and declared models alike. */
-  capabilities?: FromArgs<ModelCapability[]>;
-  default?: never;
-}
-
-export interface ChannelSelectParam {
-  type: "channelSelect";
-  /** Channel types this slot accepts. Static list or args-derived lambda. */
-  channelType: FromArgs<ChannelType[]>;
-  default?: never;
-}
-
-export interface MemorySelectParam {
-  type: "memorySelect";
-  /** Memory types this slot accepts (e.g. ["VectorDatabase"]). Static list or args-derived lambda. */
-  memoryType: FromArgs<MemoryType[]>;
-  default?: never;
-}
-
-/**
- * List parameter that binds an agent node to project-declared memory files,
- * each with an access mode (`r` = read-only, `rw` = read + write). The editor
- * holds the array directly; the API schema (`MemoryRef[]`) round-trips 1:1.
- *
- * `default` is required: a list param is always a
- * concrete array, never unset — declare `default: []` for "starts empty".
- */
-export interface MemoryRefsParam {
-  type: "memory-refs";
-  default: Schemas["MemoryRef"][];
-}
-
-/** Union of all reference-select parameter variants, used for type guards. */
-export type ReferenceSelectParam = VariableSelectParam | ChannelSelectParam | MemorySelectParam | ModelSelectParam;
-
-export function isReferenceSelectParam(param: Parameter): param is ParameterBase & ReferenceSelectParam {
-  return param.type === "variableSelect" || param.type === "channelSelect" || param.type === "memorySelect" || param.type === "modelSelect";
-}
-
-export type Parameter =
-  | (ParameterBase & BasicParam)
-  | (ParameterBase & VariableSelectParam)
-  | (ParameterBase & StringParam)
-  | (ParameterBase & BoolParam)
-  | (ParameterBase & WeekdaysParam)
-  | (ParameterBase & SelectionParam)
-  | (ParameterBase & MemorySelectParam)
-  | (ParameterBase & ModelSelectParam)
-  | (ParameterBase & ExpressionParam)
-  | (ParameterBase & ChannelSelectParam)
-  | (ParameterBase & MemoryRefsParam);
-
-// ============================================================================
-// Parameter activation rules
-// ============================================================================
-
-/** Typed union of rules that control whether a parameter is active (visible, validated, serialized). */
-export type ActivationRule =
-  | { type: "parameterIn"; parameterId: string; values: unknown[] }
-  | { type: "isControlFlow" }
-  | { type: "isToolInput" };
-
-/**
- * Evaluate whether a parameter is active (visible, validated, serialized) given current context.
- * All rules must be satisfied (AND logic). Undefined or empty array = always active.
- */
-export function isParameterActive(param: Parameter, parameterValues: Record<string, unknown>, isToolInput: boolean): boolean {
-  if (!param.activationRules?.length) return true;
-  return param.activationRules.every((cond) => {
-    switch (cond.type) {
-      case "isControlFlow":
-        return !isToolInput;
-      case "isToolInput":
-        return isToolInput;
-      case "parameterIn":
-        return cond.values.includes(parameterValues[cond.parameterId]);
-    }
-  });
-}
-
-/**
- * Whether a scalar argument value counts as "unset" for api purposes:
- * `undefined`, `null`, or `""`. Deliberately NOT `false`/`0` (valid values) nor
- * `[]` — an empty list is a real value, since list params are always
- * materialized to a concrete array. Shared by required-param diagnostics and
- * {@link pruneArguments} so "unset" has exactly one definition.
- */
-export function isEmpty(value: unknown): boolean {
-  return value === undefined || value === null || value === "";
-}
-
-/**
- * Prune arguments that must not appear in the api, at the domain→api boundary.
- * Mutates `args` in place. Two reasons an arg is dropped:
- *   1. inactive — its parameter's activation rules aren't met for this context.
- *   2. the parameter {@link isEmpty}.
- */
-export function pruneArguments(args: Record<string, unknown>, parameters: readonly Parameter[], isToolInput = false): void {
-  for (const param of parameters) {
-    const inactive = !!param.activationRules?.length && !isParameterActive(param, args, isToolInput);
-    if (inactive || isEmpty(args[param.id])) {
-      delete args[param.id];
-    }
-  }
-}
-
-// ============================================================================
-// Parameter resolvers
-// ============================================================================
-
-/**
- * Resolve an ExpressionParam's expected dataType. Handles the `fromReference` escape hatch
- * (type taken from a live variableSelect sibling parameter) and falls back to the
- * declared FromArgs<DataType>.
- */
-export function resolveExpressionType(
-  param: ExpressionParam,
-  args: Record<string, unknown>,
-  variables: Record<string, { dataType: DataType }>,
-): DataType {
-  if (param.fromReference) {
-    const ref = args[param.fromReference] as Reference | undefined;
-    if (ref?.varId) {
-      const v = variables[refToLookupKey(ref)];
-      if (v) return v.dataType;
-    }
-  }
-  return unwrapFromArgs(param.expressionType, args);
-}
-
-/** Resolve a capability filter (ModelSelectParam) for the current node arguments. */
-export function resolveCapabilities(
-  param: { capabilities?: FromArgs<ModelCapability[]> },
-  args: Record<string, unknown>,
-): ModelCapability[] | undefined {
-  return param.capabilities === undefined ? undefined : unwrapFromArgs(param.capabilities, args);
-}
-
-/** Resolve the allowed channel types for a ChannelSelectParam. */
-export function resolveChannelTypes(param: ChannelSelectParam, args: Record<string, unknown>): ChannelType[] {
-  return unwrapFromArgs(param.channelType, args);
-}
-
-/** Resolve the allowed memory types for a MemorySelectParam. */
-export function resolveMemoryTypes(param: MemorySelectParam, args: Record<string, unknown>): MemoryType[] {
-  return unwrapFromArgs(param.memoryType, args);
-}
-
-/** Resolve the allowed model types for a ModelSelectParam. */
-export function resolveModelTypes(param: ModelSelectParam, args: Record<string, unknown>): ModelType[] {
-  return unwrapFromArgs(param.modelType, args);
-}
+import type { Expression, Reference } from "../api";
+import type { ChannelType } from "../channel";
+import type { MemoryType } from "../memory";
+import type { ModelType, ModelCapability } from "../model";
+import { refToLookupKey } from "../variable";
+import type { Schemas } from "../api";
+
+export type DataType = Schemas["DataType"];
+
+/**
+ * A field that is either a static value of T, or a function that derives T
+ * from the owning node's current arguments. Scope is strictly args-only —
+ * no access to variables, IO labels, or other canvas state. For wider
+ * context, use a purpose-named accessor (e.g. resolveExpressionType).
+ */
+export type FromArgs<T> = T | ((args: Record<string, unknown>) => T);
+
+/** Unwrap a FromArgs value against the current node arguments. */
+export function unwrapFromArgs<T>(value: FromArgs<T>, args: Record<string, unknown>): T {
+  return typeof value === "function" ? (value as (args: Record<string, unknown>) => T)(args) : value;
+}
+
+// ============================================================================
+// Parameter definitions
+// ============================================================================
+
+export interface ParameterBase {
+  id: string;
+  label: string;
+  description: string;
+  optional?: boolean;
+  /** Parameter is only active (visible, validated, serialized) when all rules are met. */
+  activationRules?: ActivationRule[];
+}
+
+export interface BasicParam {
+  type: "int" | "float" | "time";
+  default?: number | string;
+}
+
+export interface StringParam {
+  type: "string";
+  multiline?: boolean;
+  default?: string;
+}
+
+export interface BoolParam {
+  type: "bool";
+  default: boolean;
+}
+
+export interface WeekdaysParam {
+  type: "weekdays";
+  default: string[];
+}
+
+export interface SelectionParam {
+  type: "selection";
+  options: Array<{ value: string; label: string }>;
+  default?: string;
+}
+
+export interface ExpressionParam {
+  type: "expression";
+  /** Type can be dynamic (static value or args-only lambda). */
+  expressionType: FromArgs<DataType>;
+  /**
+   * Escape hatch for the variableSelect case: when set, points to the id of a sibling
+   * variableSelect parameter. If that parameter holds a live Reference, the expressionType
+   * is taken from the referenced variable. Falls back to `expressionType` otherwise.
+   */
+  fromReference?: string;
+  /**
+   * Required: An expression always has a value object never an unset state.
+   */
+  default: Expression;
+}
+
+// Reference-select parameters: pick an external entity by id. No `default`.
+
+export interface VariableSelectParam {
+  type: "variableSelect";
+  default?: never;
+}
+
+// Model reference parameter — selects a model id from the static catalog (props)
+// unioned with declared custom models, filtered by model type and capability.
+export interface ModelSelectParam {
+  type: "modelSelect";
+  /** Model types this slot accepts (e.g. ["LLMModel"]). Static list or args-derived lambda. */
+  modelType: FromArgs<ModelType[]>;
+  /** Optional capability filter (e.g. ["chat"]) applied to catalog and declared models alike. */
+  capabilities?: FromArgs<ModelCapability[]>;
+  default?: never;
+}
+
+export interface ChannelSelectParam {
+  type: "channelSelect";
+  /** Channel types this slot accepts. Static list or args-derived lambda. */
+  channelType: FromArgs<ChannelType[]>;
+  default?: never;
+}
+
+export interface MemorySelectParam {
+  type: "memorySelect";
+  /** Memory types this slot accepts (e.g. ["VectorDatabase"]). Static list or args-derived lambda. */
+  memoryType: FromArgs<MemoryType[]>;
+  default?: never;
+}
+
+/**
+ * List parameter that binds an agent node to project-declared memory files,
+ * each with an access mode (`r` = read-only, `rw` = read + write). The editor
+ * holds the array directly; the API schema (`MemoryRef[]`) round-trips 1:1.
+ *
+ * `default` is required: a list param is always a
+ * concrete array, never unset — declare `default: []` for "starts empty".
+ */
+export interface MemoryRefsParam {
+  type: "memory-refs";
+  default: Schemas["MemoryRef"][];
+}
+
+/** Union of all reference-select parameter variants, used for type guards. */
+export type ReferenceSelectParam = VariableSelectParam | ChannelSelectParam | MemorySelectParam | ModelSelectParam;
+
+export function isReferenceSelectParam(param: Parameter): param is ParameterBase & ReferenceSelectParam {
+  return param.type === "variableSelect" || param.type === "channelSelect" || param.type === "memorySelect" || param.type === "modelSelect";
+}
+
+export type Parameter =
+  | (ParameterBase & BasicParam)
+  | (ParameterBase & VariableSelectParam)
+  | (ParameterBase & StringParam)
+  | (ParameterBase & BoolParam)
+  | (ParameterBase & WeekdaysParam)
+  | (ParameterBase & SelectionParam)
+  | (ParameterBase & MemorySelectParam)
+  | (ParameterBase & ModelSelectParam)
+  | (ParameterBase & ExpressionParam)
+  | (ParameterBase & ChannelSelectParam)
+  | (ParameterBase & MemoryRefsParam);
+
+// ============================================================================
+// Parameter activation rules
+// ============================================================================
+
+/** Typed union of rules that control whether a parameter is active (visible, validated, serialized). */
+export type ActivationRule =
+  | { type: "parameterIn"; parameterId: string; values: unknown[] }
+  | { type: "isControlFlow" }
+  | { type: "isToolInput" };
+
+/**
+ * Evaluate whether a parameter is active (visible, validated, serialized) given current context.
+ * All rules must be satisfied (AND logic). Undefined or empty array = always active.
+ */
+export function isParameterActive(param: Parameter, parameterValues: Record<string, unknown>, isToolInput: boolean): boolean {
+  if (!param.activationRules?.length) return true;
+  return param.activationRules.every((cond) => {
+    switch (cond.type) {
+      case "isControlFlow":
+        return !isToolInput;
+      case "isToolInput":
+        return isToolInput;
+      case "parameterIn":
+        return cond.values.includes(parameterValues[cond.parameterId]);
+    }
+  });
+}
+
+/**
+ * Whether a scalar argument value counts as "unset" for api purposes:
+ * `undefined`, `null`, or `""`. Deliberately NOT `false`/`0` (valid values) nor
+ * `[]` — an empty list is a real value, since list params are always
+ * materialized to a concrete array. Shared by required-param diagnostics and
+ * {@link pruneArguments} so "unset" has exactly one definition.
+ */
+export function isEmpty(value: unknown): boolean {
+  return value === undefined || value === null || value === "";
+}
+
+/**
+ * Prune arguments that must not appear in the api, at the domain→api boundary.
+ * Mutates `args` in place. Two reasons an arg is dropped:
+ *   1. inactive — its parameter's activation rules aren't met for this context.
+ *   2. the parameter {@link isEmpty}.
+ */
+export function pruneArguments(args: Record<string, unknown>, parameters: readonly Parameter[], isToolInput = false): void {
+  for (const param of parameters) {
+    const inactive = !!param.activationRules?.length && !isParameterActive(param, args, isToolInput);
+    if (inactive || isEmpty(args[param.id])) {
+      delete args[param.id];
+    }
+  }
+}
+
+// ============================================================================
+// Parameter resolvers
+// ============================================================================
+
+/**
+ * Resolve an ExpressionParam's expected dataType. Handles the `fromReference` escape hatch
+ * (type taken from a live variableSelect sibling parameter) and falls back to the
+ * declared FromArgs<DataType>.
+ */
+export function resolveExpressionType(
+  param: ExpressionParam,
+  args: Record<string, unknown>,
+  variables: Record<string, { dataType: DataType }>,
+): DataType {
+  if (param.fromReference) {
+    const ref = args[param.fromReference] as Reference | undefined;
+    if (ref?.varId) {
+      const v = variables[refToLookupKey(ref)];
+      if (v) return v.dataType;
+    }
+  }
+  return unwrapFromArgs(param.expressionType, args);
+}
+
+/** Resolve a capability filter (ModelSelectParam) for the current node arguments. */
+export function resolveCapabilities(
+  param: { capabilities?: FromArgs<ModelCapability[]> },
+  args: Record<string, unknown>,
+): ModelCapability[] | undefined {
+  return param.capabilities === undefined ? undefined : unwrapFromArgs(param.capabilities, args);
+}
+
+/** Resolve the allowed channel types for a ChannelSelectParam. */
+export function resolveChannelTypes(param: ChannelSelectParam, args: Record<string, unknown>): ChannelType[] {
+  return unwrapFromArgs(param.channelType, args);
+}
+
+/** Resolve the allowed memory types for a MemorySelectParam. */
+export function resolveMemoryTypes(param: MemorySelectParam, args: Record<string, unknown>): MemoryType[] {
+  return unwrapFromArgs(param.memoryType, args);
+}
+
+/** Resolve the allowed model types for a ModelSelectParam. */
+export function resolveModelTypes(param: ModelSelectParam, args: Record<string, unknown>): ModelType[] {
+  return unwrapFromArgs(param.modelType, args);
+}