@elizaos/plugin-workflow 2.0.0-beta.1

package/src/utils/host-capabilities.ts

@@ -0,0 +1,81 @@
+/**
+ * Host capability detection for the embedded workflow engine.
+ *
+ * Different host environments have different ceilings: Cloudflare Workers
+ * have no fs/childProcess/long-running process; iOS/Android (Capacitor) have
+ * no fs/childProcess and no public inbound HTTP without a tunnel; browsers
+ * have neither fs nor inbound. The engine uses these to refuse activation
+ * of workflows whose nodes need capabilities the host can't provide, with
+ * an actionable message suggesting the right remediation (paired Eliza
+ * Cloud, plugin-tunnel, or running on a server agent).
+ */
+
+export interface HostCapabilities {
+  /** Read/write filesystem via node:fs (or equivalent). */
+  fs: boolean;
+  /** Can receive inbound HTTP from the public internet (host a webhook). */
+  inbound: boolean;
+  /** Host process stays alive across schedule firings (vs short-lived). */
+  longRunning: boolean;
+  /** Spawns child processes via node:child_process. */
+  childProcess: boolean;
+  /** Raw TCP/UDP sockets via node:net (vs only fetch). */
+  net: boolean;
+  /** Human-readable host label for error messages. */
+  label: string;
+}
+
+declare const navigator: { userAgent?: string } | undefined;
+
+export function detectHostCapabilities(): HostCapabilities {
+  // Cloudflare Workers — runtime exposes navigator.userAgent === 'Cloudflare-Workers'.
+  if (
+    typeof navigator !== 'undefined' &&
+    typeof navigator?.userAgent === 'string' &&
+    navigator.userAgent.includes('Cloudflare-Workers')
+  ) {
+    return {
+      fs: false,
+      inbound: true, // Workers handle HTTP — webhook nodes can run if scheduling is the worker cron
+      longRunning: false,
+      childProcess: false,
+      net: false,
+      label: 'Cloudflare Worker',
+    };
+  }
+
+  // Capacitor (iOS / Android). Capacitor exposes a global on the window/globalThis.
+  const capacitor: unknown = Reflect.get(globalThis, 'Capacitor');
+  if (capacitor && typeof capacitor === 'object') {
+    return {
+      fs: false,
+      inbound: false, // No public HTTP without plugin-tunnel
+      longRunning: true, // App stays alive while running; bg runner handles wake-ups
+      childProcess: false,
+      net: false,
+      label: 'Mobile (Capacitor)',
+    };
+  }
+
+  // Browser without Capacitor — pure web.
+  if (typeof window !== 'undefined' && typeof process === 'undefined') {
+    return {
+      fs: false,
+      inbound: false,
+      longRunning: true,
+      childProcess: false,
+      net: false,
+      label: 'Browser',
+    };
+  }
+
+  // Node — server / desktop. Full power.
+  return {
+    fs: true,
+    inbound: true,
+    longRunning: true,
+    childProcess: true,
+    net: true,
+    label: 'Node',
+  };
+}

package/src/utils/inferSyntheticOutputSchema.ts

@@ -0,0 +1,163 @@
+/**
+ * Synthetic output-schema inference for nodes whose output keys are
+ * deterministically derivable from their parameters (Summarize, Set, etc.).
+ * For nodes with arbitrary user-defined output (Code, Function), returns
+ * null — callers should skip downstream field validation rather than
+ * false-error.
+ *
+ * Returning null = "unknowable, do not validate". Returning an empty array
+ * also means "unknowable" but signals the caller can warn loudly. We use
+ * null (skip) for Code/Function and a populated array for Summarize/Set.
+ */
+
+import type { WorkflowNode } from '../types/index';
+
+/** workflows Summarize node aggregation → output prefix. Verified against actual
+ *  workflows output during Session 20 dogfood (concatenate→concatenated_<field>,
+ *  count→count_<field>). Update this map when new aggregations show up. */
+const SUMMARIZE_AGG_PREFIX: Record<string, string> = {
+  concatenate: 'concatenated',
+  count: 'count',
+  countUnique: 'uniqueCount',
+  sum: 'sum',
+  average: 'average',
+  min: 'min',
+  max: 'max',
+  first: 'first',
+  last: 'last',
+  append: 'appended',
+};
+
+/** Returns top-level output field names a Summarize node will emit, derived
+ *  from its `fieldsToSummarize.values[]` parameter. */
+function inferSummarizeFields(node: WorkflowNode): string[] | null {
+  const fields = (node.parameters as Record<string, unknown> | undefined)?.fieldsToSummarize as
+    | { values?: Array<{ aggregation?: string; field?: string }> }
+    | undefined;
+  if (!fields?.values || !Array.isArray(fields.values)) {
+    return null;
+  }
+  const out: string[] = [];
+  for (const entry of fields.values) {
+    if (typeof entry?.aggregation !== 'string' || typeof entry?.field !== 'string') {
+      continue;
+    }
+    const prefix = SUMMARIZE_AGG_PREFIX[entry.aggregation];
+    if (!prefix) {
+      continue;
+    }
+    out.push(`${prefix}_${entry.field}`);
+  }
+  return out.length > 0 ? out : null;
+}
+
+/** Returns field names a Set / EditFields node will emit, derived from
+ *  `assignments.assignments[]` (modern Set node) or `values.<type>[]`
+ *  (legacy Set node). */
+function inferSetFields(node: WorkflowNode): string[] | null {
+  const params = node.parameters as Record<string, unknown> | undefined;
+  if (!params) {
+    return null;
+  }
+
+  // Modern Set / EditFields shape: assignments.assignments[i].name
+  const modern = params.assignments as { assignments?: Array<{ name?: string }> } | undefined;
+  if (modern?.assignments && Array.isArray(modern.assignments)) {
+    const names = modern.assignments
+      .map((a) => a?.name)
+      .filter((n): n is string => typeof n === 'string' && n.length > 0);
+    if (names.length > 0) {
+      return names;
+    }
+  }
+
+  // Legacy Set shape: values.{string,number,boolean}[i].name
+  const legacy = params.values as Record<string, Array<{ name?: string }>> | undefined;
+  if (legacy && typeof legacy === 'object') {
+    const names: string[] = [];
+    for (const arr of Object.values(legacy)) {
+      if (!Array.isArray(arr)) {
+        continue;
+      }
+      for (const v of arr) {
+        if (typeof v?.name === 'string' && v.name.length > 0) {
+          names.push(v.name);
+        }
+      }
+    }
+    if (names.length > 0) {
+      return names;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Gmail's `simple: true` mode flattens the response with PascalCase header
+ * fields (`Subject`, `From`, `To`, `Date`, ...) — distinct from the static
+ * schema in `schemaIndex.json` which captures the non-simple shape with
+ * lowercase `subject` etc. Without this override, validateAndRepair sees
+ * the static schema, decides `field: "subject"` is valid, and fails to
+ * catch the LLM's lowercase pick — Summarize then aggregates 10 empty
+ * strings at runtime because Gmail actually emits `Subject` capitalized.
+ *
+ * Verified during Session 20 dogfood: execution result data on a real
+ * Gmail node with `simple: true` had `[id, threadId, snippet, payload,
+ * sizeEstimate, historyId, internalDate, labels, Subject, From, To]`.
+ */
+const GMAIL_SIMPLE_MODE_FIELDS = [
+  'id',
+  'threadId',
+  'snippet',
+  'payload',
+  'sizeEstimate',
+  'historyId',
+  'internalDate',
+  'labels',
+  'Subject',
+  'From',
+  'To',
+  'Date',
+  'Cc',
+  'Bcc',
+  'Reply-To',
+];
+
+function inferGmailSimpleFields(node: WorkflowNode): string[] | null {
+  const params = node.parameters as Record<string, unknown> | undefined;
+  // simple=true is the default in workflows's Gmail node. Treat both `true` and
+  // `undefined` as simple-mode unless explicitly disabled.
+  if (params?.simple === false) {
+    return null;
+  }
+  return GMAIL_SIMPLE_MODE_FIELDS;
+}
+
+/**
+ * Returns top-level output field names this node will emit, when derivable
+ * from parameters alone. Returns `null` when the schema is unknowable
+ * (Code, Function, AI Agent, custom) — callers should treat null as
+ * "skip field validation against this node's output", NOT as "no fields".
+ */
+export function inferSyntheticOutputSchema(node: WorkflowNode): string[] | null {
+  switch (node.type) {
+    case 'workflows-nodes-base.summarize':
+      return inferSummarizeFields(node);
+    case 'workflows-nodes-base.set':
+    case 'workflows-nodes-base.editFields':
+      return inferSetFields(node);
+    case 'workflows-nodes-base.gmail':
+      // simple-mode override — only applies when simple !== false.
+      // For simple=false, return null so the caller falls back to the
+      // static schema (which captures the non-simple lowercase shape).
+      return inferGmailSimpleFields(node);
+    // Arbitrary user output — schema unknowable without execution.
+    case 'workflows-nodes-base.code':
+    case 'workflows-nodes-base.function':
+    case 'workflows-nodes-base.functionItem':
+      return null;
+    default:
+      return null;
+  }
+}

package/src/utils/outputSchema.ts

@@ -0,0 +1,372 @@
+/**
+ * Output schema utilities for validating expressions between nodes.
+ * Uses pre-crawled schemaIndex.json with full schema content.
+ */
+
+import schemaIndex from '../data/schemaIndex.json';
+import triggerSchemaIndex from '../data/triggerSchemaIndex.json';
+import type { ExpressionRef, SchemaContent } from '../types/index';
+
+type SchemasByResource = Record<string, Record<string, SchemaContent>>;
+
+interface SchemaEntry {
+  folder: string;
+  schemas: SchemasByResource;
+}
+
+interface SchemaIndex {
+  nodeTypes: Record<string, SchemaEntry>;
+  generatedAt: string;
+  version: string;
+}
+
+interface TriggerSchemaIndex {
+  triggers?: Record<string, { outputSchema: SchemaContent }>;
+}
+
+const SCHEMA_INDEX = schemaIndex as Partial<SchemaIndex>;
+const TRIGGER_SCHEMA_INDEX: TriggerSchemaIndex = triggerSchemaIndex;
+const TRIGGER_SCHEMAS = TRIGGER_SCHEMA_INDEX.triggers ?? {};
+
+const NODE_SCHEMAS = SCHEMA_INDEX.nodeTypes ?? {};
+
+export interface OutputSchemaResult {
+  schema: SchemaContent;
+  fields: string[];
+}
+
+export function hasOutputSchema(nodeType: string): boolean {
+  return nodeType in NODE_SCHEMAS;
+}
+
+export function getAvailableResources(nodeType: string): string[] {
+  const entry = NODE_SCHEMAS[nodeType];
+  if (!entry) {
+    return [];
+  }
+  return Object.keys(entry.schemas);
+}
+
+export function getAvailableOperations(nodeType: string, resource: string): string[] {
+  const entry = NODE_SCHEMAS[nodeType];
+  if (!entry) {
+    return [];
+  }
+  const resourceSchemas = entry.schemas[resource];
+  if (!resourceSchemas) {
+    return [];
+  }
+  return Object.keys(resourceSchemas);
+}
+
+export function loadOutputSchema(
+  nodeType: string,
+  resource: string,
+  operation: string
+): OutputSchemaResult | null {
+  const entry = NODE_SCHEMAS[nodeType];
+  if (!entry) {
+    return null;
+  }
+
+  const resourceSchemas = entry.schemas[resource];
+  if (!resourceSchemas) {
+    return null;
+  }
+
+  const schema = resourceSchemas[operation];
+  if (!schema) {
+    return null;
+  }
+
+  return {
+    schema,
+    fields: getTopLevelFields(schema),
+  };
+}
+
+export function loadTriggerOutputSchema(
+  nodeType: string,
+  parameters?: Record<string, unknown>
+): OutputSchemaResult | null {
+  if (parameters?.simple === false) {
+    return null;
+  }
+  const entry = TRIGGER_SCHEMAS[nodeType];
+  if (!entry?.outputSchema?.properties || Object.keys(entry.outputSchema.properties).length === 0) {
+    return null;
+  }
+  return {
+    schema: entry.outputSchema,
+    fields: getTopLevelFields(entry.outputSchema),
+  };
+}
+
+export function getTopLevelFields(schema: SchemaContent): string[] {
+  if (!schema.properties) {
+    return [];
+  }
+  return Object.keys(schema.properties);
+}
+
+/** Returns all field paths including nested (e.g., "from.value[0].address") */
+export function getAllFieldPaths(schema: SchemaContent, prefix = ''): string[] {
+  return getAllFieldPathsTyped(schema, prefix).map((f) => f.path);
+}
+
+/** Returns field paths with their types (e.g., "snippet: string", "payload: object"). */
+export function getAllFieldPathsTyped(
+  schema: SchemaContent,
+  prefix = ''
+): { path: string; type: string }[] {
+  const fields: { path: string; type: string }[] = [];
+  const properties = schema.properties;
+
+  if (!properties) {
+    return fields;
+  }
+
+  for (const [key, value] of Object.entries(properties)) {
+    const currentPath = prefix ? `${prefix}.${key}` : key;
+
+    if (typeof value === 'object' && value !== null) {
+      const propSchema = value as SchemaContent;
+      fields.push({ path: currentPath, type: propSchema.type || 'unknown' });
+
+      if (propSchema.type === 'object' && propSchema.properties) {
+        fields.push(...getAllFieldPathsTyped(propSchema, currentPath));
+      }
+
+      if (propSchema.type === 'array' && propSchema.items) {
+        const items = propSchema.items as SchemaContent;
+        if (items.type === 'object' && items.properties) {
+          fields.push(...getAllFieldPathsTyped(items, `${currentPath}[0]`));
+        }
+      }
+    }
+  }
+
+  return fields;
+}
+
+export function parseExpressions(
+  parameters: Record<string, unknown>,
+  parentPath = ''
+): ExpressionRef[] {
+  const refs: ExpressionRef[] = [];
+
+  for (const [key, value] of Object.entries(parameters)) {
+    const currentPath = parentPath ? `${parentPath}.${key}` : key;
+
+    if (typeof value === 'string') {
+      refs.push(...extractExpressionsFromString(value, currentPath));
+    } else if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) {
+        if (typeof value[i] === 'string') {
+          refs.push(...extractExpressionsFromString(value[i], `${currentPath}[${i}]`));
+        } else if (typeof value[i] === 'object' && value[i] !== null) {
+          refs.push(
+            ...parseExpressions(value[i] as Record<string, unknown>, `${currentPath}[${i}]`)
+          );
+        }
+      }
+    } else if (typeof value === 'object' && value !== null) {
+      refs.push(...parseExpressions(value as Record<string, unknown>, currentPath));
+    }
+  }
+
+  return refs;
+}
+
+function extractExpressionsFromString(str: string, paramPath: string): ExpressionRef[] {
+  const refs: ExpressionRef[] = [];
+
+  // Match every $json.field reference, even inside compound expressions like {{ $json.a || $json.b }}
+  const simplePattern = /\$json\.([a-zA-Z0-9_.[\]'"-]{1,200})/g;
+  // Bracket-notation variant: $json["someField"] or $json['someField'] (Session 21
+  // follow-up). The LLM occasionally emits this when the field name has chars
+  // that wouldn't survive dot notation, OR when it's just "trying to be safe".
+  // Without this pattern, validateAndRepair walks past references like
+  // {{ $json["concatenate_subject"] }} silently — the typo never gets caught.
+  const bracketPattern = /\$json\[\s*(['"])([^'"]{1,200})\1\s*\]/g;
+  const namedNodePattern =
+    /\$\(['"]([^'"]{1,100})['"]\)\.item\.json\.([a-zA-Z0-9_.[\]'"-]{1,200})/g;
+
+  let match: RegExpExecArray | null = simplePattern.exec(str);
+  while (match !== null) {
+    const field = match[1];
+    refs.push({
+      fullExpression: match[0],
+      field,
+      path: parseFieldPath(field),
+      paramPath,
+    });
+    match = simplePattern.exec(str);
+  }
+
+  match = bracketPattern.exec(str);
+  while (match !== null) {
+    const field = match[2];
+    refs.push({
+      fullExpression: match[0],
+      field,
+      path: parseFieldPath(field),
+      paramPath,
+    });
+    match = bracketPattern.exec(str);
+  }
+
+  match = namedNodePattern.exec(str);
+  while (match !== null) {
+    const field = match[2];
+    refs.push({
+      fullExpression: match[0],
+      field,
+      path: parseFieldPath(field),
+      paramPath,
+      sourceNodeName: match[1],
+    });
+    match = namedNodePattern.exec(str);
+  }
+
+  return refs;
+}
+
+/**
+ * Parses "from.value[0].address" or "headers['content-type']" into path segments.
+ */
+function parseFieldPath(field: string): string[] {
+  const path: string[] = [];
+  let current = '';
+  let i = 0;
+
+  while (i < field.length) {
+    const char = field[i];
+
+    if (char === '.') {
+      if (current) {
+        path.push(current);
+        current = '';
+      }
+      i++;
+    } else if (char === '[') {
+      if (current) {
+        path.push(current);
+        current = '';
+      }
+      i++;
+      if (i >= field.length) {
+        break;
+      }
+      if (field[i] === "'" || field[i] === '"') {
+        const quote = field[i];
+        i++;
+        while (i < field.length && field[i] !== quote) {
+          current += field[i];
+          i++;
+        }
+        i++;
+      } else {
+        while (i < field.length && field[i] !== ']') {
+          current += field[i];
+          i++;
+        }
+      }
+      if (current) {
+        path.push(current);
+        current = '';
+      }
+      i++;
+    } else {
+      current += char;
+      i++;
+    }
+  }
+
+  if (current) {
+    path.push(current);
+  }
+
+  return path;
+}
+
+export function fieldExistsInSchema(path: string[], schema: SchemaContent): boolean {
+  if (path.length === 0) {
+    return false;
+  }
+
+  let current: SchemaContent | undefined = schema;
+
+  for (let i = 0; i < path.length; i++) {
+    const segment = path[i];
+
+    if (!current || typeof current !== 'object') {
+      return false;
+    }
+
+    const properties = current.properties;
+    if (!properties) {
+      return false;
+    }
+
+    const prop = properties[segment] as SchemaContent | undefined;
+    if (!prop) {
+      return false;
+    }
+
+    if (i === path.length - 1) {
+      return true;
+    }
+
+    if (prop.type === 'object') {
+      current = prop;
+    } else if (prop.type === 'array' && prop.items) {
+      const nextSegment = path[i + 1];
+      if (/^\d+$/.test(nextSegment)) {
+        i++;
+        current = prop.items as SchemaContent;
+      } else {
+        return false;
+      }
+    } else {
+      return false;
+    }
+  }
+
+  return false;
+}
+
+export function formatSchemaForPrompt(schema: SchemaContent, maxDepth = 2): string {
+  const lines: string[] = [];
+
+  function format(obj: SchemaContent, depth: number, prefix: string) {
+    const properties = obj.properties;
+    if (!properties || depth > maxDepth) {
+      return;
+    }
+
+    for (const [key, value] of Object.entries(properties)) {
+      const prop = value as SchemaContent;
+      const type = prop.type as string;
+      const path = prefix ? `${prefix}.${key}` : key;
+
+      if (type === 'object' && prop.properties) {
+        lines.push(`${path}: object`);
+        format(prop, depth + 1, path);
+      } else if (type === 'array' && prop.items) {
+        const items = prop.items as SchemaContent;
+        if (items.type === 'object' && items.properties) {
+          lines.push(`${path}: array of objects`);
+          format(items, depth + 1, `${path}[0]`);
+        } else {
+          lines.push(`${path}: array of ${items.type || 'unknown'}`);
+        }
+      } else {
+        lines.push(`${path}: ${type || 'unknown'}`);
+      }
+    }
+  }
+
+  format(schema, 0, '');
+  return lines.join('\n');
+}