@foresthubai/workflow-core 0.3.0

package/src/parameter/Parameter.ts

@@ -0,0 +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);
+}

package/src/parameter/index.ts

@@ -0,0 +1,33 @@
+export type {
+  DataType,
+  FromArgs,
+  ParameterBase,
+  BasicParam,
+  StringParam,
+  BoolParam,
+  WeekdaysParam,
+  SelectionParam,
+  ExpressionParam,
+  VariableSelectParam,
+  ModelSelectParam,
+  ChannelSelectParam,
+  MemorySelectParam,
+  MemoryRefsParam,
+  ReferenceSelectParam,
+  Parameter,
+  ActivationRule,
+} from "./Parameter";
+export {
+  unwrapFromArgs,
+  isReferenceSelectParam,
+  isParameterActive,
+  isEmpty,
+  pruneArguments,
+  resolveExpressionType,
+  resolveCapabilities,
+  resolveChannelTypes,
+  resolveMemoryTypes,
+  resolveModelTypes,
+} from "./Parameter";
+export type { OutputBinding, OutputDeclaration, StaticOutput, OutputList, OutputParameter } from "./OutputParameter";
+export { resolveStaticOutputDataType } from "./OutputParameter";

package/src/variable/Variable.ts

@@ -0,0 +1,10 @@
+import type { Schemas } from "../api";
+import type { DataType } from "../api";
+
+export type ApiVariable = Schemas["Variable"]; // Differentiate from domain variable type
+
+export type NodeOutputVariable = { kind: "node"; nodeId: string; outputId: string; name: string; dataType: DataType };
+export type DeclaredVariable = { kind: "declared"; uid: string; name: string; dataType: DataType; initialValue?: unknown };
+export type FunctionArgVariable = { kind: "fnarg"; uid: string; name: string; dataType: DataType };
+
+export type Variable = NodeOutputVariable | DeclaredVariable | FunctionArgVariable;

package/src/variable/index.ts

@@ -0,0 +1,16 @@
+// Public surface of the variable module. The discriminated-union types live in
+// ./Variable; the key/lookup/uid helpers and availability computation live in
+// ./operations. This file is a barrel only. Mirrors channel/memory/model.
+
+export type { ApiVariable, NodeOutputVariable, DeclaredVariable, FunctionArgVariable, Variable } from "./Variable";
+export {
+  varKey,
+  declaredVarKey,
+  fnargKey,
+  nodeOutputVarKey,
+  refToLookupKey,
+  ensureUid,
+  ensureUids,
+  paramKey,
+  computeAvailableVariables,
+} from "./operations";

package/src/variable/operations.ts

@@ -0,0 +1,106 @@
+import type { NodeOutput } from "../node";
+import type { Reference } from "../api";
+import type { ApiVariable } from "./Variable";
+import { isToolFlow, type EdgeType, type Edge } from "../edge";
+import { generateId } from "../id";
+import type { Variable } from "./Variable";
+
+// ============================================================================
+// Key Helpers
+// ============================================================================
+
+/** Compute the canonical map key for any CanvasVariable (or AvailableVariable). */
+export function varKey(v: Variable): string {
+  switch (v.kind) {
+    case "node":
+      return `${v.nodeId}:${v.outputId}`;
+    case "declared":
+      return `declared:${v.uid}`;
+    case "fnarg":
+      return `fnarg:${v.uid}`;
+  }
+}
+
+/** Key for a declared variable: `declared:<uid>` */
+export function declaredVarKey(uid: string): string {
+  return `declared:${uid}`;
+}
+
+/** Key for a function argument variable: `fnarg:<uid>` */
+export function fnargKey(uid: string): string {
+  return `fnarg:${uid}`;
+}
+
+/** Key for a node output variable: `<nodeId>:<outputId>` */
+export function nodeOutputVarKey(nodeId: string, outputId: string): string {
+  return `${nodeId}:${outputId}`;
+}
+
+// ============================================================================
+// Reference → Lookup Key
+// ============================================================================
+
+/** Convert a Reference to the canonical lookup key used in the variables record. */
+export function refToLookupKey(ref: Reference): string {
+  switch (ref.srcId) {
+    case "declared":
+      return declaredVarKey(ref.varId);
+    case "fnarg":
+      return fnargKey(ref.varId);
+    default:
+      return nodeOutputVarKey(ref.srcId, ref.varId);
+  }
+}
+
+// ============================================================================
+// Variable UID Helpers for dynamic variable definitions (e.g. Agent output definitions)
+// ============================================================================
+
+/** Create a Variable from a NodeOutput by assigning a uid. If it already has a uid, return as-is. */
+export function ensureUid(v: NodeOutput | ApiVariable): ApiVariable {
+  if ("uid" in v && v.uid) return v as ApiVariable;
+  return { uid: generateId(), name: v.name, dataType: v.dataType };
+}
+
+/** Ensure every NodeOutput/Variable in an array has a uid. */
+export function ensureUids(vars: (NodeOutput | ApiVariable)[]): ApiVariable[] {
+  return vars.map(ensureUid);
+}
+
+/** Get the binding key for a Variable — always its uid. */
+export function paramKey(p: ApiVariable): string {
+  return p.uid;
+}
+
+/**
+ * Pure function that computes available variables for a canvas from its own
+ * variables record + edges. Function canvases are self-contained: only their
+ * own declared variables, node outputs, and function arguments are visible;
+ * main-canvas state is never merged in.
+ *
+ * Only `type`/`target` are read, but the param takes the shared structural
+ * {@link Edge} so there's one edge shape across core — workflow-builder
+ * still passes its React Flow `Edge[]` without an adapter, and core stays free
+ * of `@xyflow/react`.
+ */
+export function computeAvailableVariables(
+  variables: Record<string, Variable>,
+  canvasEdges: readonly Edge[],
+): { list: Variable[]; lookup: Record<string, Variable> } {
+  const list: Variable[] = [];
+  const lookup: Record<string, Variable> = {};
+
+  // Node outputs routed to a tool port are scoped to the agent — exclude them.
+  const toolNodeIds = new Set<string>();
+  for (const edge of canvasEdges) {
+    if (isToolFlow(edge.type as EdgeType)) toolNodeIds.add(edge.target);
+  }
+
+  for (const [key, variable] of Object.entries(variables)) {
+    if (variable.kind === "node" && toolNodeIds.has(variable.nodeId)) continue;
+    list.push(variable);
+    lookup[key] = variable;
+  }
+
+  return { list, lookup };
+}

package/src/workflow/Workflow.ts

@@ -0,0 +1,41 @@
+import type { Channel } from "../channel";
+import type { Memory } from "../memory";
+import type { Model } from "../model";
+import type { Node } from "../node";
+import type { FunctionDeclaration } from "../function";
+import type { Edge } from "../edge";
+import type { Variable } from "../variable";
+import type { Schemas } from "../api";
+
+export type ApiWorkflow = Schemas["Workflow"];
+
+/**
+ * The id of the project's main canvas. All other canvas ids identify function
+ * definitions. Lives here next to {@link Workflow} (which keys canvases
+ * by this value) so the headless validator can reason about canvas scope
+ * without depending on a UI store.
+ */
+export const MAIN_CANVAS_ID = "main" as const;
+
+/**
+ * In-memory domain state for a workflow, which the headless validator consumes.
+ * NOT a persistence format, NOT the format the editor uses internally (Zustand stores).
+ * This format is used as intermediary when importing/exporting to api format and to run validation
+ */
+export interface Workflow {
+  canvases: Record<string, Canvas>;
+  functions: Record<string, FunctionDeclaration>;
+  channels: Record<string, Channel>;
+  memory: Record<string, Memory>;
+  models: Record<string, Model>;
+}
+
+/**
+ * One canvas's worth of in-memory domain state — the body of either the main canvas
+ * or a function.
+ */
+export interface Canvas {
+  nodes: Node[];
+  edges: Edge[];
+  variables: Record<string, Variable>;
+}

package/src/workflow/index.ts

@@ -0,0 +1,3 @@
+export type { ApiWorkflow, Workflow, Canvas } from "./Workflow";
+export { MAIN_CANVAS_ID } from "./Workflow";
+export { serialize, deserialize, computeVariablesFromNodes } from "./serialization";