@elizaos/plugin-workflow 2.0.0-beta.1

package/src/utils/catalog.ts

@@ -0,0 +1,260 @@
+import defaultNodesData from '../data/defaultNodes.json';
+import type {
+  IntegrationFilterResult,
+  NodeDefinition,
+  NodeProperty,
+  NodeSearchResult,
+} from '../types/index';
+
+/**
+ * workflows node catalog with keyword-based search
+ * @note Uses embedded catalog (457 nodes as of April 2025)
+ * @todo Add dynamic refresh via GET /node-types in v2
+ */
+
+const NODE_CATALOG = defaultNodesData as NodeDefinition[];
+
+/** Get all nodes in the catalog. Used by route handlers for unfiltered listing. */
+export function getAllNodes(): NodeDefinition[] {
+  return NODE_CATALOG;
+}
+
+/**
+ * Look up a node definition by its type name.
+ *
+ * Handles full names ("workflows-nodes-base.httpRequest") and bare names ("httpRequest").
+ */
+export function getNodeDefinition(typeName: string): NodeDefinition | undefined {
+  const exact = NODE_CATALOG.find((n) => n.name === typeName);
+  if (exact) {
+    return exact;
+  }
+
+  const bare = typeName.replace(/^workflows-nodes-base\./, '');
+  return NODE_CATALOG.find((n) => {
+    const catalogBare = n.name.replace(/^workflows-nodes-base\./, '');
+    return catalogBare === bare || n.name === bare;
+  });
+}
+
+/** Split a name into lowercase tokens on camelCase / dot / hyphen / underscore / @ / slash boundaries */
+function tokenize(name: string): string[] {
+  return name
+    .replace(/([a-z])([A-Z])/g, '$1 $2') // camelCase → words
+    .split(/[\s.\-_@/]+/)
+    .map((t) => t.toLowerCase())
+    .filter(Boolean);
+}
+
+/**
+ * Scoring: exact name 10, word-boundary 7, substring 3, category 3, description 2, word 1
+ */
+export function searchNodes(keywords: string[], limit = 15): NodeSearchResult[] {
+  if (keywords.length === 0) {
+    return [];
+  }
+
+  const normalizedKeywords = keywords.map((kw) => kw.toLowerCase().trim());
+
+  const scoredNodes: NodeSearchResult[] = NODE_CATALOG.filter(
+    (node) => node.name && node.displayName
+  ).map((node) => {
+    let score = 0;
+    const matchReasons: string[] = [];
+
+    const nodeName = node.name.toLowerCase();
+    const nodeDisplayName = node.displayName.toLowerCase();
+    const nodeDescription = node.description?.toLowerCase() || '';
+    const nameTokens = tokenize(node.name);
+    const displayTokens = tokenize(node.displayName);
+
+    for (const keyword of normalizedKeywords) {
+      if (nodeName === keyword || nodeDisplayName === keyword) {
+        score += 10;
+        matchReasons.push(`exact match: "${keyword}"`);
+        continue;
+      }
+
+      // Word-boundary match: keyword equals a token in the name
+      const isWordMatch =
+        nameTokens.some((t) => t === keyword) || displayTokens.some((t) => t === keyword);
+
+      if (isWordMatch) {
+        score += 7;
+        matchReasons.push(`word match: "${keyword}"`);
+      } else if (nodeName.includes(keyword) || nodeDisplayName.includes(keyword)) {
+        score += 3;
+        matchReasons.push(`name contains: "${keyword}"`);
+      }
+
+      if (nodeDescription.includes(keyword)) {
+        score += 2;
+        matchReasons.push(`description contains: "${keyword}"`);
+      }
+
+      const descriptionWords = nodeDescription.split(/\s+/);
+      if (descriptionWords.some((word) => word.includes(keyword))) {
+        score += 1;
+      }
+
+      if (node.group.some((group) => group.toLowerCase().includes(keyword))) {
+        score += 3;
+        matchReasons.push(`category: "${keyword}"`);
+      }
+    }
+
+    return {
+      node,
+      score,
+      matchReason: matchReasons.join(', ') || 'no strong match',
+    };
+  });
+
+  return scoredNodes
+    .filter((result) => result.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit);
+}
+
+export function filterNodesByIntegrationSupport(
+  nodes: NodeSearchResult[],
+  supportedCredTypes: Set<string>
+): IntegrationFilterResult {
+  const remaining: NodeSearchResult[] = [];
+  const removed: NodeSearchResult[] = [];
+
+  for (const result of nodes) {
+    const creds = result.node.credentials;
+
+    // No credentials → utility node → always keep
+    if (!creds || creds.length === 0) {
+      remaining.push(result);
+      continue;
+    }
+
+    // Service node: keep if ANY credential type is supported
+    const hasSupported = creds.some((c) => supportedCredTypes.has(c.name));
+    if (hasSupported) {
+      remaining.push(result);
+    } else {
+      removed.push(result);
+    }
+  }
+
+  return { remaining, removed };
+}
+
+const NOISE_TYPES = new Set(['notice', 'hidden']);
+const STRIP_KEYS = new Set([
+  'routing',
+  'displayOptions',
+  'typeOptions',
+  'hint',
+  'isNodeSetting',
+  'noDataExpression',
+  'validateType',
+  'ignoreValidationDuringExecution',
+  'requiresDataPath',
+  'disabledOptions',
+  'credentialTypes',
+  'modes',
+]);
+
+type NodePropertyOption = NonNullable<NodeProperty['options']>[number];
+
+function isPropertyCollectionOption(
+  option: NodePropertyOption
+): option is Extract<NodePropertyOption, { values: NodeProperty[] }> {
+  return Array.isArray(option.values);
+}
+
+function simplifyProperty(prop: NodeProperty): NodeProperty | null {
+  if (NOISE_TYPES.has(prop.type)) {
+    return null;
+  }
+
+  const slim: NodeProperty = { ...prop };
+  for (const key of STRIP_KEYS) {
+    delete slim[key];
+  }
+
+  if (prop.type === 'resourceLocator') {
+    slim.type = 'string';
+    slim.default = '';
+    slim.description = slim.description || `${prop.displayName} ID`;
+  }
+
+  if (prop.options && Array.isArray(prop.options)) {
+    slim.options = prop.options.map((opt) => {
+      if (isPropertyCollectionOption(opt)) {
+        return {
+          name: opt.name,
+          displayName: opt.displayName,
+          values: opt.values.map(simplifyProperty).filter((v): v is NodeProperty => v !== null),
+        };
+      }
+      const { description: _d, ...rest } = opt;
+      return rest;
+    });
+  }
+
+  return slim;
+}
+
+/**
+ * Derive a `{ credType: requiredAuthValue }` map from a node's catalog
+ * credential entries. So Gmail's catalog produces
+ * `{ gmailOAuth2: "oAuth2", googleApi: "serviceAccount" }`. The LLM uses
+ * this to set `parameters.authentication` correctly when attaching a
+ * credentials block (Session 21 anti-hallucination Layer 2).
+ *
+ * Returns undefined when no credential entries gate on `authentication`.
+ */
+function buildCredentialAuthMatrix(node: NodeDefinition): Record<string, string> | undefined {
+  if (!node.credentials?.length) {
+    return undefined;
+  }
+  const out: Record<string, string> = {};
+  for (const cred of node.credentials) {
+    const authValues = (cred.displayOptions as { show?: { authentication?: string[] } } | undefined)
+      ?.show?.authentication;
+    if (Array.isArray(authValues) && authValues.length === 1) {
+      out[cred.name] = authValues[0];
+    }
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+export function simplifyNodeForLLM(node: NodeDefinition): NodeDefinition {
+  const cleaned = node.properties
+    .map(simplifyProperty)
+    .filter((p): p is NodeProperty => p !== null);
+
+  const seen = new Set<string>();
+  const deduped: NodeProperty[] = [];
+  for (const prop of cleaned) {
+    if (seen.has(prop.name)) {
+      continue;
+    }
+    seen.add(prop.name);
+    deduped.push(prop);
+  }
+
+  // Layer 2 (Session 21): always emit `version` as an array so the LLM
+  // sees the EXACT set of valid values (catches typeVersion hallucinations
+  // like 2.2 when only [1, 2, 2.1] exist). Pair with the prompt rule
+  // "pick the highest from version[]; never invent versions".
+  const versions: number[] = Array.isArray(node.version) ? [...node.version] : [node.version];
+
+  // Layer 2 (Session 21): expose the credential→authentication mapping
+  // so the LLM sets `parameters.authentication` correctly when it
+  // attaches a credentials block.
+  const credentialAuthMatrix = buildCredentialAuthMatrix(node);
+
+  return {
+    ...node,
+    version: versions,
+    properties: deduped,
+    ...(credentialAuthMatrix ? { credentialAuthMatrix } : {}),
+  } as NodeDefinition & { credentialAuthMatrix?: Record<string, string> };
+}

package/src/utils/clarification.ts

@@ -0,0 +1,52 @@
+import type { ClarificationRequest } from '../types';
+
+/**
+ * Marker used by the service to flag clarifications produced by post-LLM
+ * catalog validation (vs. clarifications emitted by the LLM itself). Hosts
+ * may surface these differently if needed.
+ */
+export const CATALOG_CLARIFICATION_SUFFIX =
+  '— please provide this value or clarify your requirements';
+
+export function isCatalogClarificationString(value: string): boolean {
+  return value.endsWith(CATALOG_CLARIFICATION_SUFFIX);
+}
+
+export function isCatalogClarification(item: string | ClarificationRequest): boolean {
+  return typeof item === 'string'
+    ? isCatalogClarificationString(item)
+    : isCatalogClarificationString(item.question);
+}
+
+/**
+ * Normalize a mixed-shape clarifications array into structured
+ * `ClarificationRequest` objects. Legacy strings become `kind: 'free_text'`
+ * with an empty `paramPath` (host renders a free-form input instead of a
+ * picker). Structured items pass through unchanged.
+ */
+export function coerceClarificationRequests(
+  items: ReadonlyArray<string | ClarificationRequest> | undefined | null
+): ClarificationRequest[] {
+  if (!items || items.length === 0) {
+    return [];
+  }
+  const out: ClarificationRequest[] = [];
+  for (const item of items) {
+    if (typeof item === 'string') {
+      const trimmed = item.trim();
+      if (trimmed.length === 0) {
+        continue;
+      }
+      out.push({ kind: 'free_text', question: trimmed, paramPath: '' });
+    } else if (item && typeof item === 'object' && typeof item.question === 'string') {
+      out.push({
+        kind: item.kind ?? 'free_text',
+        platform: item.platform,
+        scope: item.scope,
+        question: item.question,
+        paramPath: typeof item.paramPath === 'string' ? item.paramPath : '',
+      });
+    }
+  }
+  return out;
+}

package/src/utils/context.ts

@@ -0,0 +1,22 @@
+import type { IAgentRuntime, Memory, State, UUID } from '@elizaos/core';
+
+export function buildConversationContext(message: Memory, state: State | undefined): string {
+  const raw = state?.values?.recentMessages;
+  const recentMessages = typeof raw === 'string' ? raw : '';
+  const currentText = message.content?.text ?? '';
+
+  if (!recentMessages) {
+    return currentText;
+  }
+
+  return `${recentMessages}\n\nCurrent request: ${currentText}`;
+}
+
+export async function getUserTagName(runtime: IAgentRuntime, userId: string): Promise<string> {
+  const entity = await runtime.getEntityById(userId as UUID);
+  const shortId = userId.replace(/-/g, '').slice(0, 8);
+  const name = entity?.names?.[0];
+  // ElizaOS default name is "User" + UUID — not useful for a tag
+  const isRealName = name && !name.includes(userId.slice(0, 8));
+  return isRealName ? `${name}_${shortId}` : `user_${shortId}`;
+}

package/src/utils/credentialResolver.ts

@@ -0,0 +1,234 @@
+import { logger } from '@elizaos/core';
+import type {
+  CredentialProvider,
+  CredentialResolutionResult,
+  MissingConnection,
+  WorkflowCredentialStoreApi,
+  WorkflowDefinition,
+  WorkflowPluginConfig,
+} from '../types/index';
+
+interface CredentialApiClient {
+  createCredential(credential: {
+    name: string;
+    type: string;
+    data: Record<string, unknown>;
+  }): Promise<{ id: string }>;
+}
+
+/**
+ * Resolve and inject credentials into workflow.
+ *
+ * Resolution chain (first match wins):
+ *   1. Credential store DB — cached mappings from previous resolutions
+ *   2. Static config — character.settings.workflows.credentials
+ *   3. External provider — registered CredentialProvider service (e.g. cloud OAuth)
+ *   4. Missing — reported for manual configuration in workflows
+ */
+export async function resolveCredentials(
+  workflow: WorkflowDefinition,
+  userId: string,
+  config: WorkflowPluginConfig,
+  credStore: WorkflowCredentialStoreApi | null,
+  credProvider: CredentialProvider | null,
+  apiClient: CredentialApiClient | null,
+  tagName: string
+): Promise<CredentialResolutionResult> {
+  const requiredCredTypes = extractRequiredCredentialTypes(workflow);
+
+  if (requiredCredTypes.size === 0) {
+    return {
+      workflow,
+      missingConnections: [],
+      injectedCredentials: new Map(),
+    };
+  }
+
+  const injectedCredentials = new Map<string, string>();
+  const missingConnections: MissingConnection[] = [];
+
+  for (const credType of requiredCredTypes) {
+    const credId = await resolveOneCredential(
+      credType,
+      userId,
+      config,
+      credStore,
+      credProvider,
+      apiClient,
+      missingConnections,
+      tagName
+    );
+
+    if (credId) {
+      injectedCredentials.set(credType, credId);
+    }
+  }
+
+  const resolvedWorkflow = injectCredentialIds(workflow, injectedCredentials);
+
+  return {
+    workflow: resolvedWorkflow,
+    missingConnections,
+    injectedCredentials,
+  };
+}
+
+async function resolveOneCredential(
+  credType: string,
+  userId: string,
+  config: WorkflowPluginConfig,
+  credStore: WorkflowCredentialStoreApi | null,
+  credProvider: CredentialProvider | null,
+  apiClient: CredentialApiClient | null,
+  missingConnections: MissingConnection[],
+  tagName: string
+): Promise<string | null> {
+  // 1. Credential store DB
+  const cachedId = await credStore?.get(userId, credType);
+  if (cachedId) {
+    logger.debug(
+      { src: 'plugin:workflow:utils:credentials' },
+      `Resolved ${credType} from credential store`
+    );
+    return cachedId;
+  }
+
+  // 2. Static config
+  if (config.credentials) {
+    const configId = findCredentialId(config.credentials, credType);
+    if (configId) {
+      return configId;
+    }
+  }
+
+  // 3. External provider
+  if (credProvider) {
+    try {
+      const result = await credProvider.resolve(userId, credType);
+
+      if (result?.status === 'credential_data') {
+        if (!apiClient) {
+          logger.error(
+            { src: 'plugin:workflow:utils:credentials' },
+            `Received credential_data for ${credType} but no apiClient available`
+          );
+          missingConnections.push({ credType });
+          return null;
+        }
+        const credName = `${credType}_${tagName}`;
+        const workflowsCred = await apiClient.createCredential({
+          name: credName,
+          type: credType,
+          data: result.data,
+        });
+        try {
+          await credStore?.set(userId, credType, workflowsCred.id);
+        } catch (cacheError) {
+          logger.warn(
+            { src: 'plugin:workflow:utils:credentials' },
+            `Failed to cache credential mapping for ${credType} (credential still usable): ${cacheError instanceof Error ? cacheError.message : String(cacheError)}`
+          );
+        }
+        logger.info(
+          { src: 'plugin:workflow:utils:credentials' },
+          `Created workflows credential for ${credType}: ${workflowsCred.id}`
+        );
+        return workflowsCred.id;
+      }
+
+      if (result?.status === 'needs_auth') {
+        missingConnections.push({ credType, authUrl: result.authUrl });
+        return null;
+      }
+    } catch (error) {
+      logger.error(
+        { src: 'plugin:workflow:utils:credentials' },
+        `Credential provider failed for ${credType}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  // 4. Missing
+  missingConnections.push({ credType });
+  return null;
+}
+
+/**
+ * Look up a credential ID from config, tolerating naming mismatches
+ * (e.g. LLM generates "gmailOAuth2Api" but config has "gmailOAuth2", or vice-versa).
+ */
+function findCredentialId(credentials: Record<string, string>, credType: string): string | null {
+  if (credentials[credType]) {
+    return credentials[credType];
+  }
+
+  // Fuzzy: try without "Api" suffix (e.g. "gmailOAuth2Api" → "gmailOAuth2")
+  const withoutApi = credType.replace(/Api$/, '');
+  if (withoutApi !== credType && credentials[withoutApi]) {
+    logger.debug(
+      { src: 'plugin:workflow:utils:credentials' },
+      `Fuzzy credential match: "${credType}" → "${withoutApi}" (removed Api suffix)`
+    );
+    return credentials[withoutApi];
+  }
+
+  // Fuzzy: try with "Api" suffix (e.g. "gmailOAuth2" → "gmailOAuth2Api")
+  const withApi = `${credType}Api`;
+  if (credentials[withApi]) {
+    logger.debug(
+      { src: 'plugin:workflow:utils:credentials' },
+      `Fuzzy credential match: "${credType}" → "${withApi}" (added Api suffix)`
+    );
+    return credentials[withApi];
+  }
+
+  return null;
+}
+
+function extractRequiredCredentialTypes(workflow: WorkflowDefinition): Set<string> {
+  const credTypes = new Set<string>();
+
+  for (const node of workflow.nodes) {
+    if (node.credentials) {
+      for (const credType of Object.keys(node.credentials)) {
+        credTypes.add(credType);
+      }
+    }
+  }
+
+  return credTypes;
+}
+
+function injectCredentialIds(
+  workflow: WorkflowDefinition,
+  credentialMap: Map<string, string>
+): WorkflowDefinition {
+  const injected = { ...workflow };
+  injected.nodes = workflow.nodes.map((node) => {
+    if (!node.credentials) {
+      return node;
+    }
+
+    const updatedCredentials: typeof node.credentials = {};
+
+    for (const [credType, credRef] of Object.entries(node.credentials)) {
+      const credId = credentialMap.get(credType);
+
+      if (credId) {
+        updatedCredentials[credType] = {
+          id: credId,
+          name: credRef.name,
+        };
+      } else {
+        updatedCredentials[credType] = credRef;
+      }
+    }
+
+    return {
+      ...node,
+      credentials: updatedCredentials,
+    };
+  });
+
+  return injected;
+}