@elizaos/plugin-workflow 2.0.0-beta.1 → 2.0.3-beta.5

package/src/utils/execution-diagnostics.ts

@@ -0,0 +1,192 @@
+import type { WorkflowExecution } from '../types/index';
+
+export type WorkflowExecutionTone = 'success' | 'danger' | 'warning' | 'muted';
+
+export interface WorkflowExecutionRunRow {
+  nodeName: string;
+  status: 'success' | 'error' | 'unknown';
+  startTime?: number;
+  executionTimeMs?: number;
+  itemCount: number;
+  preview: string;
+  error?: string;
+}
+
+export interface WorkflowExecutionSummary {
+  statusLabel: string;
+  tone: WorkflowExecutionTone;
+  durationLabel: string;
+  nodeCount: number;
+  lastNode?: string;
+  error?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function readNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value : undefined;
+}
+
+function countMainItems(data: unknown): number {
+  if (!isRecord(data) || !Array.isArray(data.main)) return 0;
+  return data.main.reduce((total, output) => {
+    if (!Array.isArray(output)) return total;
+    return total + output.length;
+  }, 0);
+}
+
+function previewMainData(data: unknown): string {
+  if (!isRecord(data) || !Array.isArray(data.main)) return 'No output';
+  for (const output of data.main) {
+    if (!Array.isArray(output)) continue;
+    const first = output.find(isRecord);
+    if (!first) continue;
+    const json = isRecord(first.json) ? first.json : first;
+    try {
+      const preview = JSON.stringify(json);
+      return preview.length > 160 ? `${preview.slice(0, 157)}...` : preview;
+    } catch {
+      return 'Output could not be previewed';
+    }
+  }
+  return 'No output';
+}
+
+function getRunError(run: unknown): string | undefined {
+  if (!isRecord(run)) return undefined;
+  const error = run.error;
+  if (isRecord(error)) {
+    return readString(error.message) ?? readString(error.description);
+  }
+  return readString(error);
+}
+
+export function getWorkflowExecutionRunRows(
+  execution: WorkflowExecution
+): WorkflowExecutionRunRow[] {
+  const runData = execution.data?.resultData?.runData;
+  if (!runData) return [];
+
+  return Object.entries(runData).flatMap(([nodeName, runs]) => {
+    if (!Array.isArray(runs)) return [];
+    return runs.map((run): WorkflowExecutionRunRow => {
+      const record = isRecord(run) ? run : {};
+      const error = getRunError(record);
+      const data = record.data;
+      return {
+        nodeName,
+        status: error ? 'error' : execution.status === 'success' ? 'success' : 'unknown',
+        startTime: readNumber(record.startTime),
+        executionTimeMs: readNumber(record.executionTime),
+        itemCount: countMainItems(data),
+        preview: previewMainData(data),
+        error,
+      };
+    });
+  });
+}
+
+export function getWorkflowExecutionError(execution: WorkflowExecution): string | undefined {
+  const error = execution.data?.resultData?.error;
+  if (error?.message) return error.message;
+  for (const row of getWorkflowExecutionRunRows(execution)) {
+    if (row.error) return row.error;
+  }
+  return undefined;
+}
+
+export function formatWorkflowExecutionDuration(
+  startedAt?: string,
+  stoppedAt?: string | null
+): string {
+  if (!startedAt) return 'Unknown';
+  const startMs = Date.parse(startedAt);
+  const stopMs = stoppedAt ? Date.parse(stoppedAt) : Date.now();
+  if (!Number.isFinite(startMs) || !Number.isFinite(stopMs)) return 'Unknown';
+  const durationMs = Math.max(0, stopMs - startMs);
+  if (durationMs < 1000) return `${durationMs} ms`;
+  if (durationMs < 60_000) return `${(durationMs / 1000).toFixed(1)} s`;
+  return `${Math.round(durationMs / 60_000)} min`;
+}
+
+export function summarizeWorkflowExecution(execution: WorkflowExecution): WorkflowExecutionSummary {
+  const rows = getWorkflowExecutionRunRows(execution);
+  const status = execution.status;
+  const tone: WorkflowExecutionTone =
+    status === 'success'
+      ? 'success'
+      : status === 'error' || status === 'crashed' || status === 'canceled'
+        ? 'danger'
+        : status === 'running' || status === 'waiting'
+          ? 'warning'
+          : 'muted';
+  const statusLabel =
+    status === 'success'
+      ? 'Succeeded'
+      : status === 'error'
+        ? 'Failed'
+        : status === 'running'
+          ? 'Running'
+          : status === 'waiting'
+            ? 'Waiting'
+            : status.charAt(0).toUpperCase() + status.slice(1);
+
+  return {
+    statusLabel,
+    tone,
+    durationLabel: formatWorkflowExecutionDuration(execution.startedAt, execution.stoppedAt),
+    nodeCount: rows.length,
+    lastNode: execution.data?.resultData?.lastNodeExecuted,
+    error: getWorkflowExecutionError(execution),
+  };
+}
+
+export function formatWorkflowEngineMetrics(execution: WorkflowExecution): string | null {
+  const engine = execution.data?.resultData?.engine;
+  if (!engine) return null;
+  const skipped = engine.skipped > 0 ? ` / ${engine.skipped} skipped` : '';
+  const retries = engine.retries > 0 ? ` / ${engine.retries} retries` : '';
+  return `${engine.nodes} nodes / ${engine.levels} levels / ${engine.maxConcurrency} max parallel${skipped}${retries}`;
+}
+
+export function buildWorkflowExecutionDiagnostics(execution: WorkflowExecution): string {
+  const summary = summarizeWorkflowExecution(execution);
+  const rows = getWorkflowExecutionRunRows(execution);
+  const engineMetrics = formatWorkflowEngineMetrics(execution);
+  const lines = [
+    `Workflow execution ${execution.id}`,
+    `Status: ${summary.statusLabel}`,
+    `Workflow: ${execution.workflowId}`,
+    `Mode: ${execution.mode}`,
+    `Started: ${execution.startedAt}`,
+    `Stopped: ${execution.stoppedAt ?? 'still running'}`,
+    `Duration: ${summary.durationLabel}`,
+    summary.lastNode ? `Last node: ${summary.lastNode}` : null,
+    engineMetrics ? `Engine: ${engineMetrics}` : null,
+    summary.error ? `Error: ${summary.error}` : null,
+  ].filter((line): line is string => Boolean(line));
+
+  if (rows.length === 0) {
+    lines.push('Nodes: none recorded');
+    return lines.join('\n');
+  }
+
+  lines.push('Nodes:');
+  for (const row of rows) {
+    const elapsed =
+      typeof row.executionTimeMs === 'number' ? `${row.executionTimeMs} ms` : 'unknown';
+    const result = row.error ? `error=${row.error}` : `preview=${row.preview}`;
+    lines.push(
+      `- ${row.nodeName}: ${row.status}; ${row.itemCount} item${
+        row.itemCount === 1 ? '' : 's'
+      }; ${elapsed}; ${result}`
+    );
+  }
+  return lines.join('\n');
+}

package/src/utils/generation.ts

@@ -48,16 +48,179 @@ type StructuredModelRunner = {
   ): Promise<T>;
 };
 
+type WorkflowTextModelType = typeof ModelType.TEXT_SMALL | typeof ModelType.TEXT_LARGE;
+type WorkflowGenerateTextParams = GenerateTextParams & { model?: string };
+
+interface WorkflowModelRouting {
+  model?: string;
+  requestedProvider?: string;
+  runtimeProvider?: string;
+}
+
+const WORKFLOW_MODEL_PROVIDER_KEYS = [
+  'WORKFLOW_LLM_PROVIDER',
+  'WORKFLOW_MODEL_PROVIDER',
+  'WORKFLOW_TEST_PROVIDER',
+] as const;
+
+const WORKFLOW_MODEL_KEYS = [
+  'WORKFLOW_LLM_MODEL',
+  'WORKFLOW_MODEL',
+  'WORKFLOW_TEST_MODEL',
+] as const;
+
+const WORKFLOW_RUNTIME_PROVIDER_KEYS = [
+  'WORKFLOW_LLM_RUNTIME_PROVIDER',
+  'WORKFLOW_MODEL_RUNTIME_PROVIDER',
+] as const;
+
+function readStringSetting(runtime: IAgentRuntime, key: string): string | undefined {
+  const runtimeValue = runtime.getSetting(key);
+  if (typeof runtimeValue === 'string' && runtimeValue.trim().length > 0) {
+    return runtimeValue.trim();
+  }
+  if (typeof process !== 'undefined') {
+    const envValue = process.env[key];
+    if (typeof envValue === 'string' && envValue.trim().length > 0) {
+      return envValue.trim();
+    }
+  }
+  return undefined;
+}
+
+function readFirstStringSetting(
+  runtime: IAgentRuntime,
+  keys: readonly string[]
+): string | undefined {
+  for (const key of keys) {
+    const value = readStringSetting(runtime, key);
+    if (value) {
+      return value;
+    }
+  }
+  return undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isCerebrasHost(value: string): boolean {
+  const host = value.toLowerCase();
+  return host === 'cerebras.ai' || host.endsWith('.cerebras.ai');
+}
+
+function isCerebrasBaseUrl(value: string): boolean {
+  try {
+    return isCerebrasHost(new URL(value).hostname);
+  } catch {
+    const host = value.replace(/^[a-z][a-z0-9+.-]*:\/\//i, '').split(/[/?#:]/, 1)[0];
+    return isCerebrasHost(host);
+  }
+}
+
+function inferCerebrasMode(runtime: IAgentRuntime): boolean {
+  const explicitProvider = readStringSetting(runtime, 'ELIZA_PROVIDER');
+  if (explicitProvider?.toLowerCase() === 'cerebras') {
+    return true;
+  }
+  const openAiBaseUrl = readStringSetting(runtime, 'OPENAI_BASE_URL');
+  if (openAiBaseUrl && isCerebrasBaseUrl(openAiBaseUrl)) {
+    return true;
+  }
+  const cerebrasKey = readStringSetting(runtime, 'CEREBRAS_API_KEY');
+  return !!cerebrasKey && !readStringSetting(runtime, 'OPENAI_API_KEY') && !openAiBaseUrl;
+}
+
+function resolveWorkflowModelRouting(runtime: IAgentRuntime): WorkflowModelRouting | null {
+  const explicitProvider = readFirstStringSetting(runtime, WORKFLOW_MODEL_PROVIDER_KEYS);
+  const requestedProvider =
+    explicitProvider ?? (inferCerebrasMode(runtime) ? 'cerebras' : undefined);
+  const normalizedProvider = requestedProvider?.toLowerCase();
+  const model =
+    readFirstStringSetting(runtime, WORKFLOW_MODEL_KEYS) ??
+    (normalizedProvider === 'cerebras'
+      ? (readStringSetting(runtime, 'CEREBRAS_MODEL') ?? 'gpt-oss-120b')
+      : undefined);
+  const explicitRuntimeProvider = readFirstStringSetting(runtime, WORKFLOW_RUNTIME_PROVIDER_KEYS);
+  const runtimeProvider =
+    explicitRuntimeProvider ?? (normalizedProvider === 'cerebras' ? 'openai' : requestedProvider);
+
+  if (!model && !requestedProvider && !runtimeProvider) {
+    return null;
+  }
+
+  return {
+    ...(model ? { model } : {}),
+    ...(requestedProvider ? { requestedProvider } : {}),
+    ...(runtimeProvider ? { runtimeProvider } : {}),
+  };
+}
+
+function withWorkflowModelRouting(
+  runtime: IAgentRuntime,
+  params: GenerateTextParams,
+  callSite: string
+): { params: WorkflowGenerateTextParams; provider?: string } {
+  const routing = resolveWorkflowModelRouting(runtime);
+  if (!routing) {
+    return { params };
+  }
+
+  const existingProviderOptions = isRecord(params.providerOptions) ? params.providerOptions : {};
+  const existingWorkflowOptions = isRecord(existingProviderOptions.workflow)
+    ? existingProviderOptions.workflow
+    : {};
+
+  return {
+    provider: routing.runtimeProvider,
+    params: {
+      ...params,
+      ...(routing.model ? { model: routing.model } : {}),
+      providerOptions: {
+        ...existingProviderOptions,
+        workflow: {
+          ...existingWorkflowOptions,
+          callSite,
+          ...(routing.model ? { model: routing.model } : {}),
+          ...(routing.requestedProvider ? { requestedProvider: routing.requestedProvider } : {}),
+          ...(routing.runtimeProvider ? { runtimeProvider: routing.runtimeProvider } : {}),
+        },
+      },
+    },
+  };
+}
+
 async function useStructuredModel<T>(
   runtime: IAgentRuntime,
   prompt: string,
-  schema: unknown
+  schema: unknown,
+  callSite: string
 ): Promise<T> {
   const structuredRuntime = runtime as IAgentRuntime & StructuredModelRunner;
-  return (await structuredRuntime.useModel<T>(ModelType.TEXT_SMALL, {
-    prompt,
-    responseSchema: schema as never,
-  })) as T;
+  const routed = withWorkflowModelRouting(
+    runtime,
+    {
+      prompt,
+      responseSchema: schema as never,
+    },
+    callSite
+  );
+  return (await structuredRuntime.useModel<T>(
+    ModelType.TEXT_SMALL,
+    routed.params as GenerateTextParams & { responseSchema: unknown },
+    routed.provider
+  )) as T;
+}
+
+async function useWorkflowTextModel(
+  runtime: IAgentRuntime,
+  modelType: WorkflowTextModelType,
+  params: GenerateTextParams,
+  callSite: string
+): Promise<string> {
+  const routed = withWorkflowModelRouting(runtime, params, callSite);
+  return (await runtime.useModel(modelType, routed.params, routed.provider)) as string;
 }
 
 /**
@@ -85,7 +248,8 @@ export async function extractKeywords(
     result = await useStructuredModel<KeywordExtractionResult>(
       runtime,
       `${KEYWORD_EXTRACTION_SYSTEM_PROMPT}${buildPreferredProvidersDirective(preferredProviders)}\n\nUser request: ${userPrompt}`,
-      keywordExtractionSchema
+      keywordExtractionSchema,
+      'extractKeywords'
     );
   } catch (error) {
     const errMsg = error instanceof Error ? error.message : String(error);
@@ -97,7 +261,7 @@ export async function extractKeywords(
   }
 
   // Validate structure
-  if (!result?.keywords || !Array.isArray(result.keywords)) {
+  if (!result || typeof result !== 'object' || !Array.isArray(result.keywords)) {
     logger.error(
       {
         src: 'plugin:workflow:generation:keywords',
@@ -153,7 +317,8 @@ ${workflowList}`;
       result = await useStructuredModel<WorkflowMatchResult>(
         runtime,
         `${WORKFLOW_MATCHING_SYSTEM_PROMPT}\n\n${userPrompt}`,
-        workflowMatchingSchema
+        workflowMatchingSchema,
+        'matchWorkflow'
       );
     } catch (innerError) {
       const errMsg = innerError instanceof Error ? innerError.message : String(innerError);
@@ -218,7 +383,8 @@ ${draftSummary}
 ## User Message
 
 ${userMessage}`,
-      draftIntentSchema
+      draftIntentSchema,
+      'classifyDraftIntent'
     );
   } catch (error) {
     const errMsg = error instanceof Error ? error.message : String(error);
@@ -233,7 +399,7 @@ ${userMessage}`,
   }
 
   const validIntents = ['confirm', 'cancel', 'modify', 'new'] as const;
-  if (!result?.intent || !validIntents.includes(result.intent as (typeof validIntents)[number])) {
+  if (!result.intent || !validIntents.includes(result.intent as (typeof validIntents)[number])) {
     logger.warn(
       { src: 'plugin:workflow:generation:intent' },
       `Invalid intent from LLM: ${JSON.stringify(result)}, re-showing preview`
@@ -301,11 +467,16 @@ Return the COMPLETE corrected workflow JSON. Preserve every field that was not p
 
   let response: string;
   try {
-    response = (await runtime.useModel(ModelType.TEXT_LARGE, {
-      prompt: fixPrompt,
-      temperature: 0,
-      responseFormat: { type: 'json_object' },
-    })) as string;
+    response = await useWorkflowTextModel(
+      runtime,
+      ModelType.TEXT_LARGE,
+      {
+        prompt: fixPrompt,
+        temperature: 0,
+        responseFormat: { type: 'json_object' },
+      },
+      'fixWorkflowErrors'
+    );
   } catch (err) {
     const errMsg = err instanceof Error ? err.message : String(err);
     logger.error(
@@ -501,11 +672,16 @@ async function callLlmAndParseWorkflow(
   context: 'generateWorkflow' | 'modifyWorkflow'
 ): Promise<WorkflowDefinition> {
   const callOnce = async (extraInstruction?: string): Promise<string> =>
-    (await runtime.useModel(ModelType.TEXT_LARGE, {
-      prompt: extraInstruction ? `${prompt}\n\n${extraInstruction}` : prompt,
-      temperature: 0,
-      responseFormat: { type: 'json_object' },
-    })) as string;
+    useWorkflowTextModel(
+      runtime,
+      ModelType.TEXT_LARGE,
+      {
+        prompt: extraInstruction ? `${prompt}\n\n${extraInstruction}` : prompt,
+        temperature: 0,
+        responseFormat: { type: 'json_object' },
+      },
+      context
+    );
 
   const firstResponse = await callOnce();
   try {
@@ -630,9 +806,14 @@ export async function formatActionResponse(
   data: Record<string, unknown>
 ): Promise<string> {
   try {
-    const response = await runtime.useModel(ModelType.TEXT_SMALL, {
-      prompt: `${ACTION_RESPONSE_SYSTEM_PROMPT}\n\nType: ${responseType}\n\nData:\n${formatActionDataForPrompt(data)}`,
-    });
+    const response = await useWorkflowTextModel(
+      runtime,
+      ModelType.TEXT_SMALL,
+      {
+        prompt: `${ACTION_RESPONSE_SYSTEM_PROMPT}\n\nType: ${responseType}\n\nData:\n${formatActionDataForPrompt(data)}`,
+      },
+      'formatActionResponse'
+    );
 
     return (response as string).trim();
   } catch (error) {
@@ -713,7 +894,8 @@ export async function assessFeasibility(
         `\n\n## Removed Integrations (unavailable)\n${removedList}` +
         `\n\n## Available Service Integrations\n${availableList}` +
         `\n\n## Available Utility Nodes\n${utilityList}`,
-      feasibilitySchema
+      feasibilitySchema,
+      'assessFeasibility'
     );
 
     return result;
@@ -756,10 +938,15 @@ export async function correctFieldReferences(
           ref.expression
         ).replace('{availableFields}', ref.availableFields.join('\n'));
 
-        const corrected = await runtime.useModel(ModelType.TEXT_SMALL, {
-          prompt: `${FIELD_CORRECTION_SYSTEM_PROMPT}\n\n${userPrompt}`,
-          temperature: 0,
-        });
+        const corrected = await useWorkflowTextModel(
+          runtime,
+          ModelType.TEXT_SMALL,
+          {
+            prompt: `${FIELD_CORRECTION_SYSTEM_PROMPT}\n\n${userPrompt}`,
+            temperature: 0,
+          },
+          'correctFieldReferences'
+        );
 
         const cleaned = (corrected as string).trim();
         return {
@@ -915,10 +1102,15 @@ export async function correctParameterNames(
           .replace('{currentParams}', JSON.stringify(detection.currentParams, null, 2))
           .replace('{propertyDefs}', JSON.stringify(detection.propertyDefs, null, 2));
 
-        const response = await runtime.useModel(ModelType.TEXT_SMALL, {
-          prompt: `${PARAM_CORRECTION_SYSTEM_PROMPT}\n\n${userPrompt}`,
-          temperature: 0,
-        });
+        const response = await useWorkflowTextModel(
+          runtime,
+          ModelType.TEXT_SMALL,
+          {
+            prompt: `${PARAM_CORRECTION_SYSTEM_PROMPT}\n\n${userPrompt}`,
+            temperature: 0,
+          },
+          'correctParameterNames'
+        );
 
         const cleaned = (response as string)
           .replace(/^[\s\S]*?```(?:json)?\s*\n?/i, '')

package/src/utils/host-capabilities.ts

@@ -31,7 +31,7 @@ export function detectHostCapabilities(): HostCapabilities {
   // Cloudflare Workers — runtime exposes navigator.userAgent === 'Cloudflare-Workers'.
   if (
     typeof navigator !== 'undefined' &&
-    typeof navigator?.userAgent === 'string' &&
+    typeof navigator.userAgent === 'string' &&
     navigator.userAgent.includes('Cloudflare-Workers')
   ) {
     return {
@@ -45,24 +45,40 @@ export function detectHostCapabilities(): HostCapabilities {
   }
 
   // Capacitor (iOS / Android). Capacitor exposes a global on the window/globalThis.
+  // `longRunning` is conditional on a registered BackgroundRunner plugin: without
+  // it, the JS context suspends within seconds of backgrounding (iOS WKWebView
+  // aggressively) and any `requiresLongRunning` node (scheduleTrigger, etc.)
+  // is dead the moment the user leaves the app. With it, the OS may wake the
+  // runner JS context periodically (≥15 min on both platforms) and the engine
+  // can argue it has cross-suspend continuity. We detect by probing for the
+  // plugin instance rather than trusting a build-time flag.
   const capacitor: unknown = Reflect.get(globalThis, 'Capacitor');
   if (capacitor && typeof capacitor === 'object') {
+    const plugins: unknown = Reflect.get(capacitor as object, 'Plugins');
+    const bgRunner: unknown =
+      plugins && typeof plugins === 'object'
+        ? Reflect.get(plugins as object, 'BackgroundRunner')
+        : undefined;
+    const hasBgRunner = typeof bgRunner === 'object' && bgRunner !== null;
     return {
       fs: false,
       inbound: false, // No public HTTP without plugin-tunnel
-      longRunning: true, // App stays alive while running; bg runner handles wake-ups
+      longRunning: hasBgRunner,
       childProcess: false,
       net: false,
-      label: 'Mobile (Capacitor)',
+      label: hasBgRunner
+        ? 'Mobile (Capacitor + BackgroundRunner)'
+        : 'Mobile (Capacitor, foreground-only)',
     };
   }
 
-  // Browser without Capacitor — pure web.
+  // Browser without Capacitor — pure web. Browser tabs can be backgrounded
+  // and discarded; treat as short-lived for scheduling purposes.
   if (typeof window !== 'undefined' && typeof process === 'undefined') {
     return {
       fs: false,
       inbound: false,
-      longRunning: true,
+      longRunning: false,
       childProcess: false,
       net: false,
       label: 'Browser',

package/src/utils/inferSyntheticOutputSchema.ts

@@ -39,7 +39,7 @@ function inferSummarizeFields(node: WorkflowNode): string[] | null {
   }
   const out: string[] = [];
   for (const entry of fields.values) {
-    if (typeof entry?.aggregation !== 'string' || typeof entry?.field !== 'string') {
+    if (typeof entry.aggregation !== 'string' || typeof entry.field !== 'string') {
       continue;
     }
     const prefix = SUMMARIZE_AGG_PREFIX[entry.aggregation];
@@ -64,7 +64,7 @@ function inferSetFields(node: WorkflowNode): string[] | null {
   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)
+      .map((a) => a.name)
       .filter((n): n is string => typeof n === 'string' && n.length > 0);
     if (names.length > 0) {
       return names;
@@ -80,7 +80,7 @@ function inferSetFields(node: WorkflowNode): string[] | null {
         continue;
       }
       for (const v of arr) {
-        if (typeof v?.name === 'string' && v.name.length > 0) {
+        if (typeof v.name === 'string' && v.name.length > 0) {
           names.push(v.name);
         }
       }

package/src/utils/outputSchema.ts

@@ -93,7 +93,7 @@ export function loadTriggerOutputSchema(
     return null;
   }
   const entry = TRIGGER_SCHEMAS[nodeType];
-  if (!entry?.outputSchema?.properties || Object.keys(entry.outputSchema.properties).length === 0) {
+  if (!entry?.outputSchema.properties || Object.keys(entry.outputSchema.properties).length === 0) {
     return null;
   }
   return {