@foresthubai/workflow-core 0.3.0

package/src/diagnostics/index.ts

@@ -0,0 +1,11 @@
+export type { DiagnosticSeverity, DiagnosticCategory, Diagnostic, CanvasValidationResult, ValidationResult } from "./diagnostics";
+export {
+  computeNodeDiagnostics,
+  computeEdgeDiagnostics,
+  validateChannel,
+  validateMemory,
+  validateModel,
+  validateFunction,
+  validateFunctionOutputs,
+  validateWorkflowState,
+} from "./diagnostics";

package/src/edge/Edge.ts

@@ -0,0 +1,23 @@
+import type { Expression } from "../api";
+
+export interface EdgeData extends Record<string, unknown> {
+  prompt?: Expression; // agentTask and agentDelegate
+  description?: string; // agentChoice and agentDelegate
+}
+
+/**
+ * Full domain edge entity held on a {@link Canvas}: connectivity topology plus
+ * the optional {@link EdgeData} payload. Low-level core fns that read only
+ * connectivity accept it directly, and the editor's React Flow `Edge[]` is
+ * structurally assignable
+ * without an adapter (core stays free of `@xyflow/react`).
+ */
+export interface Edge {
+  id: string;
+  type?: string;
+  source: string;
+  sourceHandle?: string | null;
+  target: string;
+  targetHandle?: string | null;
+  data?: EdgeData;
+}

package/src/edge/EdgeDefinition.ts

@@ -0,0 +1,45 @@
+import { Parameter } from "../parameter";
+import type { EdgeType } from "./EdgeType";
+
+export interface EdgeDefinition {
+  label: string;
+  description: string;
+  parameters: Parameter[];
+}
+
+export const EDGE_DEFINITIONS: Record<EdgeType, EdgeDefinition> = {
+  agentTask: {
+    label: "Task",
+    description: "Assigns a task to an agent with a prompt",
+    parameters: [{ id: "prompt", label: "Prompt", description: "", type: "expression", expressionType: "string", default: { expression: "", references: [], dataType: "string" } }],
+  },
+  agentChoice: {
+    label: "Choice",
+    description: "A path the agent can choose based on its description",
+    parameters: [
+      { id: "description", label: "Description", description: "", type: "string", default: "When should the agent take this path?" },
+    ],
+  },
+  agentDelegate: {
+    label: "Delegation",
+    description: "Lets an agent hand off control to another agent",
+    parameters: [
+      { id: "description", label: "Description", description: "", type: "string", default: "When should the agent take this path?" },
+      { id: "prompt", label: "Prompt", description: "", type: "expression", expressionType: "string", default: { expression: "", references: [], dataType: "string" } },
+    ],
+  },
+  control: {
+    label: "Control",
+    description: "Sequential control flow between nodes",
+    parameters: [],
+  },
+  tool: {
+    label: "Tool",
+    description: "Tool connection between nodes",
+    parameters: [],
+  },
+};
+
+export function getEdgeDefinition(type: EdgeType): EdgeDefinition {
+  return EDGE_DEFINITIONS[type];
+}

package/src/edge/EdgeType.ts

@@ -0,0 +1,19 @@
+// Edge taxonomy: a plain control/tool edge, or one of the three agent-specific
+// control-flow refinements resolved at connection time from source/target context.
+// Node port handles themselves only carry `control` or `tool`. Tool edges have no
+// agent-specific variant — every tool edge points at an agent by construction.
+export type EdgeType = "control" | "tool" | "agentTask" | "agentChoice" | "agentDelegate";
+
+// All types that behave like control flow (horizontal bezier, side ports)
+export type ControlFlowType = "control" | "agentTask" | "agentChoice" | "agentDelegate";
+
+// All types that behave like tool connections (vertical bezier, top/bottom ports)
+export type ToolFlowType = "tool";
+
+export function isControlFlow(type: EdgeType): type is ControlFlowType {
+  return type === "control" || type === "agentTask" || type === "agentChoice" || type === "agentDelegate";
+}
+
+export function isToolFlow(type: EdgeType): type is ToolFlowType {
+  return type === "tool";
+}

package/src/edge/index.ts

@@ -0,0 +1,8 @@
+// Public surface of the edge module. The base type (EdgeData) lives in
+// ./Edge; this file is a barrel only. Mirrors channel/memory/model.
+
+export type { EdgeData, Edge } from "./Edge";
+export { type EdgeDefinition, getEdgeDefinition, EDGE_DEFINITIONS } from "./EdgeDefinition";
+export { type EdgeType, type ControlFlowType, type ToolFlowType, isControlFlow, isToolFlow } from "./EdgeType";
+export { serialize, deserialize } from "./serialization";
+export type { ApiEdge } from "./serialization";

package/src/edge/serialization.ts

@@ -0,0 +1,83 @@
+import type { Schemas } from "../api";
+import type { Edge, EdgeData } from "./Edge";
+import type { EdgeType } from "./EdgeType";
+
+export type ApiEdge = Schemas["Edge"];
+
+/**
+ * Serialize a domain {@link Edge} to the api `Edge`. The `id` is preserved
+ * (the api requires it). Edge-type-conditional metadata (`prompt`,
+ * `description`) is reattached from the edge's `data` payload.
+ */
+export function serialize(edge: Edge): ApiEdge {
+  const sourceHandle = edge.sourceHandle || "";
+  const targetHandle = edge.targetHandle || "";
+  const edgeType = edge.type as EdgeType | undefined;
+  const from = { nodeId: edge.source, port: sourceHandle };
+  const to = { nodeId: edge.target, port: targetHandle };
+
+  switch (edgeType) {
+    case "agentTask":
+      return {
+        id: edge.id,
+        type: "agentTask",
+        from,
+        to,
+        prompt: (edge.data?.prompt as Schemas["Expression"]) ?? { expression: "", references: [], dataType: "string" },
+      };
+    case "agentChoice":
+      return {
+        id: edge.id,
+        type: "agentChoice",
+        from,
+        to,
+        ...(edge.data?.description ? { description: edge.data.description as string } : {}),
+      };
+    case "agentDelegate":
+      return {
+        id: edge.id,
+        type: "agentDelegate",
+        from,
+        to,
+        ...(edge.data?.prompt ? { prompt: edge.data.prompt as Schemas["Expression"] } : {}),
+        ...(edge.data?.description ? { description: edge.data.description as string } : {}),
+      };
+    case "control":
+      return { id: edge.id, type: "control", from, to };
+    case "tool":
+      return { id: edge.id, type: "tool", from, to };
+    default:
+      return {
+        id: edge.id,
+        type: sourceHandle.startsWith("ctrl") || targetHandle.startsWith("ctrl") ? "control" : "tool",
+        from,
+        to,
+      };
+  }
+}
+
+/**
+ * Convert an api `Edge` into a domain {@link Edge}. The api's `id` is preserved
+ * verbatim (earlier code synthesized `e${index+1}`, breaking roundtrip
+ * identity). Edge-type-conditional metadata (`prompt` on agentTask/agentDelegate;
+ * `description` on agentChoice/agentDelegate) is folded into `data` as
+ * {@link EdgeData}.
+ */
+export function deserialize(apiEdge: ApiEdge): Edge {
+  let data: EdgeData | undefined;
+  if ((apiEdge.type === "agentTask" || apiEdge.type === "agentDelegate") && apiEdge.prompt) {
+    data = { ...data, prompt: apiEdge.prompt };
+  }
+  if ((apiEdge.type === "agentChoice" || apiEdge.type === "agentDelegate") && apiEdge.description) {
+    data = { ...data, description: apiEdge.description };
+  }
+  return {
+    id: apiEdge.id,
+    type: apiEdge.type,
+    source: apiEdge.from.nodeId,
+    sourceHandle: apiEdge.from.port,
+    target: apiEdge.to.nodeId,
+    targetHandle: apiEdge.to.port,
+    ...(data ? { data } : {}),
+  };
+}

package/src/expression/index.ts

@@ -0,0 +1,4 @@
+export type { ParseResult } from "./parser";
+export { parseExpression } from "./parser";
+export type { ResolvedExpr } from "./types";
+export { resolveExpression, isExpression } from "./types";

package/src/expression/parser.ts

@@ -0,0 +1,362 @@
+import jsep from "jsep";
+import type { DataType } from "../api";
+import { ResolvedExpr } from "./types";
+
+export interface ParseResult {
+  isValid: boolean;
+  inferredType: DataType | null;
+  errors: string[];
+}
+
+// Map of placeholder names to their types (populated from variables)
+type TypeContext = Map<string, DataType>;
+
+/**
+ * Parse and validate an expression against C-style type rules.
+ * Replaces ${} placeholders with temporary identifiers, parses with jsep,
+ * infers types from the AST, and validates against the expected type.
+ */
+export function parseExpression(expr: ResolvedExpr): ParseResult {
+  // Handle early returns
+  if (!expr.expression.trim()) {
+    return { isValid: false, inferredType: null, errors: ["Expression is empty"] };
+  }
+  if (expr.variables.some((v) => v === null)) {
+    return { isValid: false, inferredType: null, errors: ["Expression contains stale variable references"] };
+  }
+
+  const errors: string[] = [];
+
+  // 1. Build type context from variables
+  const typeContext: TypeContext = new Map();
+
+  // Replace ${} placeholders with temp identifiers for jsep
+  let parsableExpr = expr.expression;
+
+  // Count placeholders in expression
+  const placeholderCount = (expr.expression.match(/\$\{\}/g) || []).length;
+
+  if (placeholderCount !== expr.variables.length) {
+    errors.push(`Placeholder count (${placeholderCount}) doesn't match reference count (${expr.variables.length})`);
+    return { isValid: false, inferredType: null, errors };
+  }
+
+  expr.variables.forEach((variable, i) => {
+    const placeholder = `__var${i}__`;
+    parsableExpr = parsableExpr.replace("${}", placeholder);
+
+    if (variable) {
+      typeContext.set(placeholder, variable.dataType);
+    } else {
+      // Stale reference - variable was deleted
+      errors.push(`Referenced variable at position ${i + 1} not found`);
+    }
+  });
+
+  // If we have stale/null variables, don't proceed with parsing
+  if (errors.length > 0) {
+    return { isValid: false, inferredType: null, errors };
+  }
+
+  // 2. For string-type expressions, auto-wrap bare text as string literals
+  //    so users don't need to type quotes. E.g. `hello __var0__` → `"hello " + __var0__`
+  if (expr.expectedType === "string") {
+    parsableExpr = wrapStringTemplate(parsableExpr);
+  }
+
+  // 3. Parse with jsep
+  let ast: jsep.Expression;
+  try {
+    ast = jsep(parsableExpr);
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    return { isValid: false, inferredType: null, errors: [`Parse error: ${message}`] };
+  }
+
+  // 4. Infer type by walking AST
+  const inferredType = inferType(ast, typeContext, errors);
+
+  // 5. Check against expected type
+  if (inferredType && expr.expectedType !== inferredType) {
+    // Allow implicit conversions (int → float, etc.)
+    if (!isCompatible(inferredType, expr.expectedType)) {
+      errors.push(`Type mismatch: expression evaluates to '${inferredType}', expected '${expr.expectedType}'`);
+    }
+  }
+
+  return {
+    isValid: errors.length === 0 && inferredType !== null,
+    inferredType,
+    errors,
+  };
+}
+
+/**
+ * Recursively infer the type of an AST node
+ */
+function inferType(node: jsep.Expression, ctx: TypeContext, errors: string[]): DataType | null {
+  switch (node.type) {
+    case "Literal":
+      return inferLiteralType(node as jsep.Literal);
+
+    case "Identifier": {
+      const name = (node as jsep.Identifier).name;
+      const type = ctx.get(name);
+      if (!type) {
+        // Check if it's a placeholder variable that's missing
+        if (name.startsWith("__var") && name.endsWith("__")) {
+          errors.push(`Missing type for variable reference`);
+        } else {
+          errors.push(`Unknown identifier: '${name}'`);
+        }
+      }
+      return type ?? null;
+    }
+
+    case "BinaryExpression":
+      return inferBinaryType(node as jsep.BinaryExpression, ctx, errors);
+
+    case "UnaryExpression":
+      return inferUnaryType(node as jsep.UnaryExpression, ctx, errors);
+
+    case "ConditionalExpression": {
+      // Ternary: condition ? consequent : alternate
+      const cond = node as jsep.ConditionalExpression;
+      const condType = inferType(cond.test, ctx, errors);
+      if (condType !== "bool") {
+        errors.push("Ternary condition must be boolean");
+      }
+      const consType = inferType(cond.consequent, ctx, errors);
+      const altType = inferType(cond.alternate, ctx, errors);
+      if (consType && altType && consType !== altType) {
+        // Allow numeric promotion
+        if (isNumeric(consType) && isNumeric(altType)) {
+          return "float";
+        }
+        errors.push(`Ternary branches must have same type (got '${consType}' and '${altType}')`);
+      }
+      return consType;
+    }
+
+    case "MemberExpression": {
+      // For now, we don't support member expressions in C code generation
+      errors.push("Member expressions (e.g., obj.property) are not supported");
+      return null;
+    }
+
+    case "CallExpression": {
+      return inferCallType(node as jsep.CallExpression, ctx, errors);
+    }
+
+    default:
+      errors.push(`Unsupported expression type: ${node.type}`);
+      return null;
+  }
+}
+
+/**
+ * Infer the type of a literal value
+ */
+function inferLiteralType(node: jsep.Literal): DataType {
+  const value = node.value;
+
+  if (typeof value === "boolean") return "bool";
+
+  if (typeof value === "number") {
+    // Check if it's an integer or float
+    return Number.isInteger(value) ? "int" : "float";
+  }
+
+  if (typeof value === "string") return "string";
+
+  // null/undefined - default to int
+  return "int";
+}
+
+/**
+ * Infer the result type of a binary operation
+ */
+function inferBinaryType(node: jsep.BinaryExpression, ctx: TypeContext, errors: string[]): DataType | null {
+  const leftType = inferType(node.left, ctx, errors);
+  const rightType = inferType(node.right, ctx, errors);
+  const op = node.operator;
+
+  // If either operand failed to type, propagate null
+  if (!leftType || !rightType) return null;
+
+  // String concatenation: string + any → string
+  if (op === "+" && (leftType === "string" || rightType === "string")) {
+    return "string";
+  }
+
+  // Arithmetic operators: int/float → int/float (promote to float if either is float)
+  if (["+", "-", "*", "/"].includes(op)) {
+    if (!isNumeric(leftType) || !isNumeric(rightType)) {
+      errors.push(`Operator '${op}' requires numeric operands (got '${leftType}' and '${rightType}')`);
+      return null;
+    }
+    return leftType === "float" || rightType === "float" ? "float" : "int";
+  }
+
+  // Modulo: int only
+  if (op === "%") {
+    if (leftType !== "int" || rightType !== "int") {
+      errors.push(`Operator '%' requires integer operands (got '${leftType}' and '${rightType}')`);
+      return null;
+    }
+    return "int";
+  }
+
+  // Comparison operators: numeric → bool
+  if (["<", ">", "<=", ">="].includes(op)) {
+    if (!isNumeric(leftType) || !isNumeric(rightType)) {
+      errors.push(`Operator '${op}' requires numeric operands (got '${leftType}' and '${rightType}')`);
+    }
+    return "bool";
+  }
+
+  // Equality operators: any → bool (but types should match)
+  if (["==", "!="].includes(op)) {
+    if (leftType !== rightType && !(isNumeric(leftType) && isNumeric(rightType))) {
+      errors.push(`Comparing incompatible types: '${leftType}' and '${rightType}'`);
+    }
+    return "bool";
+  }
+
+  // Logical operators: bool → bool
+  if (["&&", "||"].includes(op)) {
+    if (leftType !== "bool" || rightType !== "bool") {
+      errors.push(`Operator '${op}' requires boolean operands (got '${leftType}' and '${rightType}')`);
+    }
+    return "bool";
+  }
+
+  // Bitwise operators: int → int
+  if (["&", "|", "^", "<<", ">>"].includes(op)) {
+    if (leftType !== "int" || rightType !== "int") {
+      errors.push(`Bitwise operator '${op}' requires integer operands (got '${leftType}' and '${rightType}')`);
+      return null;
+    }
+    return "int";
+  }
+
+  errors.push(`Unknown operator: '${op}'`);
+  return null;
+}
+
+/**
+ * Infer the result type of a unary operation
+ */
+function inferUnaryType(node: jsep.UnaryExpression, ctx: TypeContext, errors: string[]): DataType | null {
+  const argType = inferType(node.argument, ctx, errors);
+
+  if (!argType) return null;
+
+  // Logical NOT: bool → bool
+  if (node.operator === "!") {
+    if (argType !== "bool") {
+      errors.push(`Logical NOT '!' requires boolean operand (got '${argType}')`);
+    }
+    return "bool";
+  }
+
+  // Unary plus/minus: numeric → same type
+  if (node.operator === "-" || node.operator === "+") {
+    if (!isNumeric(argType)) {
+      errors.push(`Unary '${node.operator}' requires numeric operand (got '${argType}')`);
+    }
+    return argType;
+  }
+
+  // Bitwise NOT: int → int
+  if (node.operator === "~") {
+    if (argType !== "int") {
+      errors.push(`Bitwise NOT '~' requires integer operand (got '${argType}')`);
+    }
+    return "int";
+  }
+
+  errors.push(`Unknown unary operator: '${node.operator}'`);
+  return argType;
+}
+
+/** Cast functions: expression syntax uses int(), float(), bool(), str()
+ * which the code generator translates to C casts / conversion calls.
+ */
+const CAST_FUNCTIONS: Record<string, DataType> = {
+  int: "int",
+  float: "float",
+  bool: "bool",
+  str: "string",
+};
+
+/**
+ * Infer the result type of a cast function call, e.g. int(expr), str(expr).
+ * Any type can be cast to any other type — it's the user's explicit intent.
+ */
+function inferCallType(node: jsep.CallExpression, ctx: TypeContext, errors: string[]): DataType | null {
+  const callee = node.callee;
+  if (callee.type !== "Identifier") {
+    errors.push("Only cast functions are supported (int, float, bool, str)");
+    return null;
+  }
+
+  const name = (callee as jsep.Identifier).name;
+  const targetType = CAST_FUNCTIONS[name];
+  if (!targetType) {
+    errors.push(`Unknown function '${name}'. Available cast functions: int(), float(), bool(), str()`);
+    return null;
+  }
+
+  if (node.arguments.length !== 1) {
+    errors.push(`${name}() expects exactly 1 argument, got ${node.arguments.length}`);
+    return null;
+  }
+
+  // Validate the argument expression (ensure it type-checks). Length checked as 1 above.
+  inferType(node.arguments[0]!, ctx, errors);
+
+  return targetType;
+}
+
+/**
+ * Check if a type is numeric (int or float)
+ */
+function isNumeric(type: DataType | null): boolean {
+  return type === "int" || type === "float";
+}
+
+/**
+ * Check if a type can be implicitly converted to another.
+ * - int ↔ float: both directions (truncation for float→int, common in embedded)
+ * - any → string: allowed (format strings)
+ * - bool is strict: requires explicit cast to/from bool
+ */
+function isCompatible(from: DataType, to: DataType): boolean {
+  if (from === to) return true;
+  if (isNumeric(from) && isNumeric(to)) return true;
+  if (to === "string") return true;
+  return false;
+}
+
+/**
+ * Wrap bare text in a string-type expression into quoted string literals for jsep.
+ * Splits by variable placeholders (__varN__), quotes text segments, joins with +.
+ * E.g. `hello __var0__` → `"hello " + __var0__`
+ */
+function wrapStringTemplate(expr: string): string {
+  // Split by __varN__ placeholders but keep them as delimiters
+  const parts = expr.split(/(__var\d+__)/);
+  const segments: string[] = [];
+
+  for (const part of parts) {
+    if (/^__var\d+__$/.test(part)) {
+      segments.push(part);
+    } else if (part !== "") {
+      const escaped = part.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+      segments.push(`"${escaped}"`);
+    }
+  }
+
+  return segments.join(" + ");
+}

package/src/expression/types.ts

@@ -0,0 +1,30 @@
+import type { NodeOutput } from "../node";
+import type { DataType, Expression } from "../api";
+import type { Variable } from "../variable";
+import { refToLookupKey } from "../variable";
+
+// ResolvedExpr represents an expression with its variable references resolved to runtime variables
+export interface ResolvedExpr {
+  expression: string; // The expression string with variable references, e.g. "${} + ${}"
+  variables: (NodeOutput | null)[]; // List of variables used in the expression (null if stale/invalid)
+  expectedType: DataType; // The expected data type of the expression result
+}
+
+// Resolve an expression by converting variable references to runtime variables
+export function resolveExpression(apiExpr: Expression, availableVars: Record<string, Variable>): ResolvedExpr {
+  return {
+    expression: apiExpr.expression,
+    expectedType: apiExpr.dataType,
+    variables: apiExpr.references.map((ref) => {
+      if (!ref.varId) return null;
+      const key = refToLookupKey(ref);
+      const v = availableVars[key];
+      return v ? { name: v.name, dataType: v.dataType } : null;
+    }),
+  };
+}
+
+// Check if a value is an expression (has references array)
+export function isExpression(value: unknown): value is Expression {
+  return typeof value === "object" && value !== null && "expression" in value && "references" in value;
+}

package/src/function/FunctionDeclaration.ts

@@ -0,0 +1,54 @@
+import type { Expression, Schemas } from "../api";
+import type { ApiVariable } from "../variable";
+import type { DataType } from "../parameter";
+
+/**
+ * The flat call-site signature of a function: identity + version + ports, with no
+ * expressions (the contract's `FunctionInfo`, used both inside `Function` on the wire
+ * and here in the domain). It is the snapshot a {@link FunctionCallNode} caches — to
+ * detect drift against the live declaration and render its ports without a registry
+ * lookup — and the shape {@link buildFunctionNodeDef} consumes.
+ */
+export type FunctionInfo = Schemas["FunctionInfo"];
+
+/**
+ * A function output: its declaration (`uid`/`name`/`dataType`) bundled with the
+ * `expression` that produces it (evaluated in callee scope at the function's end).
+ * Acts as a supertype of {@link ApiVariable}.
+ */
+export interface OutputAssignment {
+  uid: string;
+  name: string;
+  dataType: DataType;
+  expression: Expression;
+}
+
+/**
+ * The domain function declaration: a signature with its outputs bundled
+ * (declaration + assignment per output).
+ * Separate from the function body (which is a canvas of nodes, edges, variables).
+ */
+export interface FunctionDeclaration {
+  id: string;
+  version: number;
+  name: string;
+  arguments: ApiVariable[];
+  outputs: OutputAssignment[];
+}
+
+/**
+ * Project a declaration to the flat call-site signature, dropping the expressions
+ * (the caller has no business storing the callee's internals). Used only when
+ * crossing from declaration to a call-site snapshot — dropping or migrating a
+ * `FunctionCall` node — and by serialization. Never used to represent a function
+ * within the domain.
+ */
+export function toFunctionInfo(fn: FunctionDeclaration): FunctionInfo {
+  return {
+    id: fn.id,
+    version: fn.version,
+    name: fn.name,
+    arguments: fn.arguments,
+    returns: fn.outputs.map(({ uid, name, dataType }) => ({ uid, name, dataType })),
+  };
+}

package/src/function/index.ts

@@ -0,0 +1,3 @@
+export type { OutputAssignment, FunctionDeclaration, FunctionInfo } from "./FunctionDeclaration";
+export { toFunctionInfo } from "./FunctionDeclaration";
+export { serialize, deserialize } from "./serialization";