@foresthubai/workflow-core 0.3.0 → 0.4.0

package/src/expression/types.ts

@@ -1,30 +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;
-}
+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

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

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

package/src/function/serialization.ts

@@ -1,40 +1,40 @@
-import type { Expression } from "../api";
-import type { FunctionDeclaration, FunctionInfo } from "./FunctionDeclaration";
-import { toFunctionInfo } from "./FunctionDeclaration";
-
-/**
- * The two wire pieces a {@link FunctionDeclaration} splits into. The contract keeps
- * the signature (`functionInfo`) and the return-value expressions (`outputAssignments`)
- * apart; the domain bundles them on `outputs`. The function *body*
- * (nodes/edges/declaredVariables) is added separately by the workflow serializer —
- * this only handles the declaration ⇄ wire mapping.
- */
-export interface SerializedFunction {
-  functionInfo: FunctionInfo;
-  outputAssignments: Record<string, Expression>;
-}
-
-/** Domain declaration → wire pieces: flatten the signature and lift each output's
- *  expression into the `outputAssignments` map keyed by output uid. */
-export function serialize(fn: FunctionDeclaration): SerializedFunction {
-  const outputAssignments: Record<string, Expression> = {};
-  for (const o of fn.outputs) outputAssignments[o.uid] = o.expression;
-  return { functionInfo: toFunctionInfo(fn), outputAssignments };
-}
-
-/** Wire pieces → domain declaration: bundle each `return` with its assignment. A
- *  return with no stored assignment gets an empty expression of the right dataType. */
-export function deserialize(functionInfo: FunctionInfo, outputAssignments: Record<string, Expression>): FunctionDeclaration {
-  return {
-    id: functionInfo.id,
-    version: functionInfo.version,
-    name: functionInfo.name,
-    arguments: functionInfo.arguments,
-    outputs: functionInfo.returns.map((r) => ({
-      uid: r.uid,
-      name: r.name,
-      dataType: r.dataType,
-      expression: outputAssignments[r.uid] ?? { expression: "", references: [], dataType: r.dataType },
-    })),
-  };
-}
+import type { Expression } from "../api";
+import type { FunctionDeclaration, FunctionInfo } from "./FunctionDeclaration";
+import { toFunctionInfo } from "./FunctionDeclaration";
+
+/**
+ * The two wire pieces a {@link FunctionDeclaration} splits into. The contract keeps
+ * the signature (`functionInfo`) and the return-value expressions (`outputAssignments`)
+ * apart; the domain bundles them on `outputs`. The function *body*
+ * (nodes/edges/declaredVariables) is added separately by the workflow serializer —
+ * this only handles the declaration ⇄ wire mapping.
+ */
+export interface SerializedFunction {
+  functionInfo: FunctionInfo;
+  outputAssignments: Record<string, Expression>;
+}
+
+/** Domain declaration → wire pieces: flatten the signature and lift each output's
+ *  expression into the `outputAssignments` map keyed by output uid. */
+export function serialize(fn: FunctionDeclaration): SerializedFunction {
+  const outputAssignments: Record<string, Expression> = {};
+  for (const o of fn.outputs) outputAssignments[o.uid] = o.expression;
+  return { functionInfo: toFunctionInfo(fn), outputAssignments };
+}
+
+/** Wire pieces → domain declaration: bundle each `return` with its assignment. A
+ *  return with no stored assignment gets an empty expression of the right dataType. */
+export function deserialize(functionInfo: FunctionInfo, outputAssignments: Record<string, Expression>): FunctionDeclaration {
+  return {
+    id: functionInfo.id,
+    version: functionInfo.version,
+    name: functionInfo.name,
+    arguments: functionInfo.arguments,
+    outputs: functionInfo.returns.map((r) => ({
+      uid: r.uid,
+      name: r.name,
+      dataType: r.dataType,
+      expression: outputAssignments[r.uid] ?? { expression: "", references: [], dataType: r.dataType },
+    })),
+  };
+}

package/src/globals.d.ts

@@ -1,9 +1,9 @@
-/**
- * This package drops the `DOM` lib (see tsconfig.json) to stay headless, so the
- * Web Crypto `crypto` global is untyped. It exists at runtime everywhere we run
- * — browsers, Node >= 19, Deno, Bun — so we declare only the one member we use
- * rather than pulling in `DOM` or `@types/node` and their global scope.
- */
-declare const crypto: {
-  randomUUID(): `${string}-${string}-${string}-${string}-${string}`;
-};
+/**
+ * This package drops the `DOM` lib (see tsconfig.json) to stay headless, so the
+ * Web Crypto `crypto` global is untyped. It exists at runtime everywhere we run
+ * — browsers, Node >= 19, Deno, Bun — so we declare only the one member we use
+ * rather than pulling in `DOM` or `@types/node` and their global scope.
+ */
+declare const crypto: {
+  randomUUID(): `${string}-${string}-${string}-${string}-${string}`;
+};

package/src/id/index.ts

@@ -1,8 +1,8 @@
-/**
- * Centralized UID creation for every entity in a workflow — nodes, edges,
- * channels, memory, models, declared variables, function arguments, and
- * function canvases. IDs are opaque.
- */
-export function generateId(): string {
-  return crypto.randomUUID();
-}
+/**
+ * Centralized UID creation for every entity in a workflow — nodes, edges,
+ * channels, memory, models, declared variables, function arguments, and
+ * function canvases. IDs are opaque.
+ */
+export function generateId(): string {
+  return crypto.randomUUID();
+}

package/src/index.ts

@@ -1,22 +1,22 @@
-import { deserialize } from "./workflow/serialization";
-import { validateWorkflowState, type ValidationResult } from "./diagnostics/diagnostics";
-import type { ApiWorkflow } from "./workflow/Workflow";
-
-// Api-layer types consumers use directly (no domain twin). Sourced from `api`
-// so they're available at the package root rather than via a domain subpath.
-// (`FunctionInfo` is the exception — it's the flat twin of the domain
-// `FunctionDeclaration`, so it lives on the `function` subpath, not here.)
-export type { DataType, Reference, Expression } from "./api";
-
-// Format versioning: load persisted documents through `migrate` before
-// deserializing.
-export { migrate, CURRENT_SCHEMA_VERSION } from "./migration";
-
-/**
- * Validate a workflow against the headless validator.
- * Pure: no I/O, no Zustand, no React, no DOM. Runnable in Node, a CLI, or
- * a Claude Code skill.
- */
-export function validateWorkflow(workflow: ApiWorkflow): ValidationResult {
-  return validateWorkflowState(deserialize(workflow));
-}
+import { deserialize } from "./workflow/serialization";
+import { validateWorkflowState, type ValidationResult } from "./diagnostics/diagnostics";
+import type { ApiWorkflow } from "./workflow/Workflow";
+
+// Api-layer types consumers use directly (no domain twin). Sourced from `api`
+// so they're available at the package root rather than via a domain subpath.
+// (`FunctionInfo` is the exception — it's the flat twin of the domain
+// `FunctionDeclaration`, so it lives on the `function` subpath, not here.)
+export type { DataType, Reference, Expression } from "./api";
+
+// Format versioning: load persisted documents through `migrate` before
+// deserializing.
+export { migrate, CURRENT_SCHEMA_VERSION } from "./migration";
+
+/**
+ * Validate a workflow against the headless validator.
+ * Pure: no I/O, no Zustand, no React, no DOM. Runnable in Node, a CLI, or
+ * a Claude Code skill.
+ */
+export function validateWorkflow(workflow: ApiWorkflow): ValidationResult {
+  return validateWorkflowState(deserialize(workflow));
+}

package/src/memory/Memory.ts

@@ -1,15 +1,15 @@
-import type { Schemas } from "../api";
-
-export type MemoryType = "MemoryFile" | "VectorDatabase";
-
-export const ALL_MEMORY_TYPES: MemoryType[] = ["MemoryFile", "VectorDatabase"];
-
-export interface Memory {
-  id: string;
-  label: string;
-  type: MemoryType;
-  arguments: Record<string, unknown>;
-}
-
-/** Reference from an agent node to a declared MemoryFile, with access mode. Round-trips 1:1 with the API. */
-export type MemoryRef = Schemas["MemoryRef"];
+import type { Schemas } from "../api";
+
+export type MemoryType = "MemoryFile" | "VectorDatabase";
+
+export const ALL_MEMORY_TYPES: MemoryType[] = ["MemoryFile", "VectorDatabase"];
+
+export interface Memory {
+  id: string;
+  label: string;
+  type: MemoryType;
+  arguments: Record<string, unknown>;
+}
+
+/** Reference from an agent node to a declared MemoryFile, with access mode. Round-trips 1:1 with the API. */
+export type MemoryRef = Schemas["MemoryRef"];

package/src/memory/MemoryDefinition.ts

@@ -1,16 +1,16 @@
-import type { Parameter } from "../parameter";
-import type { MemoryType } from "./Memory";
-
-/**
- * Static, per-type metadata for a memory variant. Mirrors NodeDefinition:
- * one definition object per MemoryType, registered in MemoryRegistry — unlike
- * channels, which use a single union definition gated by activation rules.
- * `label` is a top-level instance field (edited like a channel label), so it is
- * never a parameter here.
- */
-export interface MemoryDefinition {
-  type: MemoryType;
-  label: string;
-  description: string;
-  parameters: Parameter[];
-}
+import type { Parameter } from "../parameter";
+import type { MemoryType } from "./Memory";
+
+/**
+ * Static, per-type metadata for a memory variant. Mirrors NodeDefinition:
+ * one definition object per MemoryType, registered in MemoryRegistry — unlike
+ * channels, which use a single union definition gated by activation rules.
+ * `label` is a top-level instance field (edited like a channel label), so it is
+ * never a parameter here.
+ */
+export interface MemoryDefinition {
+  type: MemoryType;
+  label: string;
+  description: string;
+  parameters: Parameter[];
+}

package/src/memory/MemoryFileDefinition.ts

@@ -1,37 +1,37 @@
-import type { MemoryDefinition } from "./MemoryDefinition";
-
-/**
- * Agent-scoped durable text storage. The instance `label` (edited like a channel
- * label) is the identifier the LLM sees in tool calls, so it is not a parameter.
- * The config panel renders these parameters via ParameterEditor, same as channels.
- */
-export const MemoryFileDefinition: MemoryDefinition = {
-  type: "MemoryFile",
-  label: "Memory File",
-  description: "Durable text storage an agent can read and write",
-  parameters: [
-    {
-      id: "description",
-      label: "Description",
-      description: "What this memory file is for (shown to the LLM as tool description)",
-      type: "string",
-      multiline: true,
-      optional: true,
-    },
-    {
-      id: "content",
-      label: "Initial Content",
-      description: "Seed content written on fresh deploy; existing rows keep their content on redeploy",
-      type: "string",
-      multiline: true,
-      optional: true,
-    },
-    {
-      id: "maxSizeBytes",
-      label: "Max Size (bytes)",
-      description: "Byte cap on writes; leave empty for unlimited",
-      type: "int",
-      optional: true,
-    },
-  ],
-};
+import type { MemoryDefinition } from "./MemoryDefinition";
+
+/**
+ * Agent-scoped durable text storage. The instance `label` (edited like a channel
+ * label) is the identifier the LLM sees in tool calls, so it is not a parameter.
+ * The config panel renders these parameters via ParameterEditor, same as channels.
+ */
+export const MemoryFileDefinition: MemoryDefinition = {
+  type: "MemoryFile",
+  label: "Memory File",
+  description: "Durable text storage an agent can read and write",
+  parameters: [
+    {
+      id: "description",
+      label: "Description",
+      description: "What this memory file is for (shown to the LLM as tool description)",
+      type: "string",
+      multiline: true,
+      optional: true,
+    },
+    {
+      id: "content",
+      label: "Initial Content",
+      description: "Seed content written on fresh deploy; existing rows keep their content on redeploy",
+      type: "string",
+      multiline: true,
+      optional: true,
+    },
+    {
+      id: "maxSizeBytes",
+      label: "Max Size (bytes)",
+      description: "Byte cap on writes; leave empty for unlimited",
+      type: "int",
+      optional: true,
+    },
+  ],
+};

package/src/memory/MemoryRegistry.ts

@@ -1,35 +1,35 @@
-import type { MemoryType } from "./Memory";
-import type { MemoryDefinition } from "./MemoryDefinition";
-import { MemoryFileDefinition } from "./MemoryFileDefinition";
-import { VectorDatabaseDefinition } from "./VectorDatabaseDefinition";
-
-/**
- * Central registry for memory variant definitions (one per MemoryType).
- * Mirrors NodeRegistry.
- */
-class MemoryDefinitionRegistry {
-  private memories: Map<MemoryType, MemoryDefinition> = new Map();
-  private initialized = false;
-
-  initialize() {
-    if (this.initialized) return;
-    this.register(MemoryFileDefinition);
-    this.register(VectorDatabaseDefinition);
-    this.initialized = true;
-  }
-
-  private register(definition: MemoryDefinition) {
-    this.memories.set(definition.type, definition);
-  }
-
-  getAll(): MemoryDefinition[] {
-    return Array.from(this.memories.values());
-  }
-
-  getByType(type: MemoryType): MemoryDefinition | undefined {
-    return this.memories.get(type);
-  }
-}
-
-export const MemoryRegistry = new MemoryDefinitionRegistry();
-MemoryRegistry.initialize();
+import type { MemoryType } from "./Memory";
+import type { MemoryDefinition } from "./MemoryDefinition";
+import { MemoryFileDefinition } from "./MemoryFileDefinition";
+import { VectorDatabaseDefinition } from "./VectorDatabaseDefinition";
+
+/**
+ * Central registry for memory variant definitions (one per MemoryType).
+ * Mirrors NodeRegistry.
+ */
+class MemoryDefinitionRegistry {
+  private memories: Map<MemoryType, MemoryDefinition> = new Map();
+  private initialized = false;
+
+  initialize() {
+    if (this.initialized) return;
+    this.register(MemoryFileDefinition);
+    this.register(VectorDatabaseDefinition);
+    this.initialized = true;
+  }
+
+  private register(definition: MemoryDefinition) {
+    this.memories.set(definition.type, definition);
+  }
+
+  getAll(): MemoryDefinition[] {
+    return Array.from(this.memories.values());
+  }
+
+  getByType(type: MemoryType): MemoryDefinition | undefined {
+    return this.memories.get(type);
+  }
+}
+
+export const MemoryRegistry = new MemoryDefinitionRegistry();
+MemoryRegistry.initialize();

package/src/memory/VectorDatabaseDefinition.ts

@@ -1,21 +1,21 @@
-import type { MemoryDefinition } from "./MemoryDefinition";
-
-/**
- * RAG knowledge base referenced from Retriever nodes. Only descriptive config
- * lives here; the backend collection it binds to is supplied at deploy time.
- */
-export const VectorDatabaseDefinition: MemoryDefinition = {
-  type: "VectorDatabase",
-  label: "Vector Database",
-  description: "RAG knowledge base that Retriever nodes can query",
-  parameters: [
-    {
-      id: "description",
-      label: "Description",
-      description: "What this knowledge base contains",
-      type: "string",
-      multiline: true,
-      optional: true,
-    },
-  ],
-};
+import type { MemoryDefinition } from "./MemoryDefinition";
+
+/**
+ * RAG knowledge base referenced from Retriever nodes. Only descriptive config
+ * lives here; the backend collection it binds to is supplied at deploy time.
+ */
+export const VectorDatabaseDefinition: MemoryDefinition = {
+  type: "VectorDatabase",
+  label: "Vector Database",
+  description: "RAG knowledge base that Retriever nodes can query",
+  parameters: [
+    {
+      id: "description",
+      label: "Description",
+      description: "What this knowledge base contains",
+      type: "string",
+      multiline: true,
+      optional: true,
+    },
+  ],
+};

package/src/memory/index.ts

@@ -1,8 +1,8 @@
-export type { MemoryType, Memory, MemoryRef } from "./Memory";
-export { ALL_MEMORY_TYPES } from "./Memory";
-export type { MemoryDefinition } from "./MemoryDefinition";
-export { MemoryFileDefinition } from "./MemoryFileDefinition";
-export { VectorDatabaseDefinition } from "./VectorDatabaseDefinition";
-export { MemoryRegistry } from "./MemoryRegistry";
-export { serialize, deserialize } from "./serialization";
-export type { ApiMemory } from "./serialization";
+export type { MemoryType, Memory, MemoryRef } from "./Memory";
+export { ALL_MEMORY_TYPES } from "./Memory";
+export type { MemoryDefinition } from "./MemoryDefinition";
+export { MemoryFileDefinition } from "./MemoryFileDefinition";
+export { VectorDatabaseDefinition } from "./VectorDatabaseDefinition";
+export { MemoryRegistry } from "./MemoryRegistry";
+export { serialize, deserialize } from "./serialization";
+export type { ApiMemory } from "./serialization";