@usejarvis/brain 0.1.0

package/src/workflows/nodes/builtin.ts

@@ -0,0 +1,119 @@
+/**
+ * Built-in Node Library — Phase 3
+ *
+ * Imports all node definitions and registers them into a NodeRegistry instance.
+ * Call registerBuiltinNodes(registry) once at startup.
+ */
+
+import type { NodeRegistry } from './registry.ts';
+
+// ── Triggers ──────────────────────────────────────────────────────────────────
+import { cronTrigger }        from './triggers/cron.ts';
+import { webhookTrigger }     from './triggers/webhook.ts';
+import { emailTrigger }       from './triggers/email.ts';
+import { fileChangeTrigger }  from './triggers/file-change.ts';
+import { screenEventTrigger } from './triggers/screen-event.ts';
+import { manualTrigger }      from './triggers/manual.ts';
+import { gitTrigger }         from './triggers/git.ts';
+import { clipboardTrigger }   from './triggers/clipboard.ts';
+import { processTrigger }     from './triggers/process.ts';
+import { calendarTrigger }    from './triggers/calendar.ts';
+import { pollTrigger }        from './triggers/poll.ts';
+
+// ── Actions ───────────────────────────────────────────────────────────────────
+import { sendMessageAction }   from './actions/send-message.ts';
+import { runToolAction }       from './actions/run-tool.ts';
+import { agentTaskAction }     from './actions/agent-task.ts';
+import { httpRequestAction }   from './actions/http-request.ts';
+import { fileWriteAction }     from './actions/file-write.ts';
+import { notificationAction }  from './actions/notification.ts';
+import { gmailAction }         from './actions/gmail.ts';
+import { calendarActionNode }  from './actions/calendar-action.ts';
+import { telegramAction }      from './actions/telegram.ts';
+import { discordAction }       from './actions/discord.ts';
+import { shellCommandAction }  from './actions/shell-command.ts';
+import { codeExecutionAction } from './actions/code-execution.ts';
+
+// ── Logic ─────────────────────────────────────────────────────────────────────
+import { ifElseNode }         from './logic/if-else.ts';
+import { switchNode }         from './logic/switch.ts';
+import { loopNode }           from './logic/loop.ts';
+import { delayNode }          from './logic/delay.ts';
+import { mergeNode }          from './logic/merge.ts';
+import { raceNode }           from './logic/race.ts';
+import { variableSetNode }    from './logic/variable-set.ts';
+import { variableGetNode }    from './logic/variable-get.ts';
+import { templateRenderNode } from './logic/template-render.ts';
+
+// ── Transform ─────────────────────────────────────────────────────────────────
+import { jsonParseTransform }  from './transform/json-parse.ts';
+import { csvParseTransform }   from './transform/csv-parse.ts';
+import { regexMatchTransform } from './transform/regex-match.ts';
+import { aggregateTransform }  from './transform/aggregate.ts';
+import { mapFilterTransform }  from './transform/map-filter.ts';
+
+// ── Error ─────────────────────────────────────────────────────────────────────
+import { errorHandlerNode } from './error/error-handler.ts';
+import { retryNode }        from './error/retry.ts';
+import { fallbackNode }     from './error/fallback.ts';
+
+/**
+ * Register all built-in nodes into the provided NodeRegistry.
+ * Throws if any node type is already registered (duplicate detection).
+ */
+export function registerBuiltinNodes(registry: NodeRegistry): void {
+  // Triggers
+  registry.register(cronTrigger);
+  registry.register(webhookTrigger);
+  registry.register(emailTrigger);
+  registry.register(fileChangeTrigger);
+  registry.register(screenEventTrigger);
+  registry.register(manualTrigger);
+  registry.register(gitTrigger);
+  registry.register(clipboardTrigger);
+  registry.register(processTrigger);
+  registry.register(calendarTrigger);
+  registry.register(pollTrigger);
+
+  // Actions
+  registry.register(sendMessageAction);
+  registry.register(runToolAction);
+  registry.register(agentTaskAction);
+  registry.register(httpRequestAction);
+  registry.register(fileWriteAction);
+  registry.register(notificationAction);
+  registry.register(gmailAction);
+  registry.register(calendarActionNode);
+  registry.register(telegramAction);
+  registry.register(discordAction);
+  registry.register(shellCommandAction);
+  registry.register(codeExecutionAction);
+
+  // Logic
+  registry.register(ifElseNode);
+  registry.register(switchNode);
+  registry.register(loopNode);
+  registry.register(delayNode);
+  registry.register(mergeNode);
+  registry.register(raceNode);
+  registry.register(variableSetNode);
+  registry.register(variableGetNode);
+  registry.register(templateRenderNode);
+
+  // Transform
+  registry.register(jsonParseTransform);
+  registry.register(csvParseTransform);
+  registry.register(regexMatchTransform);
+  registry.register(aggregateTransform);
+  registry.register(mapFilterTransform);
+
+  // Error
+  registry.register(errorHandlerNode);
+  registry.register(retryNode);
+  registry.register(fallbackNode);
+}
+
+/**
+ * Convenience: total number of built-in nodes across all categories.
+ */
+export const BUILTIN_NODE_COUNT = 40;

package/src/workflows/nodes/error/error-handler.ts

@@ -0,0 +1,37 @@
+import type { NodeDefinition } from '../registry.ts';
+
+export const errorHandlerNode: NodeDefinition = {
+  type: 'error.error_handler',
+  label: 'Error Handler',
+  description: 'Catch errors from upstream nodes and continue with a custom message.',
+  category: 'error',
+  icon: '🛡️',
+  color: '#ef4444',
+  configSchema: {
+    message: {
+      type: 'template',
+      label: 'Message',
+      description: 'Custom error message to include in output. Supports template expressions.',
+      required: false,
+      placeholder: 'An error occurred: {{data.error}}',
+    },
+  },
+  inputs: ['default', 'error'],
+  outputs: ['default'],
+  execute: async (input, config, ctx) => {
+    const message = config.message ? String(config.message) : 'An error was handled by the error handler node.';
+    ctx.logger.info(`Error handler triggered: ${message.slice(0, 120)}`);
+
+    const errorData = input.data['_error'] ?? input.data['error'] ?? null;
+
+    return {
+      data: {
+        ...input.data,
+        error_handled: true,
+        handler_message: message,
+        original_error: errorData,
+        handledAt: Date.now(),
+      },
+    };
+  },
+};

package/src/workflows/nodes/error/fallback.ts

@@ -0,0 +1,47 @@
+import type { NodeDefinition } from '../registry.ts';
+
+export const fallbackNode: NodeDefinition = {
+  type: 'error.fallback',
+  label: 'Fallback',
+  description: 'Provide a static fallback value when an upstream node fails.',
+  category: 'error',
+  icon: '🪂',
+  color: '#ef4444',
+  configSchema: {
+    fallback_value: {
+      type: 'json',
+      label: 'Fallback Value',
+      description: 'JSON value to merge into the data output when this node is reached via an error path.',
+      required: true,
+      default: { fallback: true },
+    },
+  },
+  inputs: ['default'],
+  outputs: ['default'],
+  execute: async (input, config, ctx) => {
+    ctx.logger.info('Fallback node triggered — injecting fallback value');
+
+    let fallbackValue: unknown = config.fallback_value;
+    if (typeof fallbackValue === 'string') {
+      try {
+        fallbackValue = JSON.parse(fallbackValue);
+      } catch {
+        // keep as string
+      }
+    }
+
+    const fallbackData: Record<string, unknown> =
+      fallbackValue !== null && typeof fallbackValue === 'object' && !Array.isArray(fallbackValue)
+        ? (fallbackValue as Record<string, unknown>)
+        : { fallback_value: fallbackValue };
+
+    return {
+      data: {
+        ...input.data,
+        ...fallbackData,
+        _fallback_used: true,
+        fallbackAt: Date.now(),
+      },
+    };
+  },
+};

package/src/workflows/nodes/error/retry.ts

@@ -0,0 +1,82 @@
+import type { NodeDefinition } from '../registry.ts';
+
+export const retryNode: NodeDefinition = {
+  type: 'error.retry',
+  label: 'Retry',
+  description: 'Automatically retry a failed upstream node with configurable backoff.',
+  category: 'error',
+  icon: '🔁',
+  color: '#ef4444',
+  configSchema: {
+    max_retries: {
+      type: 'number',
+      label: 'Max Retries',
+      description: 'Maximum number of retry attempts.',
+      required: true,
+      default: 3,
+    },
+    delay_ms: {
+      type: 'number',
+      label: 'Initial Delay (ms)',
+      description: 'Delay before the first retry. Subsequent delays increase with backoff.',
+      required: true,
+      default: 1000,
+    },
+    backoff: {
+      type: 'select',
+      label: 'Backoff Strategy',
+      description: 'How the delay grows between retry attempts.',
+      required: true,
+      default: 'exponential',
+      options: [
+        { label: 'Fixed', value: 'fixed' },
+        { label: 'Exponential', value: 'exponential' },
+      ],
+    },
+  },
+  inputs: ['default'],
+  outputs: ['default', 'failed'],
+  execute: async (input, config, ctx) => {
+    const maxRetries = typeof config.max_retries === 'number' ? config.max_retries : 3;
+    const delayMs = typeof config.delay_ms === 'number' ? config.delay_ms : 1000;
+    const backoff = String(config.backoff ?? 'exponential');
+
+    // The retry logic is orchestrated by the workflow executor using the node's RetryPolicy.
+    // This execute function is called on each attempt — it passes data through and records attempt info.
+    const currentAttempt = typeof input.data['_retry_attempt'] === 'number'
+      ? (input.data['_retry_attempt'] as number)
+      : 0;
+
+    ctx.logger.info(`Retry node: attempt ${currentAttempt + 1}/${maxRetries + 1}`);
+
+    const hasError = Boolean(input.data['_error'] || input.data['error']);
+
+    if (hasError && currentAttempt >= maxRetries) {
+      ctx.logger.warn(`Retry exhausted after ${maxRetries} attempts`);
+      return {
+        data: {
+          ...input.data,
+          retry_exhausted: true,
+          retry_attempts: currentAttempt,
+          max_retries: maxRetries,
+        },
+        route: 'failed',
+      };
+    }
+
+    const nextDelay = backoff === 'exponential'
+      ? delayMs * Math.pow(2, currentAttempt)
+      : delayMs;
+
+    return {
+      data: {
+        ...input.data,
+        _retry_attempt: currentAttempt + 1,
+        retry_delay_ms: nextDelay,
+        max_retries: maxRetries,
+        backoff,
+      },
+      route: 'default',
+    };
+  },
+};

package/src/workflows/nodes/logic/delay.ts

@@ -0,0 +1,42 @@
+import type { NodeDefinition } from '../registry.ts';
+
+export const delayNode: NodeDefinition = {
+  type: 'logic.delay',
+  label: 'Delay',
+  description: 'Pause workflow execution for a specified duration.',
+  category: 'logic',
+  icon: '⏳',
+  color: '#f59e0b',
+  configSchema: {
+    delay_ms: {
+      type: 'number',
+      label: 'Delay (ms)',
+      description: 'Number of milliseconds to wait before continuing.',
+      required: true,
+      default: 1000,
+    },
+  },
+  inputs: ['default'],
+  outputs: ['default'],
+  execute: async (input, config, ctx) => {
+    const delayMs = typeof config.delay_ms === 'number' ? Math.max(0, config.delay_ms) : 1000;
+    ctx.logger.info(`Delaying for ${delayMs}ms`);
+
+    await new Promise<void>((resolve, reject) => {
+      if (ctx.abortSignal.aborted) { reject(new Error('Delay aborted')); return; }
+      const onAbort = () => { clearTimeout(timer); reject(new Error('Delay aborted')); };
+      const timer = setTimeout(() => {
+        ctx.abortSignal.removeEventListener('abort', onAbort);
+        resolve();
+      }, delayMs);
+      ctx.abortSignal.addEventListener('abort', onAbort, { once: true });
+    });
+
+    return {
+      data: {
+        ...input.data,
+        delayed_ms: delayMs,
+      },
+    };
+  },
+};

package/src/workflows/nodes/logic/if-else.ts

@@ -0,0 +1,41 @@
+import type { NodeDefinition } from '../registry.ts';
+import { safeEvaluateExpression } from '../../safe-eval.ts';
+
+export const ifElseNode: NodeDefinition = {
+  type: 'logic.if_else',
+  label: 'If / Else',
+  description: 'Branch the workflow based on a JavaScript boolean expression.',
+  category: 'logic',
+  icon: '🔀',
+  color: '#f59e0b',
+  configSchema: {
+    condition: {
+      type: 'template',
+      label: 'Condition',
+      description: 'A JavaScript expression that evaluates to true or false. Has access to `data` (input data object).',
+      required: true,
+      placeholder: 'data.status === "ok" && data.count > 0',
+    },
+  },
+  inputs: ['default'],
+  outputs: ['true', 'false'],
+  execute: async (input, config, ctx) => {
+    const condition = String(config.condition ?? 'false');
+    ctx.logger.info(`Evaluating condition: ${condition.slice(0, 120)}`);
+
+    let result = false;
+    try {
+      result = !!safeEvaluateExpression(condition, { data: input.data, variables: input.variables });
+    } catch (err) {
+      ctx.logger.warn(`Condition evaluation error: ${err instanceof Error ? err.message : String(err)}`);
+      result = false;
+    }
+
+    ctx.logger.info(`Condition result: ${result}`);
+
+    return {
+      data: { ...input.data, condition_result: result },
+      route: result ? 'true' : 'false',
+    };
+  },
+};

package/src/workflows/nodes/logic/loop.ts

@@ -0,0 +1,90 @@
+import type { NodeDefinition } from '../registry.ts';
+
+export const loopNode: NodeDefinition = {
+  type: 'logic.loop',
+  label: 'Loop',
+  description: 'Iterate over an array, executing downstream "item" nodes for each element, then emitting "done".',
+  category: 'logic',
+  icon: '🔁',
+  color: '#f59e0b',
+  configSchema: {
+    items_path: {
+      type: 'template',
+      label: 'Items Path / Expression',
+      description: 'A template expression that resolves to an array, e.g. "{{data.results}}".',
+      required: true,
+      placeholder: '{{data.items}}',
+    },
+    max_iterations: {
+      type: 'number',
+      label: 'Max Iterations',
+      description: 'Safety cap on the number of iterations.',
+      required: false,
+      default: 100,
+    },
+  },
+  inputs: ['default'],
+  outputs: ['item', 'done'],
+  execute: async (input, config, ctx) => {
+    const maxIterations = typeof config.max_iterations === 'number' ? config.max_iterations : 100;
+
+    // Resolve items from config (template engine resolves upstream)
+    let items: unknown[] = [];
+    const rawItems = config.items_path;
+    if (Array.isArray(rawItems)) {
+      items = rawItems;
+    } else if (typeof rawItems === 'string') {
+      // Try dot-path into input.data
+      const resolved = rawItems.split('.').reduce<unknown>((acc, key) => {
+        if (acc && typeof acc === 'object') return (acc as Record<string, unknown>)[key];
+        return undefined;
+      }, input.data as unknown);
+      if (Array.isArray(resolved)) items = resolved;
+    }
+
+    const capped = items.slice(0, maxIterations);
+    if (items.length > maxIterations) {
+      ctx.logger.warn(`Loop capped at ${maxIterations} iterations (total items: ${items.length})`);
+    }
+
+    if (capped.length === 0) {
+      ctx.logger.info('Loop: no items to iterate');
+      return {
+        data: {
+          ...input.data,
+          loop_items: [],
+          loop_results: [],
+          loop_total: 0,
+        },
+        route: 'done',
+      };
+    }
+
+    ctx.logger.info(`Loop: iterating over ${capped.length} items`);
+
+    // Execute downstream "item" path for each element by collecting results.
+    // Since individual node execute() can't drive the graph executor,
+    // we emit each item's data with index metadata. The executor's routing
+    // sends this to the "item" output branch.
+    // For true per-item subgraph execution, we'd need executor-level loop support.
+    // Current approach: output all items with metadata so downstream nodes can process.
+    const results: unknown[] = [];
+    for (let i = 0; i < capped.length; i++) {
+      if (ctx.abortSignal.aborted) break;
+      const item = capped[i];
+      results.push(item);
+    }
+
+    return {
+      data: {
+        ...input.data,
+        loop_items: capped,
+        loop_results: results,
+        loop_total: capped.length,
+        loop_index: 0,
+        loop_current: capped[0],
+      },
+      route: 'item',
+    };
+  },
+};

package/src/workflows/nodes/logic/merge.ts

@@ -0,0 +1,38 @@
+import type { NodeDefinition } from '../registry.ts';
+
+export const mergeNode: NodeDefinition = {
+  type: 'logic.merge',
+  label: 'Merge',
+  description: 'Wait for two input branches and merge their data into one output.',
+  category: 'logic',
+  icon: '🔗',
+  color: '#f59e0b',
+  configSchema: {},
+  inputs: ['input_1', 'input_2'],
+  outputs: ['default'],
+  execute: async (input, _config, ctx) => {
+    ctx.logger.info('Merging inputs');
+
+    // The executor collects data from all incoming edges via Object.assign.
+    // We deep-merge by ensuring nested objects don't clobber each other.
+    const merged: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(input.data)) {
+      if (
+        key in merged &&
+        merged[key] && typeof merged[key] === 'object' && !Array.isArray(merged[key]) &&
+        value && typeof value === 'object' && !Array.isArray(value)
+      ) {
+        merged[key] = { ...(merged[key] as Record<string, unknown>), ...(value as Record<string, unknown>) };
+      } else {
+        merged[key] = value;
+      }
+    }
+
+    merged.merged_at = Date.now();
+    merged.merge_source_count = Object.keys(input.data).length;
+
+    return {
+      data: merged,
+    };
+  },
+};

package/src/workflows/nodes/logic/race.ts

@@ -0,0 +1,40 @@
+import type { NodeDefinition } from '../registry.ts';
+
+export const raceNode: NodeDefinition = {
+  type: 'logic.race',
+  label: 'Race',
+  description: 'Pass through whichever input branch arrives first; tag the winner with timing metadata.',
+  category: 'logic',
+  icon: '🏁',
+  color: '#f59e0b',
+  configSchema: {
+    timeout_ms: {
+      type: 'number',
+      label: 'Timeout (ms)',
+      description: 'If no branch completes within this time, the node fails.',
+      required: true,
+      default: 30000,
+    },
+  },
+  inputs: ['default'],
+  outputs: ['winner'],
+  execute: async (input, config, ctx) => {
+    const timeoutMs = typeof config.timeout_ms === 'number' ? config.timeout_ms : 30000;
+    const arrivedAt = Date.now();
+
+    ctx.logger.info(`Race node: input arrived (timeout was ${timeoutMs}ms)`);
+
+    // In graph execution, all inputs to this node are collected by the executor.
+    // The race semantics mean the first completed branch's data is what we receive.
+    // We tag the output with timing metadata.
+    return {
+      data: {
+        ...input.data,
+        race_winner: true,
+        race_arrived_at: arrivedAt,
+        race_timeout_ms: timeoutMs,
+      },
+      route: 'winner',
+    };
+  },
+};

package/src/workflows/nodes/logic/switch.ts

@@ -0,0 +1,59 @@
+import type { NodeDefinition } from '../registry.ts';
+import { safeEvaluateExpression } from '../../safe-eval.ts';
+
+export const switchNode: NodeDefinition = {
+  type: 'logic.switch',
+  label: 'Switch',
+  description: 'Route to one of multiple cases based on an expression value.',
+  category: 'logic',
+  icon: '🔃',
+  color: '#f59e0b',
+  configSchema: {
+    expression: {
+      type: 'template',
+      label: 'Expression',
+      description: 'JavaScript expression whose value is matched against cases. Has access to `data`.',
+      required: true,
+      placeholder: 'data.status',
+    },
+    cases: {
+      type: 'json',
+      label: 'Cases',
+      description: 'JSON array of string values to match, e.g. ["pending", "active", "done"]. Matched in order against case_0, case_1, ... case_N.',
+      required: true,
+      default: ['case_a', 'case_b', 'case_c'],
+    },
+  },
+  inputs: ['default'],
+  outputs: ['case_0', 'case_1', 'case_2', 'default'],
+  execute: async (input, config, ctx) => {
+    const expression = String(config.expression ?? '');
+
+    let exprValue: unknown;
+    try {
+      exprValue = safeEvaluateExpression(expression, { data: input.data, variables: input.variables });
+    } catch (err) {
+      ctx.logger.warn(`Switch expression evaluation error: ${err instanceof Error ? err.message : String(err)}`);
+      exprValue = undefined;
+    }
+
+    // Parse cases
+    let cases: unknown[] = [];
+    if (Array.isArray(config.cases)) {
+      cases = config.cases;
+    } else if (typeof config.cases === 'string') {
+      try { cases = JSON.parse(config.cases); } catch { cases = []; }
+    }
+
+    // Match against any number of cases (not limited to 3)
+    const matchIndex = cases.findIndex(c => String(c) === String(exprValue));
+    const route = matchIndex >= 0 ? `case_${matchIndex}` : 'default';
+
+    ctx.logger.info(`Switch: expression="${exprValue}", matched case ${matchIndex}, route="${route}"`);
+
+    return {
+      data: { ...input.data, switch_value: exprValue, switch_route: route },
+      route,
+    };
+  },
+};

package/src/workflows/nodes/logic/template-render.ts

@@ -0,0 +1,53 @@
+import type { NodeDefinition } from '../registry.ts';
+import { resolveTemplateString } from '../../template.ts';
+
+export const templateRenderNode: NodeDefinition = {
+  type: 'logic.template_render',
+  label: 'Template Render',
+  description: 'Render a template string against current data and store the result.',
+  category: 'logic',
+  icon: '📄',
+  color: '#f59e0b',
+  configSchema: {
+    template: {
+      type: 'template',
+      label: 'Template',
+      description: 'Template string with {{...}} expressions to resolve.',
+      required: true,
+      placeholder: 'Hello {{data.name}}, you have {{data.count}} items.',
+    },
+  },
+  inputs: ['default'],
+  outputs: ['default'],
+  execute: async (input, config, ctx) => {
+    const template = String(config.template ?? '');
+    ctx.logger.info(`Rendering template (${template.length} chars)`);
+
+    // Build nodeOutputs from input data so $node["..."] references work
+    const nodeOutputs = new Map<string, Record<string, unknown>>();
+    // Populate with input.data entries that look like node outputs
+    for (const [key, value] of Object.entries(input.data)) {
+      if (value && typeof value === 'object' && !Array.isArray(value)) {
+        nodeOutputs.set(key, value as Record<string, unknown>);
+      }
+    }
+
+    const templateCtx = {
+      variables: input.variables,
+      nodeOutputs,
+      triggerData: (input.data['$trigger'] as Record<string, unknown>) ?? input.data,
+      env: Object.fromEntries(
+        Object.entries(process.env).filter(([, v]) => v !== undefined) as [string, string][]
+      ),
+    };
+
+    const rendered = resolveTemplateString(template, templateCtx);
+
+    return {
+      data: {
+        ...input.data,
+        rendered_output: rendered,
+      },
+    };
+  },
+};