@foresthubai/workflow-core 0.3.0

package/src/node/DataNode.ts

@@ -0,0 +1,41 @@
+import { NodeBase } from "./Node";
+import type { Expression, Reference } from "../api";
+import { NodeCategory } from "./constants";
+import { NodeDefinition } from "./NodeDefinition";
+
+export interface SetVariableNode extends NodeBase {
+  type: "SetVariable";
+  arguments: {
+    variable: Reference | undefined;
+    value: Expression;
+  };
+}
+
+export type DataNodeType = "SetVariable";
+export type DataNode = SetVariableNode;
+
+// Node Definitions
+
+export const SetVariableNodeDefinition: NodeDefinition = {
+  type: "SetVariable",
+  label: "Set Variable",
+  category: NodeCategory.Data,
+  description: "Assign a new value to an existing variable",
+  parameters: [
+    {
+      id: "variable",
+      label: "Variable",
+      description: "The variable to update",
+      type: "variableSelect",
+    },
+    {
+      id: "value",
+      label: "Value",
+      description: "Expression to assign",
+      type: "expression",
+      expressionType: "int", // fallback; actual type is derived from the target variable (see fromReference)
+      fromReference: "variable",
+      default: { expression: "", references: [], dataType: "int" },
+    },
+  ],
+};

package/src/node/FunctionNode.ts

@@ -0,0 +1,76 @@
+import { NodeBase } from "./Node";
+import type { Expression } from "../api";
+import type { FunctionInfo } from "../function";
+import type { DataType } from "../api";
+import { OutputBinding } from "../parameter";
+import { NodeDefinition } from "./NodeDefinition";
+import { NodeCategory } from "./constants";
+import { paramKey } from "../variable";
+
+// Function Call Node - invokes a user-defined function.
+// Arguments are flat — keyed by Variable uid. Input argument uids map to Expression,
+// return uids map to OutputBinding. Same shape as every other node, so the rest of
+// the system (parameter editors, output bindings, merge/update) treats FunctionCall
+// uniformly. Outputs are derived on-the-fly via buildFunctionNodeDef from
+// functionInfo.returns — there is no registered NodeDefinition.
+export interface FunctionCallNode extends NodeBase {
+  type: "FunctionCall";
+  functionInfo: FunctionInfo; // Snapshot at creation; may be stale vs registry
+  // Flat bag keyed by Variable uid (Expression for args, OutputBinding for returns),
+  // plus the reserved `toolDescription` key (string) for the tool-mode parameter.
+  arguments: Record<string, Expression | OutputBinding | string>;
+}
+
+export type FunctionCallNodeType = "FunctionCall";
+
+// FunctionNodeDefinition extends NodeDefinition with function-specific fields
+// Used by NodeLibrary to create new FunctionCall nodes
+export interface FunctionNodeDefinition extends NodeDefinition {
+  type: "FunctionCall";
+  functionInfo: FunctionInfo; // Metadata about the function being called
+}
+
+/**
+ * Build a FunctionCall NodeDefinition from FunctionInfo. Pure — takes an
+ * optional translator function so the headless validator can call it without
+ * an i18n runtime; workflow-builder passes `i18n.t.bind(i18n)` to get
+ * translated descriptions. Defaults to identity (returns the key) when no
+ * translator is supplied; validation logic ignores description strings.
+ */
+export function buildFunctionNodeDef(
+  fn: FunctionInfo,
+  t: (key: string, params?: Record<string, unknown>) => string = (key) => key,
+): FunctionNodeDefinition {
+  return {
+    type: "FunctionCall",
+    functionInfo: fn,
+    label: fn.name,
+    category: NodeCategory.Function,
+    description: t("builder.functionCallDesc", { name: fn.name }),
+    parameters: [
+      ...fn.arguments.map((param) => ({
+        id: paramKey(param),
+        label: param.name,
+        description: t("builder.functionParamDesc", { name: param.name }),
+        type: "expression" as const,
+        expressionType: param.dataType as DataType,
+        default: { expression: "", references: [], dataType: param.dataType as DataType },
+        activationRules: [{ type: "isControlFlow" as const }],
+      })),
+      {
+        id: "toolDescription",
+        label: "Tool Description",
+        description: "Description shown to the agent when this function is wired as a tool",
+        type: "string" as const,
+        multiline: true,
+        activationRules: [{ type: "isToolInput" as const }],
+      },
+    ],
+    outputs: fn.returns.map((ret) => ({
+      id: paramKey(ret),
+      label: ret.name,
+      type: "static" as const,
+      dataType: ret.dataType as DataType,
+    })),
+  };
+}

package/src/node/InputNode.ts

@@ -0,0 +1,185 @@
+import { NodeBase } from "./Node";
+import type { Expression } from "../api";
+import { OutputBinding } from "../parameter";
+import { NodeCategory, NodeTag } from "./constants";
+import { NodeDefinition } from "./NodeDefinition";
+
+export interface ReadPinNode extends NodeBase {
+  type: "ReadPin";
+  arguments: {
+    pinReference: string | undefined;
+    signalType: "digital" | "analog";
+    output: OutputBinding;
+    toolDescription?: string;
+  };
+}
+
+export interface SerialReadNode extends NodeBase {
+  type: "SerialRead";
+  arguments: {
+    portReference: string | undefined;
+    prompt?: string;
+    output: OutputBinding;
+  };
+}
+
+// Retriever - provides RAG retrieval capability to agents
+export interface RetrieverNode extends NodeBase {
+  type: "Retriever";
+  arguments: {
+    memoryReference: string;
+    topK: number | undefined;
+    query: Expression;
+    output: OutputBinding;
+    toolDescription?: string;
+  };
+}
+
+// WebFetch - fetches a URL and returns extracted text
+export interface WebFetchNode extends NodeBase {
+  type: "WebFetch";
+  arguments: {
+    url: Expression;
+    maxChars: number | undefined;
+    output: OutputBinding;
+  };
+}
+
+export type InputNodeType = "ReadPin" | "SerialRead" | "Retriever" | "WebFetch";
+export type InputNode = ReadPinNode | SerialReadNode | RetrieverNode | WebFetchNode;
+
+// Node Definitions
+
+export const ReadPinNodeDefinition: NodeDefinition = {
+  type: "ReadPin",
+  label: "Read Pin",
+  category: NodeCategory.Input,
+  tags: [NodeTag.Pin],
+  description: "Read data from a pin",
+  outputs: [
+    {
+      id: "output",
+      label: "Pin Value",
+      type: "static",
+      dataType: (args) => ((args as ReadPinNode["arguments"]).signalType === "digital" ? "bool" : "int"),
+    },
+  ],
+  parameters: [
+    {
+      id: "pinReference",
+      label: "Pin",
+      description: "IO pin to read from",
+      type: "channelSelect",
+      channelType: (args) => ((args as ReadPinNode["arguments"]).signalType === "digital" ? ["GPIOIN"] : ["ADC"]),
+    },
+    {
+      id: "signalType",
+      label: "Signal Type",
+      description: "Type of signal",
+      type: "selection",
+      default: "digital",
+      options: [
+        { value: "digital", label: "Digital" },
+        { value: "analog", label: "Analog" },
+      ],
+    },
+    {
+      id: "toolDescription",
+      label: "Tool Description",
+      description: "Description shown to the agent when this node is wired as a tool",
+      type: "string",
+      multiline: true,
+      activationRules: [{ type: "isToolInput" }],
+    },
+  ],
+};
+
+export const RetrieverNodeDefinition: NodeDefinition = {
+  type: "Retriever",
+  label: "Retriever",
+  category: NodeCategory.Input,
+  description: "Retrieves relevant documents from a knowledge base",
+  outputs: [{ id: "output", label: "Retrieved Documents", type: "static", dataType: "string" }],
+  parameters: [
+    {
+      id: "memoryReference",
+      label: "Vector Database",
+      description: "The vector database to search",
+      type: "memorySelect",
+      memoryType: ["VectorDatabase"],
+    },
+    {
+      id: "topK",
+      label: "Top K",
+      description: "Number of results to retrieve",
+      type: "int",
+      default: 5,
+    },
+    {
+      id: "query",
+      label: "Query",
+      description: "Search query expression",
+      type: "expression",
+      expressionType: "string",
+      default: { expression: "", references: [], dataType: "string" },
+    },
+    {
+      id: "toolDescription",
+      label: "Tool Description",
+      description: "Description shown to the agent when this node is wired as a tool",
+      type: "string",
+      multiline: true,
+      activationRules: [{ type: "isToolInput" }],
+    },
+  ],
+};
+
+export const WebFetchNodeDefinition: NodeDefinition = {
+  type: "WebFetch",
+  label: "Web Fetch",
+  category: NodeCategory.Input,
+  description: "Fetches a URL and returns extracted text",
+  outputs: [{ id: "output", label: "Fetched Text", type: "static", dataType: "string" }],
+  parameters: [
+    {
+      id: "url",
+      label: "URL",
+      description: "URL to fetch (http or https)",
+      type: "expression",
+      expressionType: "string",
+      default: { expression: "", references: [], dataType: "string" },
+    },
+    {
+      id: "maxChars",
+      label: "Max Characters",
+      description: "Maximum characters of extracted text to return",
+      type: "int",
+      optional: true,
+    },
+  ],
+};
+
+export const SerialReadNodeDefinition: NodeDefinition = {
+  type: "SerialRead",
+  label: "Serial Read",
+  category: NodeCategory.Input,
+  tags: [NodeTag.Serial],
+  description: "Read string from serial port",
+  outputs: [{ id: "output", label: "Serial Data", type: "static", dataType: "string" }],
+  parameters: [
+    {
+      id: "portReference",
+      label: "Port",
+      description: "Serial port to read from",
+      type: "channelSelect",
+      channelType: ["UART"],
+    },
+    {
+      id: "prompt",
+      label: "Input prompt",
+      description: "Prompt for the serial read operation",
+      type: "string",
+      optional: true,
+    },
+  ],
+};

package/src/node/LogicNode.ts

@@ -0,0 +1,33 @@
+import { NodeBase } from "./Node";
+import type { Expression } from "../api";
+import { NodeCategory } from "./constants";
+import { NodeDefinition } from "./NodeDefinition";
+
+export interface IfNode extends NodeBase {
+  type: "If";
+  arguments: {
+    condition: Expression;
+  };
+}
+
+export type LogicNodeType = "If";
+export type LogicNode = IfNode;
+
+// Node Definitions
+
+export const IfNodeDefinition: NodeDefinition = {
+  type: "If",
+  label: "If Condition Node",
+  category: NodeCategory.Logic,
+  description: "Conditional branching based on boolean expression",
+  parameters: [
+    {
+      id: "condition",
+      label: "Condition",
+      description: "Boolean expression (e.g., ${Input_1.value} > 50)",
+      type: "expression",
+      expressionType: "bool",
+      default: { expression: "", references: [], dataType: "bool" },
+    },
+  ],
+};

package/src/node/MqttNode.ts

@@ -0,0 +1,127 @@
+import { NodeBase } from "./Node";
+import type { Expression } from "../api";
+import { OutputBinding } from "../parameter";
+import { NodeCategory, NodeTag } from "./constants";
+import { NodeDefinition } from "./NodeDefinition";
+
+// MQTT Publish - publishes a single value to an MQTT topic
+export interface MqttPublishNode extends NodeBase {
+  type: "MqttPublish";
+  arguments: {
+    channelReference: string;
+    dataType: "int" | "float" | "bool" | "string";
+    value: Expression;
+    qos: "0" | "1" | "2";
+    retain: boolean;
+  };
+}
+
+// On MQTT Message - fires when a message is received on a subscribed topic
+export interface OnMqttMessageNode extends NodeBase {
+  type: "OnMqttMessage";
+  arguments: {
+    channelReference: string;
+    dataType: "int" | "float" | "bool" | "string";
+    output: OutputBinding;
+  };
+}
+
+export type MqttNodeType = "MqttPublish" | "OnMqttMessage";
+export type MqttNode = MqttPublishNode | OnMqttMessageNode;
+
+// Node Definitions
+
+export const MqttPublishNodeDefinition: NodeDefinition = {
+  type: "MqttPublish",
+  label: "MQTT Publish",
+  category: NodeCategory.Output,
+  tags: [NodeTag.Network],
+  description: "Publish a value to an MQTT topic",
+  parameters: [
+    {
+      id: "channelReference",
+      label: "Channel",
+      description: "MQTT channel to publish through",
+      type: "channelSelect",
+      channelType: ["MQTT"],
+    },
+    {
+      id: "dataType",
+      label: "Data Type",
+      description: "Data type of the value to publish",
+      type: "selection",
+      options: [
+        { value: "int", label: "Integer" },
+        { value: "float", label: "Float" },
+        { value: "bool", label: "Boolean" },
+        { value: "string", label: "String" },
+      ],
+      default: "string",
+    },
+    {
+      id: "value",
+      label: "Value",
+      description: "Value to publish",
+      type: "expression",
+      expressionType: (args) => (args as MqttPublishNode["arguments"]).dataType,
+      default: { expression: "", references: [], dataType: "string" },
+    },
+    {
+      id: "qos",
+      label: "QoS",
+      description: "Quality of Service level",
+      type: "selection",
+      options: [
+        { value: "0", label: "0 - At most once" },
+        { value: "1", label: "1 - At least once" },
+        { value: "2", label: "2 - Exactly once" },
+      ],
+      default: "0",
+    },
+    {
+      id: "retain",
+      label: "Retain",
+      description: "Whether the broker should retain the message",
+      type: "bool",
+      default: false,
+    },
+  ],
+};
+
+export const OnMqttMessageNodeDefinition: NodeDefinition = {
+  type: "OnMqttMessage",
+  label: "On MQTT Message",
+  category: NodeCategory.Trigger,
+  tags: [NodeTag.Network],
+  description: "Fires when a message is received on a subscribed MQTT topic",
+  outputs: [
+    {
+      id: "output",
+      label: "Message Value",
+      type: "static",
+      dataType: (args) => (args as OnMqttMessageNode["arguments"]).dataType,
+    },
+  ],
+  parameters: [
+    {
+      id: "channelReference",
+      label: "Channel",
+      description: "MQTT channel to subscribe through",
+      type: "channelSelect",
+      channelType: ["MQTT"],
+    },
+    {
+      id: "dataType",
+      label: "Data Type",
+      description: "Expected data type of the received message value",
+      type: "selection",
+      options: [
+        { value: "int", label: "Integer" },
+        { value: "float", label: "Float" },
+        { value: "bool", label: "Boolean" },
+        { value: "string", label: "String" },
+      ],
+      default: "string",
+    },
+  ],
+};

package/src/node/Node.ts

@@ -0,0 +1,61 @@
+// Domain Node — the base shape every node variant builds on. NodeBase is the
+// generic, untyped-parameters shape used wherever a node is handled generically
+// (e.g. React Flow nodes); NodeData is the discriminated union over the
+// per-variant interfaces (InputNode, AgentNode, …) for strongly-typed work.
+// Mirrors how channel/memory/model keep their base shape in a same-named file and
+// leave index.ts as a pure barrel. The per-variant interfaces import NodeBase
+// from here directly, not via the barrel.
+
+import type { DataType } from "../api";
+import { InputNode, InputNodeType } from "./InputNode";
+import { OutputNode, OutputNodeType } from "./OutputNode";
+import { AgentNode, AgentNodeType } from "./AgentNode";
+import { LogicNode, LogicNodeType } from "./LogicNode";
+import { DataNode, DataNodeType } from "./DataNode";
+import { TriggerNode, TriggerNodeType } from "./TriggerNode";
+import { ToolNode, ToolNodeType } from "./ToolNode";
+import { FunctionCallNode, FunctionCallNodeType } from "./FunctionNode";
+import { MqttNode, MqttNodeType } from "./MqttNode";
+
+export type NodeOutput = { name: string; dataType: DataType };
+export type NodeType =
+  | InputNodeType
+  | OutputNodeType
+  | AgentNodeType
+  | LogicNodeType
+  | DataNodeType
+  | TriggerNodeType
+  | ToolNodeType
+  | FunctionCallNodeType
+  | MqttNodeType;
+
+/**
+ * NodeData represents the runtime data for a node in the workflow builder.
+ * It is a union type of all specific node types, each with their own typed parameters.
+ * Use this type when you need strong typing for a specific node.
+ */
+export type NodeData = InputNode | OutputNode | AgentNode | LogicNode | DataNode | TriggerNode | ToolNode | FunctionCallNode | MqttNode;
+
+/**
+ * Full domain node entity held on a {@link Canvas}: the {@link NodeData}
+ * payload plus its canvas layout position, flattened. id/type/arguments/label
+ * come from NodeData; only `position` is added. The editor projects this into
+ * a React Flow node (adding the display type) at its store boundary.
+ */
+export type Node = NodeData & { position: { x: number; y: number } };
+
+/**
+ * NodeBase is a generic interface for all node instances.
+ * It uses an untyped parameters record to allow generic parameter handling (e.g., in React Flow nodes).
+ * Narrow to NodeData for specific node operations that require typed parameters.
+ *
+ * Per-output bindings (emit/assign/discard) live as flat entries inside `arguments`,
+ * keyed by the output id — same namespace as parameter values. List output entries
+ * (e.g. AgentNode's `outputDeclarations`) bundle their binding alongside their variable
+ * declaration as OutputDeclaration[].
+ */
+export interface NodeBase extends Record<string, unknown> {
+  id: string; // Same as the React Flow node ID
+  type: NodeType; // Node discriminator
+  label?: string; // User-editable display label (falls back to nodeDefinition.label)
+}

package/src/node/NodeDefinition.ts

@@ -0,0 +1,37 @@
+import { NodeType } from "./Node";
+import { NodeCategory, NodeTag } from "./constants";
+import { OutputParameter, Parameter } from "../parameter";
+
+/**
+ * NodeDefinition describes static class-level node metadata.
+ * Methods (getPorts) are optional and take no arguments for static port definitions.
+ * Instance-dependent behavior lives in NodeBehavior.ts instead.
+ */
+export interface NodeDefinition {
+  type: NodeType; // Node discriminator
+  label: string; // Human-readable, displayed name
+  category: NodeCategory; // Category for grouping (e.g., 'Input', 'Output', 'Logic')
+  description: string; // Description of what the node does
+  parameters: Parameter[]; // Parameter definitions for the node.
+  outputs?: OutputParameter[]; // Declarative output definitions — consumed by getNodeAvailableOutput() to compute a node's outputs
+  tags?: NodeTag[]; // Cross-cutting subsystem labels (Network, Pin, Serial, ...)
+  isUnremovable?: boolean; // Whether the node cannot be added or removed by a user
+  isSingleton?: boolean; // Whether only one instance of this node can exist in a canvas
+  canBranch?: boolean; // Whether the control output port may fan out to multiple branches (tool output ports are always multi-target)
+}
+
+// =============================================================================
+// PORT DEFINITIONS
+// =============================================================================
+
+// Port represents a connectable port of a node
+export interface Port {
+  id: string;
+  type: "control" | "tool";
+  label?: string;
+}
+
+export interface PortDefinitions {
+  input: Port[];
+  output: Port[];
+}

package/src/node/NodeRegistry.ts

@@ -0,0 +1,85 @@
+import { ReadPinNodeDefinition, SerialReadNodeDefinition, RetrieverNodeDefinition, WebFetchNodeDefinition } from "./InputNode";
+import { AgentNodeDefinition } from "./AgentNode";
+import {
+  DelayNodeDefinition,
+  TickerNodeDefinition,
+  AlarmNodeDefinition,
+  OnFunctionCallNodeDefinition,
+  OnStartupNodeDefinition,
+  OnPinEdgeNodeDefinition,
+  OnSerialReceiveNodeDefinition,
+  OnThresholdNodeDefinition,
+} from "./TriggerNode";
+import { WebSearchToolNodeDefinition } from "./ToolNode";
+import { NodeType } from "./Node";
+import { NodeCategory } from "./constants";
+import { SerialWriteNodeDefinition, WritePinNodeDefinition } from "./OutputNode";
+import { IfNodeDefinition } from "./LogicNode";
+import { SetVariableNodeDefinition } from "./DataNode";
+import { MqttPublishNodeDefinition, OnMqttMessageNodeDefinition } from "./MqttNode";
+import { NodeDefinition } from "./NodeDefinition";
+
+/**
+ * Central registry for all node definitions.
+ */
+class NodeDefinitionRegistry {
+  private nodes: Map<NodeType, NodeDefinition> = new Map();
+  private initialized = false;
+
+  initialize() {
+    if (this.initialized) return;
+
+    // Register all nodes
+    this.register(ReadPinNodeDefinition);
+    this.register(SerialReadNodeDefinition);
+    this.register(WritePinNodeDefinition);
+    this.register(SerialWriteNodeDefinition);
+    this.register(AgentNodeDefinition);
+    this.register(IfNodeDefinition);
+    this.register(SetVariableNodeDefinition);
+    // Register trigger nodes
+    this.register(OnFunctionCallNodeDefinition);
+    this.register(DelayNodeDefinition);
+    this.register(TickerNodeDefinition);
+    this.register(AlarmNodeDefinition);
+    this.register(OnStartupNodeDefinition);
+    this.register(OnPinEdgeNodeDefinition);
+    this.register(OnSerialReceiveNodeDefinition);
+    this.register(OnThresholdNodeDefinition);
+    // Register tool nodes
+    this.register(WebSearchToolNodeDefinition);
+    // Register input tool nodes
+    this.register(RetrieverNodeDefinition);
+    this.register(WebFetchNodeDefinition);
+    // Register MQTT nodes
+    this.register(MqttPublishNodeDefinition);
+    this.register(OnMqttMessageNodeDefinition);
+
+    this.initialized = true;
+  }
+
+  private register(definition: NodeDefinition) {
+    this.nodes.set(definition.type, definition);
+  }
+
+  getAll(): NodeDefinition[] {
+    return Array.from(this.nodes.values());
+  }
+
+  getAllCategories(): NodeCategory[] {
+    const categories = new Set(this.getAll().map((node) => node.category));
+    return Array.from(categories).sort();
+  }
+
+  getByType(type: NodeType): NodeDefinition | undefined {
+    return this.nodes.get(type);
+  }
+
+  getByCategory(category: NodeCategory): NodeDefinition[] {
+    return this.getAll().filter((node) => node.category === category);
+  }
+}
+
+// Create and initialize the registry
+export const NodeRegistry = new NodeDefinitionRegistry();
+NodeRegistry.initialize();