@elizaos/plugin-workflow 2.0.0-beta.1

package/src/types/index.ts

@@ -0,0 +1,562 @@
+import type { EventPayload } from '@elizaos/core';
+import type {
+  INode,
+  INodeCredentialsDetails,
+  INodeProperties,
+  INodeTypeDescription,
+  IWorkflowSettings,
+} from '@elizaos/workflows';
+
+// Core workflow types
+
+export interface WorkflowDefinition {
+  name: string;
+  nodes: WorkflowNode[];
+  connections: WorkflowConnections;
+  active?: boolean;
+  settings?: Partial<IWorkflowSettings>;
+  tags?: WorkflowTag[];
+  meta?: Record<string, unknown>;
+  id?: string;
+  createdAt?: string;
+  updatedAt?: string;
+  /**
+   * Metadata generated by LLM (not sent to workflow API)
+   * Used internally for preview and clarification
+   */
+  _meta?: WorkflowMeta;
+}
+
+/**
+ * Workflow metadata for internal use
+ * Generated by LLM, used for preview and clarification
+ * NOT sent to workflow API
+ */
+export interface WorkflowMeta {
+  assumptions?: string[];
+  suggestions?: string[];
+  /**
+   * Accepts either legacy free-text strings (one question per item) or
+   * structured ClarificationRequest objects. Hosts that consume this field
+   * should run it through `coerceClarificationRequests` to normalize.
+   */
+  requiresClarification?: Array<string | ClarificationRequest>;
+}
+
+/**
+ * A structured request for additional information from the user before
+ * a workflow can be deployed. Lets the host render a quick-pick UI and
+ * patch the draft at the named param path on resolution, instead of
+ * regenerating the workflow with the LLM.
+ */
+export interface ClarificationRequest {
+  /**
+   * Semantic category of the missing value. Determines how the host
+   * renders the picker (channel/server/recipient pickers vs. free text).
+   */
+  kind: 'target_channel' | 'target_server' | 'recipient' | 'value' | 'free_text';
+  /**
+   * Connector platform this clarification belongs to (e.g. 'discord',
+   * 'slack', 'telegram', 'gmail'). Drives catalog source selection.
+   */
+  platform?: string;
+  /**
+   * Narrowing scope for catalog lookups. For Discord channel pickers,
+   * `scope.guildId` constrains the channel list to a single guild.
+   */
+  scope?: { guildId?: string };
+  /**
+   * Short, user-facing question rendered above the picker.
+   */
+  question: string;
+  /**
+   * JSON-style path into the draft workflow that points at the parameter
+   * the user's choice should populate. Supports dot and bracketed-string
+   * segments, e.g. `nodes["Discord Send"].parameters.channelId`.
+   */
+  paramPath: string;
+}
+
+export interface WorkflowNode
+  extends Omit<INode, 'id' | 'parameters' | 'credentials' | 'position'> {
+  id?: string;
+  position: [number, number];
+  parameters: Record<string, unknown>;
+  credentials?: Record<string, WorkflowCredentialReference>;
+  color?: string;
+}
+
+export interface WorkflowCredentialReference extends Omit<INodeCredentialsDetails, 'id'> {
+  id: string;
+}
+
+export interface WorkflowConnections {
+  [nodeName: string]: {
+    [outputType: string]: Array<
+      Array<{
+        node: string;
+        type: string;
+        index: number;
+      }>
+    >;
+  };
+}
+
+// workflow API response types
+
+export interface WorkflowDefinitionResponse extends WorkflowDefinition {
+  id: string;
+  createdAt: string;
+  updatedAt: string;
+  versionId: string;
+}
+
+export interface WorkflowCredential {
+  id: string;
+  name: string;
+  type: string;
+  data?: Record<string, unknown>;
+  isResolvable?: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface WorkflowExecution {
+  id: string;
+  finished: boolean;
+  mode:
+    | 'cli'
+    | 'error'
+    | 'integrated'
+    | 'internal'
+    | 'manual'
+    | 'retry'
+    | 'trigger'
+    | 'webhook'
+    | 'evaluation'
+    | 'chat';
+  retryOf?: string | null;
+  retrySuccessId?: string | null;
+  startedAt: string;
+  stoppedAt?: string | null;
+  workflowId: string;
+  status: 'canceled' | 'crashed' | 'error' | 'new' | 'running' | 'success' | 'unknown' | 'waiting';
+  waitTill?: string | null;
+  customData?: Record<string, unknown>;
+  data?: {
+    resultData?: {
+      runData?: Record<string, unknown[]>;
+      lastNodeExecuted?: string;
+      error?: {
+        message: string;
+        stack?: string;
+      };
+    };
+    executionData?: {
+      contextData?: Record<string, unknown>;
+      nodeExecutionStack?: unknown[];
+      waitingExecution?: Record<string, unknown>;
+    };
+  };
+}
+
+export interface WorkflowTag {
+  id: string;
+  name: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+// Node catalog types (from workflows-intelligence)
+
+export interface NodeDefinition
+  extends Omit<
+    INodeTypeDescription,
+    | 'credentials'
+    | 'group'
+    | 'icon'
+    | 'iconUrl'
+    | 'inputs'
+    | 'outputs'
+    | 'polling'
+    | 'properties'
+    | 'triggerPanel'
+    | 'webhooks'
+  > {
+  icon?: string;
+  iconUrl?: string;
+  group: string[];
+  defaults: {
+    name: string;
+    color?: string;
+  };
+  inputs: string[] | string;
+  outputs: string[] | string;
+  credentials?: Array<{
+    name: string;
+    required: boolean;
+    displayOptions?: unknown;
+  }>;
+  properties: NodeProperty[];
+  webhooks?: Array<Record<string, unknown>>;
+  polling?: boolean;
+  triggerPanel?: unknown;
+}
+
+export interface NodePropertyOption {
+  name: string;
+  value?: string | number | boolean;
+  displayName?: string;
+  description?: string;
+  [key: string]: unknown;
+}
+
+export interface NodePropertyCollection {
+  name: string;
+  displayName?: string;
+  values: NodeProperty[];
+  [key: string]: unknown;
+}
+
+export interface NodeProperty
+  extends Omit<INodeProperties, 'default' | 'displayOptions' | 'options' | 'routing' | 'type'> {
+  type: string;
+  default: unknown;
+  options?: Array<NodePropertyOption | NodePropertyCollection>;
+  displayOptions?: unknown;
+  placeholder?: string;
+  hint?: string;
+  routing?: unknown;
+  [key: string]: unknown;
+}
+
+export interface NodeSearchResult {
+  node: NodeDefinition;
+  score: number;
+  matchReason: string;
+}
+
+export interface IntegrationFilterResult {
+  remaining: NodeSearchResult[];
+  removed: NodeSearchResult[];
+}
+
+// Workflow generation types
+
+export interface KeywordExtractionResult {
+  keywords: string[];
+}
+
+/**
+ * Result of semantic workflow matching
+ */
+export interface WorkflowMatchResult {
+  matchedWorkflowId: string | null;
+  confidence: 'high' | 'medium' | 'low' | 'none';
+  matches: Array<{
+    id: string;
+    name: string;
+    score: number;
+  }>;
+  reason: string;
+}
+
+export interface WorkflowValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+// Credential provider types
+
+export const WORKFLOW_CREDENTIAL_PROVIDER_TYPE = 'workflow_credential_provider';
+
+/**
+ * Result of a credential resolution attempt by an external provider.
+ */
+export type CredentialProviderResult =
+  | { status: 'credential_data'; data: Record<string, unknown> }
+  | { status: 'needs_auth'; authUrl: string }
+  | null;
+
+/**
+ * External credential provider interface.
+ *
+ * Hosts (e.g. eliza-cloud) can register a service implementing this interface
+ * to automatically resolve credentials (via OAuth, API keys, etc.).
+ * The plugin works without one — it's an optional enhancement.
+ *
+ * Register on runtime as service type 'workflow_credential_provider'.
+ */
+export interface CredentialProvider {
+  resolve(userId: string, credType: string): Promise<CredentialProviderResult>;
+  checkCredentialTypes?(credTypes: string[]): CheckCredentialTypesResult;
+}
+
+export interface CheckCredentialTypesResult {
+  supported: string[];
+  unsupported: string[];
+}
+
+export interface FeasibilityResult {
+  feasible: boolean;
+  reason: string;
+}
+
+/**
+ * Type guard to check if a service implements CredentialProvider
+ */
+export function isCredentialProvider(service: unknown): service is CredentialProvider {
+  if (!service || typeof service !== 'object') {
+    return false;
+  }
+  return typeof (service as Record<string, unknown>).resolve === 'function';
+}
+
+// Runtime context provider types
+
+export const WORKFLOW_RUNTIME_CONTEXT_PROVIDER_TYPE = 'workflow_runtime_context_provider';
+
+export interface RuntimeContextSupportedCredential {
+  credType: string;
+  friendlyName: string;
+  nodeTypes: string[];
+}
+
+/**
+ * Optional runtime-supplied context the host injects into the workflow-generation
+ * prompt. The plugin treats this as advisory information for the LLM:
+ * - `supportedCredentials` becomes a "## Available Credentials" section so the
+ *   LLM only references credential types the host can actually resolve.
+ * - `facts` becomes a "## Runtime Facts" section with real values (Discord
+ *   guilds/channels, the user's Gmail email, etc.) so the LLM substitutes
+ *   them verbatim instead of emitting `{{YOUR_…}}` placeholders.
+ *
+ * The plugin works without a provider — both sections are simply omitted.
+ */
+export interface RuntimeContext {
+  /**
+   * Optional. When omitted (or empty), the generation prompt simply
+   * skips the "## Available Credentials" section. Implementers can
+   * return only what they have without fabricating empty arrays.
+   */
+  supportedCredentials?: RuntimeContextSupportedCredential[];
+  /**
+   * Optional. When omitted (or empty), the generation prompt simply
+   * skips the "## Runtime Facts" section.
+   */
+  facts?: string[];
+  /**
+   * Optional bias hint for keyword extraction. Lowercase provider tags the
+   * host knows it can satisfy (e.g. `["gmail", "discord"]`). When present,
+   * keyword extraction nudges the LLM toward these providers and away from
+   * generic fallbacks (e.g. emit `gmail` not `imap`, `discord` not
+   * `webhook`). Always optional — older hosts that omit it keep working.
+   */
+  preferredProviders?: string[];
+}
+
+/**
+ * Originating-conversation routing context. Hosts pass this when the workflow
+ * is being generated from inside a platform conversation (e.g. a Discord DM),
+ * so the LLM can target "this channel" / "back to me" without the user having
+ * to name an ID. The host typically derives it from the inbound message's
+ * `MessageMetadata` and surfaces it as a fact line ("This workflow was
+ * prompted from Discord channel #foo (id 123) in Bar (id 456)…").
+ *
+ * All fields are optional. Hosts only fill the platform block that matches
+ * the trigger source. `resolvedNames` lets the host pass human names for the
+ * channel / server (when available) so the prompt can reference them in
+ * natural language.
+ */
+export interface TriggerContext {
+  /** Source platform — `"discord" | "telegram" | "slack" | "gmail" | …` */
+  source?: string;
+  discord?: { channelId?: string; guildId?: string; threadId?: string };
+  telegram?: { chatId?: string | number; threadId?: string | number };
+  slack?: { channelId?: string; teamId?: string };
+  resolvedNames?: { channel?: string; server?: string };
+}
+
+export interface RuntimeContextProviderInput {
+  userId: string;
+  relevantNodes: NodeDefinition[];
+  relevantCredTypes: string[];
+  /**
+   * Optional originating-conversation context. Forward-compatible: hosts that
+   * don't know about it simply omit the field.
+   */
+  triggerContext?: TriggerContext;
+}
+
+export interface RuntimeContextProvider {
+  getRuntimeContext(input: RuntimeContextProviderInput): Promise<RuntimeContext>;
+}
+
+/**
+ * Type guard to check if a service implements RuntimeContextProvider.
+ */
+export function isRuntimeContextProvider(service: unknown): service is RuntimeContextProvider {
+  if (!service || typeof service !== 'object') {
+    return false;
+  }
+  return typeof (service as Record<string, unknown>).getRuntimeContext === 'function';
+}
+
+// Credential store types
+
+export const WORKFLOW_CREDENTIAL_STORE_TYPE = 'workflow_credential_store';
+
+/**
+ * Runtime event emitted by the host (e.g. agent connector routes) when a
+ * connector is disconnected. WorkflowCredentialStore subscribes to this in
+ * `start()` and purges its cached credential ids for the supplied credTypes,
+ * so the next workflow generation surfaces `needs_auth` instead of returning
+ * a stale id.
+ *
+ * Payload shape kept minimal and serializable so any host can emit without
+ * pulling in plugin-workflow types — `userId` + `credTypes` is enough for
+ * the store to do its job. `connectorName` is informational for subscribers
+ * that want richer context.
+ */
+export const CONNECTOR_DISCONNECTED_EVENT = 'connector_disconnected';
+
+export interface ConnectorDisconnectedPayload extends EventPayload {
+  /** Owner of the credentials to purge — typically `runtime.agentId`. */
+  userId: string;
+  /**
+   * Workflow credential type ids tied to the disconnected connector
+   * (e.g. `['gmailOAuth2', 'gmailOAuth2Api']`). Empty list ⇒ no-op.
+   */
+  credTypes: readonly string[];
+  /** Connector name (e.g. `'gmail'`). Informational. */
+  connectorName?: string;
+}
+
+export interface CredentialMapping {
+  credType: string;
+  workflowCredentialId: string;
+}
+
+export interface WorkflowCredentialStoreApi {
+  get(userId: string, credType: string): Promise<string | null>;
+  set(userId: string, credType: string, workflowCredId: string): Promise<void>;
+  listByUser(userId: string): Promise<CredentialMapping[]>;
+  /**
+   * Forget the cached workflows credential id for (userId, credType). The next
+   * resolution falls back to credProvider so a disconnect-then-prompt flow
+   * surfaces `needs_auth` instead of reusing stale credentials.
+   *
+   * Optional: external/custom credential-store implementations that pre-date
+   * this method continue to satisfy the interface; hosts that need to cascade
+   * a disconnect must check for the method (`store.delete?.(userId, credType)`)
+   * before calling.
+   */
+  delete?(userId: string, credType: string): Promise<void>;
+}
+
+// Credential resolution types
+
+export interface CredentialResolutionResult {
+  workflow: WorkflowDefinition;
+  missingConnections: MissingConnection[];
+  injectedCredentials: Map<string, string>; // credType -> workflowCredId
+}
+
+export interface MissingConnection {
+  credType: string;
+  authUrl?: string;
+}
+
+// Plugin configuration types
+
+export interface WorkflowPluginConfig {
+  apiKey: string;
+  host: string;
+  credentials?: Record<string, string>; // credType -> workflowCredId (for local pre-configured mode)
+}
+
+// Draft/preview/confirm types
+
+export interface WorkflowDraft {
+  workflow: WorkflowDefinition;
+  prompt: string;
+  userId: string;
+  createdAt: number;
+  /** ID of the message that created this draft — used to prevent same-turn auto-confirm. */
+  originMessageId?: string;
+}
+
+export interface DraftIntentResult {
+  intent: 'confirm' | 'cancel' | 'modify' | 'new' | 'show_preview';
+  modificationRequest?: string;
+  reason: string;
+}
+
+export interface WorkflowCreationResult {
+  id: string;
+  name: string;
+  active: boolean;
+  nodeCount: number;
+  missingCredentials: MissingConnection[];
+}
+
+// Error types
+
+export class WorkflowApiError extends Error {
+  constructor(
+    message: string,
+    public statusCode?: number,
+    public response?: unknown
+  ) {
+    super(message);
+    this.name = 'WorkflowApiError';
+  }
+}
+
+export class UnsupportedIntegrationError extends Error {
+  constructor(
+    public unsupportedServices: string[],
+    public availableServices: string[]
+  ) {
+    super(`Unsupported integrations: ${unsupportedServices.join(', ')}`);
+    this.name = 'UnsupportedIntegrationError';
+  }
+}
+
+// Output schema validation types
+
+/**
+ * JSON schema content from workflows output schemas
+ */
+export interface SchemaContent {
+  type: string;
+  properties?: Record<string, unknown>;
+  items?: SchemaContent;
+  [key: string]: unknown;
+}
+
+/**
+ * Expression reference found in node parameters
+ */
+export interface ExpressionRef {
+  fullExpression: string; // "{{ $json.sender }}"
+  field: string; // "sender" or "from.value[0].address"
+  path: string[]; // ["sender"] or ["from", "value", "0", "address"]
+  paramPath: string; // Parameter path where expression was found
+  sourceNodeName?: string; // Node name from $('NodeName') syntax, undefined for $json refs
+}
+
+/**
+ * Invalid output reference detected during validation
+ */
+export interface OutputRefValidation {
+  nodeName: string; // Node with invalid reference
+  expression: string; // The full expression
+  field: string; // Referenced field
+  sourceNodeName: string; // Upstream node
+  sourceNodeType: string; // Upstream node type
+  resource: string; // Resource parameter
+  operation: string; // Operation parameter
+  availableFields: string[]; // Valid fields from schema
+}