@usejarvis/brain 0.1.0

package/src/workflows/executor.ts

@@ -0,0 +1,207 @@
+/**
+ * Graph Executor — topological sort, parallel branches, retry, fallback, self-heal
+ */
+
+import type { WorkflowDefinition, WorkflowNode, WorkflowSettings, RetryPolicy } from './types.ts';
+import type { NodeRegistry, NodeInput, NodeOutput, ExecutionContext } from './nodes/registry.ts';
+import { resolveAllTemplates, type TemplateContext } from './template.ts';
+
+/**
+ * Topological sort of workflow nodes, grouped by execution level.
+ * Nodes at the same level can be executed in parallel.
+ * Returns string[][] where each inner array is a set of node IDs to execute concurrently.
+ */
+export function topologicalSort(definition: WorkflowDefinition): string[][] {
+  const { nodes, edges } = definition;
+  const nodeIds = new Set(nodes.map(n => n.id));
+
+  // Build adjacency list and in-degree map
+  const inDegree = new Map<string, number>();
+  const adjacency = new Map<string, string[]>();
+
+  for (const id of nodeIds) {
+    inDegree.set(id, 0);
+    adjacency.set(id, []);
+  }
+
+  for (const edge of edges) {
+    if (nodeIds.has(edge.source) && nodeIds.has(edge.target)) {
+      adjacency.get(edge.source)!.push(edge.target);
+      inDegree.set(edge.target, (inDegree.get(edge.target) ?? 0) + 1);
+    }
+  }
+
+  // Kahn's algorithm, grouping by level
+  const levels: string[][] = [];
+  let queue = [...nodeIds].filter(id => inDegree.get(id) === 0);
+
+  while (queue.length > 0) {
+    levels.push([...queue]);
+    const nextQueue: string[] = [];
+
+    for (const nodeId of queue) {
+      for (const neighbor of adjacency.get(nodeId) ?? []) {
+        const newDegree = (inDegree.get(neighbor) ?? 1) - 1;
+        inDegree.set(neighbor, newDegree);
+        if (newDegree === 0) {
+          nextQueue.push(neighbor);
+        }
+      }
+    }
+
+    queue = nextQueue;
+  }
+
+  return levels;
+}
+
+/**
+ * Get the outgoing edges from a node, optionally filtered by source handle.
+ */
+export function getOutgoingEdges(
+  definition: WorkflowDefinition,
+  nodeId: string,
+  route?: string,
+): string[] {
+  return definition.edges
+    .filter(e => {
+      if (e.source !== nodeId) return false;
+      if (route !== undefined && e.sourceHandle && e.sourceHandle !== route) return false;
+      return true;
+    })
+    .map(e => e.target);
+}
+
+/**
+ * Execute a single node with retry and fallback.
+ */
+export async function executeNode(
+  node: WorkflowNode,
+  input: NodeInput,
+  nodeRegistry: NodeRegistry,
+  ctx: ExecutionContext,
+  templateCtx: TemplateContext,
+  settings: WorkflowSettings,
+): Promise<NodeOutput> {
+  const nodeDef = nodeRegistry.get(node.type);
+  if (!nodeDef) {
+    throw new Error(`Unknown node type: ${node.type}`);
+  }
+
+  // Resolve template expressions in node config
+  const resolvedConfig = resolveAllTemplates(node.config, templateCtx);
+
+  const retryPolicy: RetryPolicy = node.retryPolicy ?? {
+    maxRetries: settings.maxRetries,
+    delayMs: settings.retryDelayMs,
+    backoff: 'fixed',
+  };
+
+  let lastError: Error | null = null;
+
+  for (let attempt = 0; attempt <= retryPolicy.maxRetries; attempt++) {
+    if (ctx.abortSignal.aborted) {
+      throw new Error('Execution cancelled');
+    }
+
+    try {
+      // Enforce node-level timeout from workflow settings
+      const nodeTimeout = settings.timeoutMs ?? 300_000;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const output = await Promise.race([
+        nodeDef.execute(input, resolvedConfig, ctx),
+        new Promise<never>((_, reject) => {
+          timer = setTimeout(
+            () => reject(new Error(`Node '${node.label}' timed out after ${nodeTimeout}ms`)),
+            nodeTimeout,
+          );
+        }),
+      ]);
+      clearTimeout(timer);
+      return output;
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      ctx.logger.warn(`Node ${node.label} attempt ${attempt + 1} failed: ${lastError.message}`);
+
+      if (attempt < retryPolicy.maxRetries) {
+        const delay = retryPolicy.backoff === 'exponential'
+          ? retryPolicy.delayMs * Math.pow(2, attempt)
+          : retryPolicy.delayMs;
+        await sleep(delay, ctx.abortSignal);
+      }
+    }
+  }
+
+  // Self-heal: if onError is self_heal and we have an LLM manager, ask AI for fix
+  if (settings.onError === 'self_heal' && ctx.llmManager && lastError) {
+    try {
+      ctx.logger.info(`Node ${node.label}: attempting self-heal...`);
+      const healed = await selfHeal(node, lastError, resolvedConfig, input, ctx);
+      if (healed) return healed;
+    } catch (healErr) {
+      ctx.logger.warn(`Self-heal failed for ${node.label}: ${healErr instanceof Error ? healErr.message : healErr}`);
+    }
+  }
+
+  throw lastError ?? new Error(`Node ${node.label} failed after ${retryPolicy.maxRetries + 1} attempts`);
+}
+
+/**
+ * Self-heal: ask the LLM to diagnose the failure and provide corrected config.
+ * If the LLM provides a corrected config, retry the node once with the new config.
+ */
+async function selfHeal(
+  node: WorkflowNode,
+  error: Error,
+  config: Record<string, unknown>,
+  input: NodeInput,
+  ctx: ExecutionContext,
+): Promise<NodeOutput | null> {
+  const llm = ctx.llmManager as any;
+  if (!llm?.chat) return null;
+
+  const diagnosticPrompt = [
+    {
+      role: 'system' as const,
+      content: `You are a workflow debugger. A workflow node failed. Analyze the error and provide a corrected config that might fix it. Respond with ONLY a JSON object: { "fix": "explanation", "correctedConfig": { ... } }. If you cannot fix it, respond with { "fix": null }.`,
+    },
+    {
+      role: 'user' as const,
+      content: `Node: ${node.type} (${node.label})\nConfig: ${JSON.stringify(config)}\nInput data: ${JSON.stringify(input.data).slice(0, 1000)}\nError: ${error.message}\n\nWhat config change would fix this?`,
+    },
+  ];
+
+  const response = await llm.chat(diagnosticPrompt, { temperature: 0.1, max_tokens: 1000 });
+
+  try {
+    const text = response.content;
+    const jsonStart = text.indexOf('{');
+    const jsonEnd = text.lastIndexOf('}');
+    if (jsonStart < 0 || jsonEnd <= jsonStart) return null;
+
+    const parsed = JSON.parse(text.slice(jsonStart, jsonEnd + 1));
+    if (!parsed.fix || !parsed.correctedConfig) return null;
+
+    ctx.logger.info(`Self-heal applying fix: ${parsed.fix}`);
+
+    // Re-execute with corrected config
+    const nodeDef = ctx.nodeRegistry?.get(node.type);
+    if (!nodeDef) return null;
+
+    return await nodeDef.execute(input, parsed.correctedConfig, ctx);
+  } catch (parseErr) {
+    ctx.logger.warn(`Self-heal parse/execution failed: ${parseErr instanceof Error ? parseErr.message : parseErr}`);
+    return null;
+  }
+}
+
+/**
+ * Sleep with abort support.
+ */
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) { reject(new Error('Aborted')); return; }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener('abort', () => { clearTimeout(timer); reject(new Error('Aborted')); }, { once: true });
+  });
+}

package/src/workflows/nl-builder.ts

@@ -0,0 +1,198 @@
+/**
+ * NL Workflow Builder — Conversational workflow construction via LLM
+ *
+ * Parses natural language descriptions into WorkflowDefinition objects,
+ * modifies existing workflows via NL instructions, and supports
+ * conversational building with context.
+ */
+
+import type { WorkflowDefinition, WorkflowNode, WorkflowEdge } from './types.ts';
+import type { NodeRegistry } from './nodes/registry.ts';
+import * as vault from '../vault/workflows.ts';
+
+type ChatMessage = { role: 'user' | 'assistant'; content: string };
+
+export class NLWorkflowBuilder {
+  private nodeRegistry: NodeRegistry;
+  private llmManager: any; // LLMManager
+
+  constructor(nodeRegistry: NodeRegistry, llmManager: unknown) {
+    this.nodeRegistry = nodeRegistry;
+    this.llmManager = llmManager;
+  }
+
+  /**
+   * Parse a natural language description into a full WorkflowDefinition.
+   */
+  async parseDescription(text: string): Promise<WorkflowDefinition> {
+    const catalog = this.buildCatalogPrompt();
+    const prompt = [
+      { role: 'system' as const, content: this.buildSystemPrompt(catalog) },
+      { role: 'user' as const, content: `Create a workflow from this description:\n\n${text}\n\nRespond with ONLY valid JSON matching the WorkflowDefinition schema. No explanation.` },
+    ];
+
+    const response = await this.llmManager.chat(prompt, {
+      temperature: 0.2,
+      max_tokens: 4000,
+    });
+
+    return this.parseDefinitionResponse(response.content);
+  }
+
+  /**
+   * Modify an existing workflow definition via NL instruction.
+   */
+  async modifyWorkflow(
+    definition: WorkflowDefinition,
+    instruction: string,
+  ): Promise<{ definition: WorkflowDefinition; changes: string[] }> {
+    const catalog = this.buildCatalogPrompt();
+    const prompt = [
+      { role: 'system' as const, content: this.buildSystemPrompt(catalog) },
+      {
+        role: 'user' as const,
+        content: `Here is the current workflow definition:\n\`\`\`json\n${JSON.stringify(definition, null, 2)}\n\`\`\`\n\nModify it according to this instruction: ${instruction}\n\nRespond with JSON: { "definition": <updated WorkflowDefinition>, "changes": ["list of changes made"] }`,
+      },
+    ];
+
+    const response = await this.llmManager.chat(prompt, {
+      temperature: 0.2,
+      max_tokens: 6000,
+    });
+
+    const parsed = JSON.parse(this.extractJson(response.content));
+    return {
+      definition: this.validateDefinition(parsed.definition),
+      changes: parsed.changes ?? [],
+    };
+  }
+
+  /**
+   * Conversational workflow building — chat with history.
+   */
+  async chat(
+    workflowId: string,
+    message: string,
+    history: ChatMessage[],
+  ): Promise<{ reply: string; updated: boolean }> {
+    const catalog = this.buildCatalogPrompt();
+    const latestVersion = vault.getLatestVersion(workflowId);
+    const currentDef = latestVersion?.definition;
+
+    const messages = [
+      {
+        role: 'system' as const,
+        content: this.buildSystemPrompt(catalog) +
+          (currentDef
+            ? `\n\nCurrent workflow definition:\n\`\`\`json\n${JSON.stringify(currentDef, null, 2)}\n\`\`\``
+            : '\n\nNo workflow definition exists yet.') +
+          `\n\nYou are helping the user build/modify their workflow via chat. If the user asks to add, remove, or modify nodes/edges, output the FULL updated definition in a JSON code block. If they're asking a question, just answer it. Always explain what you changed.`,
+      },
+      ...history.map(m => ({ role: m.role as 'user' | 'assistant', content: m.content })),
+      { role: 'user' as const, content: message },
+    ];
+
+    const response = await this.llmManager.chat(messages, {
+      temperature: 0.3,
+      max_tokens: 4000,
+    });
+
+    const text = response.content;
+
+    // Check if response contains a definition update
+    const jsonMatch = text.match(/```json\s*([\s\S]*?)```/);
+    if (jsonMatch) {
+      try {
+        const newDef = this.validateDefinition(JSON.parse(jsonMatch[1]));
+        // Save as new version
+        vault.createVersion(workflowId, newDef, 'NL chat update');
+        return { reply: text.replace(/```json[\s\S]*?```/, '*(definition updated)*'), updated: true };
+      } catch {
+        // JSON parse failed — treat as conversational
+      }
+    }
+
+    return { reply: text, updated: false };
+  }
+
+  // ── Private helpers ──
+
+  private buildSystemPrompt(catalog: string): string {
+    return `You are a workflow builder AI. You create and modify workflow definitions for an automation system.
+
+Available node types:
+${catalog}
+
+A WorkflowDefinition has this structure:
+{
+  "nodes": [{ "id": string, "type": string, "label": string, "position": { "x": number, "y": number }, "config": {} }],
+  "edges": [{ "id": string, "source": string, "target": string, "sourceHandle?": string, "label?": string }],
+  "settings": { "maxRetries": 3, "retryDelayMs": 5000, "timeoutMs": 300000, "parallelism": "parallel"|"sequential", "onError": "stop"|"continue"|"self_heal" }
+}
+
+Rules:
+- Every workflow must have at least one trigger node
+- Node IDs should be descriptive (e.g., "trigger-cron-1", "action-email-1")
+- Position nodes left-to-right, top-to-bottom, with ~200px spacing
+- Connect nodes with edges from source to target
+- Use "sourceHandle" for branching nodes (if-else: "true"/"false", switch: "case_0"/"case_1"/etc.)
+- Config fields must match the node's configSchema`;
+  }
+
+  private buildCatalogPrompt(): string {
+    const nodes = this.nodeRegistry.list();
+    return nodes.map(n =>
+      `- ${n.type} (${n.category}): ${n.description} | config: ${Object.keys(n.configSchema).join(', ') || 'none'}`
+    ).join('\n');
+  }
+
+  private extractJson(text: string): string {
+    // Try to extract from code block
+    const codeBlock = text.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (codeBlock) return codeBlock[1]!.trim();
+    // Try raw JSON
+    const start = text.indexOf('{');
+    const end = text.lastIndexOf('}');
+    if (start >= 0 && end > start) return text.slice(start, end + 1);
+    throw new Error('No JSON found in response');
+  }
+
+  private parseDefinitionResponse(text: string): WorkflowDefinition {
+    const json = this.extractJson(text);
+    const parsed = JSON.parse(json);
+    return this.validateDefinition(parsed);
+  }
+
+  private validateDefinition(def: any): WorkflowDefinition {
+    if (!def.nodes || !Array.isArray(def.nodes)) throw new Error('Missing nodes array');
+    if (!def.edges || !Array.isArray(def.edges)) throw new Error('Missing edges array');
+
+    const nodes: WorkflowNode[] = def.nodes.map((n: any, i: number) => ({
+      id: n.id ?? `node-${i}`,
+      type: n.type ?? 'action.send_message',
+      label: n.label ?? n.type ?? `Node ${i}`,
+      position: n.position ?? { x: 100 + i * 200, y: 200 },
+      config: n.config ?? {},
+    }));
+
+    const edges: WorkflowEdge[] = (def.edges ?? []).map((e: any, i: number) => ({
+      id: e.id ?? `edge-${i}`,
+      source: e.source,
+      target: e.target,
+      sourceHandle: e.sourceHandle,
+      label: e.label,
+    }));
+
+    return {
+      nodes,
+      edges,
+      settings: {
+        maxRetries: def.settings?.maxRetries ?? 3,
+        retryDelayMs: def.settings?.retryDelayMs ?? 5000,
+        timeoutMs: def.settings?.timeoutMs ?? 300000,
+        parallelism: def.settings?.parallelism ?? 'parallel',
+        onError: def.settings?.onError ?? 'stop',
+      },
+    };
+  }
+}

package/src/workflows/nodes/actions/agent-task.ts

@@ -0,0 +1,73 @@
+import type { NodeDefinition } from '../registry.ts';
+
+export const agentTaskAction: NodeDefinition = {
+  type: 'action.agent_task',
+  label: 'Agent Task',
+  description: 'Dispatch a task to a sub-agent and await its response.',
+  category: 'action',
+  icon: '🤖',
+  color: '#3b82f6',
+  configSchema: {
+    task: {
+      type: 'template',
+      label: 'Task',
+      description: 'The task description to send to the sub-agent. Supports template expressions.',
+      required: true,
+      placeholder: 'Summarize the following: {{data.content}}',
+    },
+    max_iterations: {
+      type: 'number',
+      label: 'Max Iterations',
+      description: 'Maximum tool-loop iterations the sub-agent may run.',
+      required: false,
+      default: 100,
+    },
+  },
+  inputs: ['default'],
+  outputs: ['default'],
+  execute: async (input, config, ctx) => {
+    const task = String(config.task ?? '');
+    const maxIterations = typeof config.max_iterations === 'number' ? config.max_iterations : 100;
+
+    ctx.logger.info(`Dispatching agent task (max ${maxIterations} iterations): ${task.slice(0, 120)}`);
+
+    const llm = ctx.llmManager as any;
+    if (!llm?.chat) {
+      throw new Error('LLM manager not available — cannot dispatch agent task');
+    }
+
+    // Build context from input data
+    const dataContext = JSON.stringify(input.data).slice(0, 2000);
+    const messages = [
+      {
+        role: 'system' as const,
+        content: `You are a workflow sub-agent. Complete the following task concisely. You have access to the following context data:\n\n${dataContext}\n\nRespond with the task result only.`,
+      },
+      {
+        role: 'user' as const,
+        content: task,
+      },
+    ];
+
+    const llmResponse = await llm.chat(messages, {
+      temperature: 0.3,
+      max_tokens: 2000,
+    });
+
+    const response = typeof llmResponse.content === 'string'
+      ? llmResponse.content
+      : JSON.stringify(llmResponse.content);
+
+    ctx.logger.info(`Agent task completed (${response.length} chars)`);
+
+    return {
+      data: {
+        ...input.data,
+        task,
+        response,
+        success: true,
+        max_iterations: maxIterations,
+      },
+    };
+  },
+};

package/src/workflows/nodes/actions/calendar-action.ts

@@ -0,0 +1,85 @@
+import type { NodeDefinition } from '../registry.ts';
+
+export const calendarActionNode: NodeDefinition = {
+  type: 'action.calendar_action',
+  label: 'Calendar Action',
+  description: 'Create, update, or delete a Google Calendar event.',
+  category: 'action',
+  icon: '📆',
+  color: '#3b82f6',
+  configSchema: {
+    action: {
+      type: 'select',
+      label: 'Action',
+      description: 'Operation to perform on the calendar.',
+      required: true,
+      default: 'create',
+      options: [
+        { label: 'Create', value: 'create' },
+        { label: 'Update', value: 'update' },
+        { label: 'Delete', value: 'delete' },
+      ],
+    },
+    title: {
+      type: 'template',
+      label: 'Title',
+      description: 'Event title. Supports template expressions.',
+      required: true,
+      placeholder: 'Team standup',
+    },
+    start: {
+      type: 'template',
+      label: 'Start Time',
+      description: 'ISO 8601 start datetime. Supports template expressions.',
+      required: true,
+      placeholder: '2026-03-02T09:00:00Z',
+    },
+    end: {
+      type: 'template',
+      label: 'End Time',
+      description: 'ISO 8601 end datetime. Supports template expressions.',
+      required: true,
+      placeholder: '2026-03-02T09:30:00Z',
+    },
+  },
+  inputs: ['default'],
+  outputs: ['default'],
+  execute: async (input, config, ctx) => {
+    const action = String(config.action ?? 'create');
+    const title = String(config.title ?? '');
+    const start = String(config.start ?? '');
+    const end = String(config.end ?? '');
+
+    ctx.logger.info(`Calendar action: ${action} event "${title}" from ${start} to ${end}`);
+
+    let success = false;
+    let note = '';
+
+    // Try the google_calendar tool if registered
+    const toolName = 'google_calendar';
+    if (ctx.toolRegistry.has(toolName)) {
+      try {
+        await ctx.toolRegistry.execute(toolName, { action, title, start, end });
+        success = true;
+      } catch (err) {
+        throw new Error(`Calendar ${action} failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    } else {
+      note = 'Google Calendar tool not configured — set up Google API integration to enable calendar actions';
+      ctx.logger.warn(note);
+    }
+
+    return {
+      data: {
+        ...input.data,
+        calendar_action: action,
+        title,
+        start,
+        end,
+        success,
+        note: note || undefined,
+        executedAt: Date.now(),
+      },
+    };
+  },
+};

package/src/workflows/nodes/actions/code-execution.ts

@@ -0,0 +1,73 @@
+import type { NodeDefinition } from '../registry.ts';
+import { safeExecuteCode } from '../../safe-eval.ts';
+
+export const codeExecutionAction: NodeDefinition = {
+  type: 'action.code_execution',
+  label: 'Code Execution',
+  description: 'Execute a JavaScript or TypeScript snippet inline.',
+  category: 'action',
+  icon: '⚡',
+  color: '#3b82f6',
+  configSchema: {
+    code: {
+      type: 'code',
+      label: 'Code',
+      description: 'JavaScript/TypeScript code to execute. Has access to `input` (NodeInput data) and `ctx` (minimal context).',
+      required: true,
+      placeholder: '// Return a value from this function\nreturn { result: input.data.value * 2 };',
+    },
+    language: {
+      type: 'select',
+      label: 'Language',
+      description: 'Code language. TypeScript is transpiled to JS before execution.',
+      required: true,
+      default: 'javascript',
+      options: [
+        { label: 'JavaScript', value: 'javascript' },
+        { label: 'TypeScript', value: 'typescript' },
+      ],
+    },
+    timeout_ms: {
+      type: 'number',
+      label: 'Timeout (ms)',
+      description: 'Maximum execution time before the code is killed.',
+      required: false,
+      default: 10000,
+    },
+  },
+  inputs: ['default'],
+  outputs: ['default'],
+  execute: async (input, config, ctx) => {
+    const code = String(config.code ?? '');
+    if (!code) throw new Error('code is required');
+    const language = String(config.language ?? 'javascript');
+    const timeoutMs = typeof config.timeout_ms === 'number' ? config.timeout_ms : 10_000;
+
+    ctx.logger.info(`Executing ${language} snippet (${code.length} chars)`);
+
+    // Minimal safe context exposed to user code
+    const safeCtx = {
+      log: (msg: string) => ctx.logger.info(`[code] ${msg}`),
+      warn: (msg: string) => ctx.logger.warn(`[code] ${msg}`),
+      variables: input.variables,
+      executionId: input.executionId,
+    };
+
+    let result: unknown;
+    try {
+      result = await safeExecuteCode(code, input, safeCtx, timeoutMs);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      ctx.logger.error(`Code execution failed: ${message}`);
+      throw new Error(`Code execution failed: ${message}`);
+    }
+
+    return {
+      data: {
+        ...input.data,
+        code_result: result,
+        language,
+      },
+    };
+  },
+};