@elizaos/plugin-workflow 2.0.0-beta.1

package/src/plugin-routes.ts

@@ -0,0 +1,164 @@
+/**
+ * Workflow route plugin — registers `/api/workflow/*` route handlers with the
+ * elizaOS runtime plugin route system. The handlers run in-process against
+ * plugin-workflow services; there is no external workflow server or sidecar.
+ */
+
+import type http from 'node:http';
+import type { Plugin, Route } from '@elizaos/core';
+import { handleAutomationsRoutes } from './routes/automations';
+import { handleWorkflowRoutes, type WorkflowRouteContext } from './routes/workflow-routes';
+
+type AnyRuntime = WorkflowRouteContext['runtime'];
+
+interface WorkflowCompatState {
+  current: AnyRuntime;
+}
+
+function buildState(runtime: unknown): WorkflowCompatState {
+  return { current: runtime as AnyRuntime } as WorkflowCompatState;
+}
+
+function jsonResponder(httpRes: http.ServerResponse) {
+  return (_res: http.ServerResponse, body: unknown, status = 200) => {
+    if (httpRes.headersSent) return;
+    httpRes.statusCode = status;
+    httpRes.setHeader('content-type', 'application/json; charset=utf-8');
+    httpRes.end(JSON.stringify(body));
+  };
+}
+
+function makeWorkflowHandler() {
+  return async (req: unknown, res: unknown, runtime: unknown): Promise<void> => {
+    const httpReq = req as http.IncomingMessage;
+    const httpRes = res as http.ServerResponse;
+    const url = new URL(httpReq.url ?? '/', 'http://localhost');
+    const method = (httpReq.method ?? 'GET').toUpperCase();
+    const state = buildState(runtime);
+
+    await handleWorkflowRoutes({
+      req: httpReq,
+      res: httpRes,
+      method,
+      pathname: url.pathname,
+      runtime: state.current,
+      json: jsonResponder(httpRes),
+    });
+  };
+}
+
+function makeAutomationsHandler() {
+  return async (req: unknown, res: unknown, runtime: unknown): Promise<void> => {
+    const httpReq = req as http.IncomingMessage;
+    const httpRes = res as http.ServerResponse;
+    const url = new URL(httpReq.url ?? '/', 'http://localhost');
+    const method = (httpReq.method ?? 'GET').toUpperCase();
+    const state = buildState(runtime);
+
+    await handleAutomationsRoutes({
+      req: httpReq,
+      res: httpRes,
+      method,
+      pathname: url.pathname,
+      runtime: state.current,
+      json: jsonResponder(httpRes),
+    });
+  };
+}
+
+const workflowHandler = makeWorkflowHandler();
+const automationsHandler = makeAutomationsHandler();
+
+const workflowRouteList: Route[] = [
+  // Status surface
+  {
+    type: 'GET',
+    path: '/api/workflow/status',
+    rawPath: true,
+    handler: workflowHandler,
+  },
+  // Runtime lifecycle/status compatibility
+  {
+    type: 'POST',
+    path: '/api/workflow/runtime/start',
+    rawPath: true,
+    handler: workflowHandler,
+  },
+  // Workflow CRUD
+  {
+    type: 'GET',
+    path: '/api/workflow/workflows',
+    rawPath: true,
+    handler: workflowHandler,
+  },
+  {
+    type: 'POST',
+    path: '/api/workflow/workflows',
+    rawPath: true,
+    handler: workflowHandler,
+  },
+  {
+    type: 'POST',
+    path: '/api/workflow/workflows/generate',
+    rawPath: true,
+    handler: workflowHandler,
+  },
+  {
+    type: 'POST',
+    path: '/api/workflow/workflows/resolve-clarification',
+    rawPath: true,
+    handler: workflowHandler,
+  },
+  {
+    type: 'GET',
+    path: '/api/workflow/workflows/:id',
+    rawPath: true,
+    handler: workflowHandler,
+  },
+  {
+    type: 'PUT',
+    path: '/api/workflow/workflows/:id',
+    rawPath: true,
+    handler: workflowHandler,
+  },
+  {
+    type: 'POST',
+    path: '/api/workflow/workflows/:id/activate',
+    rawPath: true,
+    handler: workflowHandler,
+  },
+  {
+    type: 'POST',
+    path: '/api/workflow/workflows/:id/deactivate',
+    rawPath: true,
+    handler: workflowHandler,
+  },
+  {
+    type: 'DELETE',
+    path: '/api/workflow/workflows/:id',
+    rawPath: true,
+    handler: workflowHandler,
+  },
+  {
+    type: 'GET',
+    path: '/api/workflow/workflows/:id/executions',
+    rawPath: true,
+    handler: workflowHandler,
+  },
+  // Cross-cutting `/api/automations` surface — combines workflows, triggers,
+  // workbench tasks, and draft conversations into a single list view.
+  {
+    type: 'GET',
+    path: '/api/automations',
+    rawPath: true,
+    handler: automationsHandler,
+  },
+];
+
+export const workflowRoutePlugin: Plugin = {
+  name: '@elizaos/plugin-workflow:routes',
+  description: 'Workflow routes — in-process status, generation, CRUD, and lifecycle handlers.',
+  routes: workflowRouteList,
+};
+
+export default workflowRoutePlugin;

package/src/providers/activeWorkflows.ts

@@ -0,0 +1,81 @@
+import { type IAgentRuntime, logger, type Memory, type Provider, type State } from '@elizaos/core';
+import { WORKFLOW_SERVICE_TYPE, type WorkflowService } from '../services/index';
+
+/**
+ * Provider that enriches state with user's active workflows
+ *
+ * This provider runs for every message and adds workflow information to the state,
+ * allowing the LLM to automatically extract workflow IDs and references from context.
+ *
+ * Example: User says "run my Stripe workflow" → LLM can see all workflows and extract the right ID
+ */
+export const activeWorkflowsProvider: Provider = {
+  name: 'ACTIVE_WORKFLOWS',
+  description: "User's active workflows with IDs and descriptions",
+  contexts: ['automation', 'connectors'],
+  contextGate: { anyOf: ['automation', 'connectors'] },
+  cacheScope: 'agent',
+  roleGate: { minRole: 'ADMIN' },
+
+  get: async (runtime: IAgentRuntime, _message: Memory, _state: State) => {
+    try {
+      const service = runtime.getService<WorkflowService>(WORKFLOW_SERVICE_TYPE);
+
+      if (!service) {
+        return {
+          text: '',
+          data: {},
+          values: {},
+        };
+      }
+
+      const userId = _message.entityId;
+      const workflows = await service.listWorkflows(userId);
+
+      if (workflows.length === 0) {
+        return {
+          text: '',
+          data: { workflows: [] },
+          values: { hasWorkflows: false },
+        };
+      }
+
+      const workflowList = workflows
+        .slice(0, 20)
+        .map((wf) => {
+          const status = wf.active ? 'ACTIVE' : 'INACTIVE';
+          const nodeCount = wf.nodes?.length || 0;
+          return `- **${wf.name}** (ID: ${wf.id}, Status: ${status}, Nodes: ${nodeCount})`;
+        })
+        .join('\n');
+
+      const text = `# Available Workflows\n\n${workflowList}`;
+
+      return {
+        text,
+        data: {
+          workflows: workflows.map((wf) => ({
+            id: wf.id,
+            name: wf.name,
+            active: wf.active || false,
+            nodeCount: wf.nodes?.length || 0,
+          })),
+        },
+        values: {
+          hasWorkflows: true,
+          workflowCount: workflows.length,
+        },
+      };
+    } catch (error) {
+      logger.error(
+        { src: 'plugin:workflow:providers:active-workflows' },
+        `Failed to get active workflows: ${error instanceof Error ? error.message : String(error)}`
+      );
+      return {
+        text: '',
+        data: {},
+        values: {},
+      };
+    }
+  },
+};

package/src/providers/index.ts

@@ -0,0 +1,3 @@
+export { activeWorkflowsProvider } from './activeWorkflows';
+export { pendingDraftProvider } from './pendingDraft';
+export { workflowStatusProvider } from './workflowStatus';

package/src/providers/pendingDraft.ts

@@ -0,0 +1,55 @@
+import type { IAgentRuntime, Memory, Provider, State } from '@elizaos/core';
+import type { WorkflowDraft } from '../types/index';
+
+const DRAFT_TTL_MS = 30 * 60 * 1000;
+const MAX_DRAFT_NODES = 12;
+
+/**
+ * Provider that tells the LLM when a workflow draft is pending confirmation.
+ *
+ * Without this, the LLM has no context about pending drafts and will route
+ * confirmation messages (e.g. "yes, deploy it") to REPLY instead of WORKFLOW.
+ */
+export const pendingDraftProvider: Provider = {
+  name: 'PENDING_WORKFLOW_DRAFT',
+  description: 'Pending workflow draft awaiting user confirmation, modification, or cancellation',
+  contexts: ['automation', 'connectors'],
+  contextGate: { anyOf: ['automation', 'connectors'] },
+  cacheScope: 'conversation',
+  roleGate: { minRole: 'ADMIN' },
+
+  get: async (runtime: IAgentRuntime, message: Memory, _state: State) => {
+    try {
+      const cacheKey = `workflow_draft:${message.entityId}`;
+      const draft = await runtime.getCache<WorkflowDraft>(cacheKey);
+
+      if (!draft || Date.now() - draft.createdAt > DRAFT_TTL_MS) {
+        return { text: '', data: {}, values: {} };
+      }
+
+      const nodeNames = draft.workflow.nodes
+        .slice(0, MAX_DRAFT_NODES)
+        .map((n) => n.name)
+        .join(' → ');
+
+      return {
+        text:
+          '# Pending Workflow Draft\n\n' +
+          `A workflow draft "${draft.workflow.name}" is pending.\n` +
+          `Nodes: ${nodeNames}\n\n` +
+          '**REQUIRED**: Any user message about this draft MUST trigger the WORKFLOW action.\n' +
+          'This includes confirmations ("yes", "ok", "deploy it", "create it", "go ahead"),\n' +
+          'cancellations ("cancel", "nevermind"), and modifications ("change X", "use Y instead").\n' +
+          'The action handler manages all draft operations — do NOT handle them via text reply.\n' +
+          'You MUST include WORKFLOW in your actions.',
+        data: {
+          hasPendingDraft: true,
+          truncated: draft.workflow.nodes.length > MAX_DRAFT_NODES,
+        },
+        values: { hasPendingDraft: true },
+      };
+    } catch {
+      return { text: '', data: {}, values: {} };
+    }
+  },
+};

package/src/providers/workflowStatus.ts

@@ -0,0 +1,88 @@
+import { type IAgentRuntime, logger, type Memory, type Provider, type State } from '@elizaos/core';
+import { WORKFLOW_SERVICE_TYPE, type WorkflowService } from '../services/index';
+
+export const workflowStatusProvider: Provider = {
+  name: 'workflow_status',
+  contexts: ['automation', 'connectors'],
+  contextGate: { anyOf: ['automation', 'connectors'] },
+  cacheScope: 'turn',
+  roleGate: { minRole: 'ADMIN' },
+
+  get: async (runtime: IAgentRuntime, _message: Memory, _state: State) => {
+    try {
+      const service = runtime.getService<WorkflowService>(WORKFLOW_SERVICE_TYPE);
+
+      if (!service) {
+        logger.warn(
+          { src: 'plugin:workflow:provider:workflowStatus' },
+          'Workflow service not available for provider'
+        );
+        return {
+          text: '',
+          data: {},
+          values: {},
+        };
+      }
+
+      // Get workflows for the user
+      const userId = _message.entityId;
+
+      const workflows = await service.listWorkflows(userId);
+
+      if (workflows.length === 0) {
+        return {
+          text: 'No workflows configured yet.',
+          data: {},
+          values: {},
+        };
+      }
+
+      let status = `Current workflows (${workflows.length}):\n\n`;
+
+      for (const workflow of workflows.slice(0, 10)) {
+        const statusEmoji = workflow.active ? '✅' : '⏸️';
+        status += `${statusEmoji} ${workflow.name} (ID: ${workflow.id})\n`;
+        status += `   Nodes: ${workflow.nodes?.length || 0}\n`;
+
+        // Try to get last execution (if possible)
+        try {
+          const executions = await service.getWorkflowExecutions(workflow.id, 1);
+          if (executions.length > 0) {
+            const lastExec = executions[0];
+            const execEmoji =
+              lastExec.status === 'success' ? '✅' : lastExec.status === 'error' ? '❌' : '⏳';
+            status += `   Last run: ${execEmoji} ${lastExec.status} at ${new Date(lastExec.startedAt).toLocaleString()}\n`;
+          }
+        } catch (_error) {
+          // Ignore execution fetch errors
+          logger.debug(
+            { src: 'plugin:workflow:provider:workflowStatus' },
+            `Could not fetch executions for workflow ${workflow.id}`
+          );
+        }
+
+        status += '\n';
+      }
+
+      if (workflows.length > 10) {
+        status += `\n... and ${workflows.length - 10} more workflows.`;
+      }
+
+      return {
+        text: status,
+        data: { workflows },
+        values: { workflowCount: workflows.length },
+      };
+    } catch (error) {
+      logger.error(
+        { src: 'plugin:workflow:provider:workflowStatus' },
+        `Failed to get workflow status: ${error instanceof Error ? error.message : String(error)}`
+      );
+      return {
+        text: '',
+        data: {},
+        values: {},
+      };
+    }
+  },
+};

package/src/register-routes.ts

@@ -0,0 +1,6 @@
+import { registerAppRoutePluginLoader } from '@elizaos/core';
+
+registerAppRoutePluginLoader('@elizaos/plugin-workflow:routes', async () => {
+  const { workflowRoutePlugin } = await import('./plugin-routes');
+  return workflowRoutePlugin;
+});

package/src/routes/_helpers.ts

@@ -0,0 +1,27 @@
+import type { IAgentRuntime } from '@elizaos/core';
+import type { WorkflowService } from '../services/workflow-service';
+import { WORKFLOW_SERVICE_TYPE } from '../services/workflow-service';
+
+/**
+ * Extract WorkflowService from runtime services
+ */
+export function getService(runtime: IAgentRuntime): WorkflowService {
+  const service = runtime.getService<WorkflowService>(WORKFLOW_SERVICE_TYPE);
+
+  if (!service) {
+    throw new Error('WorkflowService not available in runtime');
+  }
+
+  return service;
+}
+
+/**
+ * Validate and clamp limit parameter
+ */
+export function validateLimit(limitParam: unknown, defaultLimit = 20, maxLimit = 100): number {
+  const limit = Number(limitParam);
+  if (!Number.isFinite(limit) || limit <= 0) {
+    return defaultLimit;
+  }
+  return Math.min(limit, maxLimit);
+}

package/src/routes/automations.ts

@@ -0,0 +1,46 @@
+/**
+ * `/api/automations` route handler. Lives in plugin-workflow because the
+ * response is built directly from the in-process WorkflowService (no proxy)
+ * plus the runtime task and room APIs.
+ */
+
+import type http from 'node:http';
+import type { AgentRuntime } from '@elizaos/core';
+import { buildAutomationListResponse } from '../lib/automations-builder';
+
+type JsonResponder = (res: http.ServerResponse, body: unknown, status?: number) => void;
+
+export interface AutomationsRouteContext {
+  req: http.IncomingMessage;
+  res: http.ServerResponse;
+  method: string;
+  pathname: string;
+  runtime: AgentRuntime | null;
+  json: JsonResponder;
+}
+
+function sendJson(ctx: AutomationsRouteContext, status: number, body: unknown): void {
+  ctx.json(ctx.res, body, status);
+}
+
+export async function handleAutomationsRoutes(ctx: AutomationsRouteContext): Promise<boolean> {
+  if (ctx.method.toUpperCase() !== 'GET') {
+    return false;
+  }
+  if (ctx.pathname !== '/api/automations') {
+    return false;
+  }
+  if (!ctx.runtime) {
+    sendJson(ctx, 503, { error: 'Agent runtime is not available' });
+    return true;
+  }
+  try {
+    const payload = await buildAutomationListResponse(ctx.runtime);
+    sendJson(ctx, 200, payload);
+  } catch (error) {
+    sendJson(ctx, 500, {
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+  return true;
+}

package/src/routes/embedded-webhooks.ts

@@ -0,0 +1,64 @@
+import type { IAgentRuntime, Route, RouteRequest, RouteResponse } from '@elizaos/core';
+import {
+  EMBEDDED_WORKFLOW_SERVICE_TYPE,
+  type EmbeddedWorkflowService,
+} from '../services/embedded-workflow-service';
+import { WorkflowApiError } from '../types/index';
+
+function getEmbeddedService(runtime: IAgentRuntime): EmbeddedWorkflowService {
+  const service = runtime.getService(
+    EMBEDDED_WORKFLOW_SERVICE_TYPE
+  ) as EmbeddedWorkflowService | null;
+  if (!service) {
+    throw new Error('EmbeddedWorkflowService not available in runtime');
+  }
+  return service;
+}
+
+function coerceBody(body: unknown): Record<string, unknown> {
+  return body && typeof body === 'object' && !Array.isArray(body)
+    ? (body as Record<string, unknown>)
+    : { body };
+}
+
+async function executeWebhook(
+  req: RouteRequest,
+  res: RouteResponse,
+  runtime: IAgentRuntime
+): Promise<void> {
+  try {
+    const path = req.params?.path;
+    if (!path) {
+      res.status(400).json({ success: false, error: 'webhook_path_required' });
+      return;
+    }
+
+    const service = getEmbeddedService(runtime);
+    const method = (req.method ?? 'POST').toUpperCase();
+    const execution = await service.executeWebhook(
+      path,
+      {
+        body: req.body ?? {},
+        query: req.query ?? {},
+        params: req.params ?? {},
+        ...coerceBody(req.body),
+      },
+      method
+    );
+    res.json({ success: true, data: execution });
+  } catch (error) {
+    res.status(error instanceof WorkflowApiError ? (error.statusCode ?? 500) : 500).json({
+      success: false,
+      error: 'failed_to_execute_webhook',
+      message: error instanceof Error ? error.message : 'Unknown error',
+    });
+  }
+}
+
+export const embeddedWebhookRoutes: Route[] = [
+  { type: 'GET', path: '/webhooks/:path', handler: executeWebhook },
+  { type: 'POST', path: '/webhooks/:path', handler: executeWebhook },
+  { type: 'PUT', path: '/webhooks/:path', handler: executeWebhook },
+  { type: 'PATCH', path: '/webhooks/:path', handler: executeWebhook },
+  { type: 'DELETE', path: '/webhooks/:path', handler: executeWebhook },
+];

package/src/routes/executions.ts

@@ -0,0 +1,75 @@
+import type { IAgentRuntime, Route, RouteRequest, RouteResponse } from '@elizaos/core';
+import { getService, validateLimit } from './_helpers';
+
+/**
+ * GET /executions?workflowId=x&status=y&limit=z&cursor=c
+ */
+async function listExecutions(
+  req: RouteRequest,
+  res: RouteResponse,
+  runtime: IAgentRuntime
+): Promise<void> {
+  try {
+    const workflowId = req.query?.workflowId as string | undefined;
+    const status = req.query?.status as
+      | 'canceled'
+      | 'error'
+      | 'running'
+      | 'success'
+      | 'waiting'
+      | undefined;
+    const limit = validateLimit(req.query?.limit, 50, 250);
+    const cursor = req.query?.cursor as string | undefined;
+
+    const service = getService(runtime);
+    const response = await service.listExecutions({
+      workflowId,
+      status,
+      limit,
+      cursor,
+    });
+    res.json({
+      success: true,
+      data: response.data,
+      nextCursor: response.nextCursor,
+    });
+  } catch (error) {
+    res.status(500).json({
+      success: false,
+      error: 'failed_to_list_executions',
+      message: error instanceof Error ? error.message : 'Unknown error',
+    });
+  }
+}
+
+/**
+ * GET /executions/:id
+ */
+async function getExecution(
+  req: RouteRequest,
+  res: RouteResponse,
+  runtime: IAgentRuntime
+): Promise<void> {
+  try {
+    const id = req.params?.id;
+    if (!id) {
+      res.status(400).json({ success: false, error: 'execution_id_required' });
+      return;
+    }
+
+    const service = getService(runtime);
+    const execution = await service.getExecutionDetail(id);
+    res.json({ success: true, data: execution });
+  } catch (error) {
+    res.status(500).json({
+      success: false,
+      error: 'failed_to_fetch_execution',
+      message: error instanceof Error ? error.message : 'Unknown error',
+    });
+  }
+}
+
+export const executionRoutes: Route[] = [
+  { type: 'GET', path: '/executions', handler: listExecutions },
+  { type: 'GET', path: '/executions/:id', handler: getExecution },
+];

package/src/routes/index.ts

@@ -0,0 +1,16 @@
+import type { Route } from '@elizaos/core';
+import { embeddedWebhookRoutes } from './embedded-webhooks';
+import { executionRoutes } from './executions';
+import { nodeRoutes } from './nodes';
+import { validationRoutes } from './validation';
+import { workflowRoutes as workflowCrudRoutes } from './workflows';
+
+export { type AutomationsRouteContext, handleAutomationsRoutes } from './automations';
+
+export const workflowRoutes: Route[] = [
+  ...validationRoutes,
+  ...workflowCrudRoutes,
+  ...nodeRoutes,
+  ...executionRoutes,
+  ...embeddedWebhookRoutes,
+];