@nordsym/apiclaw 1.3.13 → 1.4.0

package/convex/chains.ts

@@ -0,0 +1,1095 @@
+import { v } from "convex/values";
+import { mutation, query, action, internalMutation, internalAction } from "./_generated/server";
+import { internal, api } from "./_generated/api";
+import { Id, Doc } from "./_generated/dataModel";
+
+// ============================================
+// TYPES
+// ============================================
+
+type ChainStatus = "pending" | "running" | "completed" | "failed" | "paused";
+type StepStatus = "pending" | "running" | "completed" | "failed" | "skipped";
+
+interface ChainStep {
+  id: string;
+  provider: string;
+  action: string;
+  params: Record<string, unknown>;
+  // Execution modifiers
+  onError?: {
+    retry?: { attempts: number; backoff?: number[] };
+    fallback?: ChainStep;
+    abort?: boolean;
+  };
+  // Parallel execution
+  parallel?: ChainStep[];
+}
+
+interface ChainError {
+  stepId: string;
+  code: string;
+  message: string;
+  retryAfter?: number;
+}
+
+// ============================================
+// HELPER: Generate resume token
+// ============================================
+
+function generateResumeToken(chainId: string, stepIndex: number): string {
+  const random = Math.random().toString(36).substring(2, 8);
+  return `chain_${chainId.slice(-8)}_step_${stepIndex}_${random}`;
+}
+
+// ============================================
+// MUTATIONS
+// ============================================
+
+/**
+ * Create a new chain execution record (internal)
+ * Validates chain structure and initializes execution state
+ */
+export const createChainInternal = internalMutation({
+  args: {
+    workspaceId: v.id("workspaces"),
+    steps: v.array(v.any()),
+    continueOnError: v.optional(v.boolean()),
+    timeout: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+
+    // Validate steps have required fields
+    for (let i = 0; i < args.steps.length; i++) {
+      const step = args.steps[i] as ChainStep;
+      
+      // Check for parallel steps
+      if (step.parallel) {
+        for (const pStep of step.parallel) {
+          if (!pStep.id || !pStep.provider || !pStep.action) {
+            throw new Error(`Parallel step at index ${i} missing required fields (id, provider, action)`);
+          }
+        }
+      } else if (!step.id || !step.provider || !step.action) {
+        throw new Error(`Step at index ${i} missing required fields (id, provider, action)`);
+      }
+    }
+
+    // Create chain record
+    const chainId = await ctx.db.insert("chains", {
+      workspaceId: args.workspaceId,
+      steps: args.steps,
+      status: "pending",
+      currentStep: 0,
+      results: {},
+      continueOnError: args.continueOnError ?? false,
+      timeout: args.timeout,
+      totalCostCents: 0,
+      totalLatencyMs: 0,
+      createdAt: now,
+    });
+
+    // Create execution records for each step
+    for (let i = 0; i < args.steps.length; i++) {
+      const step = args.steps[i] as ChainStep;
+      
+      if (step.parallel) {
+        // Create execution records for parallel steps
+        const parallelGroup = `parallel_${i}_${Date.now()}`;
+        for (const pStep of step.parallel) {
+          await ctx.db.insert("chainExecutions", {
+            chainId,
+            stepId: pStep.id,
+            stepIndex: i,
+            status: "pending",
+            parallelGroup,
+            createdAt: now,
+          });
+        }
+      } else {
+        await ctx.db.insert("chainExecutions", {
+          chainId,
+          stepId: step.id,
+          stepIndex: i,
+          status: "pending",
+          createdAt: now,
+        });
+      }
+    }
+
+    return chainId;
+  },
+});
+
+/**
+ * Create a new chain execution record (public API)
+ */
+export const createChain = mutation({
+  args: {
+    workspaceId: v.id("workspaces"),
+    steps: v.array(v.any()),
+    continueOnError: v.optional(v.boolean()),
+    timeout: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+
+    // Validate steps have required fields
+    for (let i = 0; i < args.steps.length; i++) {
+      const step = args.steps[i] as ChainStep;
+      
+      // Check for parallel steps
+      if (step.parallel) {
+        for (const pStep of step.parallel) {
+          if (!pStep.id || !pStep.provider || !pStep.action) {
+            throw new Error(`Parallel step at index ${i} missing required fields (id, provider, action)`);
+          }
+        }
+      } else if (!step.id || !step.provider || !step.action) {
+        throw new Error(`Step at index ${i} missing required fields (id, provider, action)`);
+      }
+    }
+
+    // Create chain record
+    const chainId = await ctx.db.insert("chains", {
+      workspaceId: args.workspaceId,
+      steps: args.steps,
+      status: "pending",
+      currentStep: 0,
+      results: {},
+      continueOnError: args.continueOnError ?? false,
+      timeout: args.timeout,
+      totalCostCents: 0,
+      totalLatencyMs: 0,
+      createdAt: now,
+    });
+
+    // Create execution records for each step
+    for (let i = 0; i < args.steps.length; i++) {
+      const step = args.steps[i] as ChainStep;
+      
+      if (step.parallel) {
+        const parallelGroup = `parallel_${i}_${Date.now()}`;
+        for (const pStep of step.parallel) {
+          await ctx.db.insert("chainExecutions", {
+            chainId,
+            stepId: pStep.id,
+            stepIndex: i,
+            status: "pending",
+            parallelGroup,
+            createdAt: now,
+          });
+        }
+      } else {
+        await ctx.db.insert("chainExecutions", {
+          chainId,
+          stepId: step.id,
+          stepIndex: i,
+          status: "pending",
+          createdAt: now,
+        });
+      }
+    }
+
+    return chainId;
+  },
+});
+
+/**
+ * Create chain from template
+ */
+export const createChainFromTemplate = mutation({
+  args: {
+    workspaceId: v.id("workspaces"),
+    templateName: v.string(),
+    inputs: v.optional(v.any()),
+  },
+  handler: async (ctx, args) => {
+    // Get template
+    const template = await ctx.db
+      .query("chainTemplates")
+      .withIndex("by_name", (q) => 
+        q.eq("workspaceId", args.workspaceId).eq("name", args.templateName)
+      )
+      .first();
+
+    if (!template) {
+      throw new Error(`Template '${args.templateName}' not found`);
+    }
+
+    const now = Date.now();
+
+    // Create chain from template
+    const chainId = await ctx.db.insert("chains", {
+      workspaceId: args.workspaceId,
+      steps: template.chain,
+      status: "pending",
+      currentStep: 0,
+      results: {},
+      totalCostCents: 0,
+      totalLatencyMs: 0,
+      createdAt: now,
+    });
+
+    // Create execution records
+    for (let i = 0; i < template.chain.length; i++) {
+      const step = template.chain[i] as ChainStep;
+      
+      if (step.parallel) {
+        const parallelGroup = `parallel_${i}_${Date.now()}`;
+        for (const pStep of step.parallel) {
+          await ctx.db.insert("chainExecutions", {
+            chainId,
+            stepId: pStep.id,
+            stepIndex: i,
+            status: "pending",
+            parallelGroup,
+            createdAt: now,
+          });
+        }
+      } else {
+        await ctx.db.insert("chainExecutions", {
+          chainId,
+          stepId: step.id,
+          stepIndex: i,
+          status: "pending",
+          createdAt: now,
+        });
+      }
+    }
+
+    // Increment template use count
+    await ctx.db.patch(template._id, {
+      useCount: (template.useCount || 0) + 1,
+      lastUsedAt: now,
+    });
+
+    return chainId;
+  },
+});
+
+/**
+ * Execute a single step and store the result
+ * Called by the orchestrator action
+ */
+export const executeStep = internalMutation({
+  args: {
+    chainId: v.id("chains"),
+    stepId: v.string(),
+    stepIndex: v.number(),
+    input: v.any(),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+
+    // Get execution record
+    const execution = await ctx.db
+      .query("chainExecutions")
+      .withIndex("by_chainId_stepId", (q) => 
+        q.eq("chainId", args.chainId).eq("stepId", args.stepId)
+      )
+      .first();
+
+    if (!execution) {
+      throw new Error(`No execution record found for step ${args.stepId}`);
+    }
+
+    // Mark as running
+    await ctx.db.patch(execution._id, {
+      status: "running",
+      input: args.input,
+      startedAt: now,
+    });
+
+    // Update chain status
+    const chain = await ctx.db.get(args.chainId);
+    if (chain && chain.status === "pending") {
+      await ctx.db.patch(args.chainId, {
+        status: "running",
+        startedAt: now,
+      });
+    }
+
+    return execution._id;
+  },
+});
+
+/**
+ * Record step completion with result
+ */
+export const completeStep = internalMutation({
+  args: {
+    chainId: v.id("chains"),
+    stepId: v.string(),
+    output: v.any(),
+    latencyMs: v.number(),
+    costCents: v.number(),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+
+    // Get execution record
+    const execution = await ctx.db
+      .query("chainExecutions")
+      .withIndex("by_chainId_stepId", (q) => 
+        q.eq("chainId", args.chainId).eq("stepId", args.stepId)
+      )
+      .first();
+
+    if (!execution) {
+      throw new Error(`No execution record found for step ${args.stepId}`);
+    }
+
+    // Mark as completed
+    await ctx.db.patch(execution._id, {
+      status: "completed",
+      output: args.output,
+      latencyMs: args.latencyMs,
+      costCents: args.costCents,
+      completedAt: now,
+    });
+
+    // Update chain results
+    const chain = await ctx.db.get(args.chainId);
+    if (chain) {
+      const results = { ...(chain.results || {}), [args.stepId]: args.output };
+      const totalCost = (chain.totalCostCents || 0) + args.costCents;
+      const totalLatency = (chain.totalLatencyMs || 0) + args.latencyMs;
+
+      await ctx.db.patch(args.chainId, {
+        results,
+        totalCostCents: totalCost,
+        totalLatencyMs: totalLatency,
+      });
+    }
+
+    return { success: true };
+  },
+});
+
+/**
+ * Advance chain to next step or parallel batch
+ */
+export const advanceChain = internalMutation({
+  args: {
+    chainId: v.id("chains"),
+  },
+  handler: async (ctx, args) => {
+    const chain = await ctx.db.get(args.chainId);
+    if (!chain) {
+      throw new Error("Chain not found");
+    }
+
+    const nextStep = chain.currentStep + 1;
+
+    // Check if chain is complete
+    if (nextStep >= chain.steps.length) {
+      return { complete: true, nextStep: null };
+    }
+
+    // Update current step
+    await ctx.db.patch(args.chainId, {
+      currentStep: nextStep,
+    });
+
+    // Generate resume token for this position
+    const resumeToken = generateResumeToken(args.chainId, nextStep);
+    await ctx.db.patch(args.chainId, {
+      resumeToken,
+      canResume: true,
+    });
+
+    return { 
+      complete: false, 
+      nextStep,
+      nextStepDef: chain.steps[nextStep],
+    };
+  },
+});
+
+/**
+ * Handle chain failure
+ * Stores partial results and generates resume token
+ */
+export const failChain = internalMutation({
+  args: {
+    chainId: v.id("chains"),
+    stepId: v.string(),
+    error: v.object({
+      code: v.string(),
+      message: v.string(),
+      retryAfter: v.optional(v.number()),
+    }),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+
+    // Update execution record
+    const execution = await ctx.db
+      .query("chainExecutions")
+      .withIndex("by_chainId_stepId", (q) => 
+        q.eq("chainId", args.chainId).eq("stepId", args.stepId)
+      )
+      .first();
+
+    if (execution) {
+      await ctx.db.patch(execution._id, {
+        status: "failed",
+        error: {
+          code: args.error.code,
+          message: args.error.message,
+        },
+        completedAt: now,
+      });
+    }
+
+    // Get chain to determine resume position
+    const chain = await ctx.db.get(args.chainId);
+    if (!chain) {
+      throw new Error("Chain not found");
+    }
+
+    // Generate resume token
+    const resumeToken = generateResumeToken(args.chainId, chain.currentStep);
+
+    // Update chain status
+    await ctx.db.patch(args.chainId, {
+      status: "failed",
+      error: {
+        stepId: args.stepId,
+        ...args.error,
+      },
+      resumeToken,
+      canResume: true,
+      completedAt: now,
+    });
+
+    return {
+      resumeToken,
+      partialResults: chain.results,
+    };
+  },
+});
+
+/**
+ * Resume chain from failed step (public mutation)
+ */
+export const resumeChain = mutation({
+  args: {
+    resumeToken: v.string(),
+    overrides: v.optional(v.any()), // Optional param overrides per step
+  },
+  handler: async (ctx, args) => {
+    // Find chain by resume token
+    const chain = await ctx.db
+      .query("chains")
+      .withIndex("by_resumeToken", (q) => q.eq("resumeToken", args.resumeToken))
+      .first();
+
+    if (!chain) {
+      throw new Error("Invalid or expired resume token");
+    }
+
+    if (!chain.canResume) {
+      throw new Error("Chain cannot be resumed");
+    }
+
+    // Reset failed step to pending
+    const executions = await ctx.db
+      .query("chainExecutions")
+      .withIndex("by_chainId_stepIndex", (q) => 
+        q.eq("chainId", chain._id).eq("stepIndex", chain.currentStep)
+      )
+      .collect();
+
+    for (const exec of executions) {
+      if (exec.status === "failed") {
+        await ctx.db.patch(exec._id, {
+          status: "pending",
+          error: undefined,
+          startedAt: undefined,
+          completedAt: undefined,
+        });
+      }
+    }
+
+    // Update chain status
+    await ctx.db.patch(chain._id, {
+      status: "pending",
+      error: undefined,
+      resumeToken: undefined,
+      canResume: false,
+    });
+
+    return {
+      chainId: chain._id,
+      resumeFromStep: chain.currentStep,
+      steps: chain.steps,
+      results: chain.results,
+      overrides: args.overrides,
+    };
+  },
+});
+
+/**
+ * Mark chain as completed
+ */
+export const completeChain = internalMutation({
+  args: {
+    chainId: v.id("chains"),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const chain = await ctx.db.get(args.chainId);
+
+    if (!chain) {
+      throw new Error("Chain not found");
+    }
+
+    await ctx.db.patch(args.chainId, {
+      status: "completed",
+      canResume: false,
+      resumeToken: undefined,
+      completedAt: now,
+    });
+
+    return {
+      success: true,
+      results: chain.results,
+      totalCostCents: chain.totalCostCents,
+      totalLatencyMs: chain.totalLatencyMs,
+    };
+  },
+});
+
+/**
+ * Pause chain execution (for long-running chains)
+ */
+export const pauseChain = mutation({
+  args: {
+    chainId: v.id("chains"),
+  },
+  handler: async (ctx, args) => {
+    const chain = await ctx.db.get(args.chainId);
+    if (!chain) {
+      throw new Error("Chain not found");
+    }
+
+    if (chain.status !== "running") {
+      throw new Error("Can only pause running chains");
+    }
+
+    const resumeToken = generateResumeToken(args.chainId, chain.currentStep);
+
+    await ctx.db.patch(args.chainId, {
+      status: "paused",
+      resumeToken,
+      canResume: true,
+    });
+
+    return { resumeToken };
+  },
+});
+
+// ============================================
+// CHAIN TEMPLATE MUTATIONS
+// ============================================
+
+/**
+ * Create or update a chain template
+ */
+export const saveChainTemplate = mutation({
+  args: {
+    id: v.optional(v.id("chainTemplates")),
+    workspaceId: v.id("workspaces"),
+    name: v.string(),
+    description: v.optional(v.string()),
+    inputs: v.optional(v.any()),
+    chain: v.array(v.any()),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+
+    if (args.id) {
+      // Update existing
+      await ctx.db.patch(args.id, {
+        name: args.name,
+        description: args.description,
+        inputs: args.inputs,
+        chain: args.chain,
+        updatedAt: now,
+      });
+      return args.id;
+    }
+
+    // Create new
+    return await ctx.db.insert("chainTemplates", {
+      workspaceId: args.workspaceId,
+      name: args.name,
+      description: args.description,
+      inputs: args.inputs,
+      chain: args.chain,
+      useCount: 0,
+      createdAt: now,
+      updatedAt: now,
+    });
+  },
+});
+
+/**
+ * Delete a chain template
+ */
+export const deleteChainTemplate = mutation({
+  args: {
+    id: v.id("chainTemplates"),
+  },
+  handler: async (ctx, args) => {
+    await ctx.db.delete(args.id);
+    return { success: true };
+  },
+});
+
+// ============================================
+// QUERIES
+// ============================================
+
+/**
+ * Get chain status and results
+ */
+export const getChain = query({
+  args: {
+    chainId: v.id("chains"),
+  },
+  handler: async (ctx, args) => {
+    const chain = await ctx.db.get(args.chainId);
+    if (!chain) {
+      return null;
+    }
+
+    return {
+      id: chain._id,
+      status: chain.status,
+      currentStep: chain.currentStep,
+      totalSteps: chain.steps.length,
+      results: chain.results,
+      error: chain.error,
+      canResume: chain.canResume,
+      resumeToken: chain.resumeToken,
+      totalCostCents: chain.totalCostCents,
+      totalLatencyMs: chain.totalLatencyMs,
+      createdAt: chain.createdAt,
+      startedAt: chain.startedAt,
+      completedAt: chain.completedAt,
+    };
+  },
+});
+
+/**
+ * Get full execution trace for dashboard
+ */
+export const getChainTrace = query({
+  args: {
+    chainId: v.id("chains"),
+  },
+  handler: async (ctx, args) => {
+    const chain = await ctx.db.get(args.chainId);
+    if (!chain) {
+      return null;
+    }
+
+    // Get all step executions
+    const executions = await ctx.db
+      .query("chainExecutions")
+      .withIndex("by_chainId", (q) => q.eq("chainId", args.chainId))
+      .collect();
+
+    // Sort by stepIndex
+    executions.sort((a, b) => a.stepIndex - b.stepIndex);
+
+    // Build trace
+    const trace = executions.map((exec) => ({
+      stepId: exec.stepId,
+      stepIndex: exec.stepIndex,
+      status: exec.status,
+      parallelGroup: exec.parallelGroup,
+      input: exec.input,
+      output: exec.output,
+      latencyMs: exec.latencyMs,
+      costCents: exec.costCents,
+      error: exec.error,
+      startedAt: exec.startedAt,
+      completedAt: exec.completedAt,
+    }));
+
+    // Calculate tokens saved (estimate: ~400 tokens per avoided round-trip)
+    const completedSteps = executions.filter((e) => e.status === "completed");
+    const tokensSaved = completedSteps.length > 1 ? (completedSteps.length - 1) * 400 : 0;
+
+    return {
+      chainId: chain._id,
+      workspaceId: chain.workspaceId,
+      status: chain.status,
+      steps: chain.steps,
+      currentStep: chain.currentStep,
+      results: chain.results,
+      error: chain.error,
+      trace,
+      totalCostCents: chain.totalCostCents,
+      totalLatencyMs: chain.totalLatencyMs,
+      tokensSaved,
+      canResume: chain.canResume,
+      resumeToken: chain.resumeToken,
+      createdAt: chain.createdAt,
+      startedAt: chain.startedAt,
+      completedAt: chain.completedAt,
+    };
+  },
+});
+
+/**
+ * List chains for a workspace
+ */
+export const listChains = query({
+  args: {
+    workspaceId: v.id("workspaces"),
+    status: v.optional(v.string()),
+    limit: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const limit = args.limit ?? 50;
+
+    let chainsQuery = ctx.db
+      .query("chains")
+      .withIndex("by_workspaceId", (q) => q.eq("workspaceId", args.workspaceId))
+      .order("desc");
+
+    const chains = await chainsQuery.take(limit);
+
+    // Filter by status if provided
+    let filtered = chains;
+    if (args.status && args.status !== "all") {
+      filtered = chains.filter((c) => c.status === args.status);
+    }
+
+    return filtered.map((chain) => ({
+      id: chain._id,
+      status: chain.status,
+      stepsCount: chain.steps.length,
+      currentStep: chain.currentStep,
+      totalCostCents: chain.totalCostCents,
+      totalLatencyMs: chain.totalLatencyMs,
+      error: chain.error,
+      canResume: chain.canResume,
+      createdAt: chain.createdAt,
+      completedAt: chain.completedAt,
+    }));
+  },
+});
+
+/**
+ * List chain templates for a workspace
+ */
+export const listChainTemplates = query({
+  args: {
+    workspaceId: v.id("workspaces"),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("chainTemplates")
+      .withIndex("by_workspaceId", (q) => q.eq("workspaceId", args.workspaceId))
+      .collect();
+  },
+});
+
+/**
+ * Get chain template by name
+ */
+export const getChainTemplate = query({
+  args: {
+    workspaceId: v.id("workspaces"),
+    name: v.string(),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("chainTemplates")
+      .withIndex("by_name", (q) => 
+        q.eq("workspaceId", args.workspaceId).eq("name", args.name)
+      )
+      .first();
+  },
+});
+
+/**
+ * Get chain statistics for workspace
+ */
+export const getChainStats = query({
+  args: {
+    workspaceId: v.id("workspaces"),
+  },
+  handler: async (ctx, args) => {
+    const chains = await ctx.db
+      .query("chains")
+      .withIndex("by_workspaceId", (q) => q.eq("workspaceId", args.workspaceId))
+      .collect();
+
+    const total = chains.length;
+    const completed = chains.filter((c) => c.status === "completed").length;
+    const failed = chains.filter((c) => c.status === "failed").length;
+    const running = chains.filter((c) => c.status === "running").length;
+    const paused = chains.filter((c) => c.status === "paused").length;
+
+    const totalCostCents = chains.reduce((acc, c) => acc + (c.totalCostCents || 0), 0);
+    const totalLatencyMs = chains.reduce((acc, c) => acc + (c.totalLatencyMs || 0), 0);
+
+    // Count total steps across all chains
+    const allExecutions = await Promise.all(
+      chains.map((c) =>
+        ctx.db
+          .query("chainExecutions")
+          .withIndex("by_chainId", (q) => q.eq("chainId", c._id))
+          .collect()
+      )
+    );
+    const totalSteps = allExecutions.flat().length;
+
+    return {
+      total,
+      completed,
+      failed,
+      running,
+      paused,
+      totalCostCents,
+      totalLatencyMs,
+      totalSteps,
+      successRate: total > 0 ? Math.round((completed / total) * 100) : 0,
+    };
+  },
+});
+
+// ============================================
+// ACTIONS (Orchestration Logic)
+// ============================================
+
+/**
+ * Main chain orchestrator
+ * Validates chain → executes steps sequentially/parallel → handles errors
+ */
+export const runChain = action({
+  args: {
+    workspaceId: v.id("workspaces"),
+    steps: v.array(v.any()),
+    continueOnError: v.optional(v.boolean()),
+    timeout: v.optional(v.number()),
+  },
+  handler: async (ctx, args): Promise<{
+    success: boolean;
+    chainId: Id<"chains">;
+    results?: Record<string, unknown>;
+    completedSteps?: string[];
+    failedStep?: { id: string; error: string; code: string };
+    partialResults?: Record<string, unknown>;
+    canResume?: boolean;
+    resumeToken?: string;
+    totalCostCents?: number;
+    totalLatencyMs?: number;
+  }> => {
+    const startTime = Date.now();
+    const timeout = args.timeout || 30000; // Default 30s
+
+    // 1. Create chain record
+    const chainId = await ctx.runMutation(internal.chains.createChainInternal, {
+      workspaceId: args.workspaceId,
+      steps: args.steps,
+      continueOnError: args.continueOnError,
+      timeout: args.timeout,
+    });
+
+    const completedSteps: string[] = [];
+    let currentResults: Record<string, unknown> = {};
+
+    try {
+      // 2. Execute steps
+      for (let i = 0; i < args.steps.length; i++) {
+        // Check timeout
+        if (Date.now() - startTime > timeout) {
+          throw new Error("TIMEOUT: Chain execution exceeded timeout");
+        }
+
+        const step = args.steps[i] as ChainStep;
+
+        // Handle parallel steps
+        if (step.parallel && step.parallel.length > 0) {
+          const parallelResults = await ctx.runAction(internal.chains.runParallelSteps, {
+            chainId,
+            steps: step.parallel,
+            stepIndex: i,
+          });
+
+          // Merge parallel results
+          for (const [stepId, result] of Object.entries(parallelResults)) {
+            currentResults[stepId] = result;
+            completedSteps.push(stepId);
+          }
+        } else {
+          // Sequential step
+          await ctx.runMutation(internal.chains.executeStep, {
+            chainId,
+            stepId: step.id,
+            stepIndex: i,
+            input: step.params,
+          });
+
+          // Execute the actual API call (placeholder - in production calls Direct Call)
+          const stepStartTime = Date.now();
+          const result = await executeProviderCall(ctx, step);
+          const latencyMs = Date.now() - stepStartTime;
+
+          await ctx.runMutation(internal.chains.completeStep, {
+            chainId,
+            stepId: step.id,
+            output: result,
+            latencyMs,
+            costCents: result.costCents || 0,
+          });
+
+          currentResults[step.id] = result;
+          completedSteps.push(step.id);
+        }
+
+        // Advance to next step
+        await ctx.runMutation(internal.chains.advanceChain, { chainId });
+      }
+
+      // 3. Complete chain
+      const finalResult = await ctx.runMutation(internal.chains.completeChain, { chainId });
+
+      return {
+        success: true,
+        chainId,
+        results: currentResults,
+        completedSteps,
+        totalCostCents: finalResult.totalCostCents,
+        totalLatencyMs: finalResult.totalLatencyMs,
+      };
+
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      const errorCode = errorMessage.startsWith("TIMEOUT") ? "TIMEOUT" : "EXECUTION_ERROR";
+      
+      // Find current step
+      const currentStep = args.steps[completedSteps.length] as ChainStep | undefined;
+      const failedStepId = currentStep?.id || "unknown";
+
+      // Handle failure
+      const failureResult = await ctx.runMutation(internal.chains.failChain, {
+        chainId,
+        stepId: failedStepId,
+        error: {
+          code: errorCode,
+          message: errorMessage,
+        },
+      });
+
+      return {
+        success: false,
+        chainId,
+        completedSteps,
+        failedStep: {
+          id: failedStepId,
+          error: errorMessage,
+          code: errorCode,
+        },
+        partialResults: failureResult.partialResults,
+        canResume: true,
+        resumeToken: failureResult.resumeToken,
+      };
+    }
+  },
+});
+
+/**
+ * Execute parallel steps concurrently
+ */
+export const runParallelSteps = internalAction({
+  args: {
+    chainId: v.id("chains"),
+    steps: v.array(v.any()),
+    stepIndex: v.number(),
+  },
+  handler: async (ctx, args): Promise<Record<string, unknown>> => {
+    const results: Record<string, unknown> = {};
+
+    // Mark all steps as running
+    for (const step of args.steps as ChainStep[]) {
+      await ctx.runMutation(internal.chains.executeStep, {
+        chainId: args.chainId,
+        stepId: step.id,
+        stepIndex: args.stepIndex,
+        input: step.params,
+      });
+    }
+
+    // Execute all in parallel
+    const promises = (args.steps as ChainStep[]).map(async (step) => {
+      const startTime = Date.now();
+      
+      try {
+        const result = await executeProviderCall(ctx, step);
+        const latencyMs = Date.now() - startTime;
+
+        await ctx.runMutation(internal.chains.completeStep, {
+          chainId: args.chainId,
+          stepId: step.id,
+          output: result,
+          latencyMs,
+          costCents: result.costCents || 0,
+        });
+
+        return { stepId: step.id, result };
+      } catch (error) {
+        throw new Error(`Step ${step.id} failed: ${error instanceof Error ? error.message : "Unknown"}`);
+      }
+    });
+
+    const settledResults = await Promise.all(promises);
+
+    for (const { stepId, result } of settledResults) {
+      results[stepId] = result;
+    }
+
+    return results;
+  },
+});
+
+// ============================================
+// HELPER: Execute provider call
+// Placeholder - in production, this calls the Direct Call API
+// ============================================
+
+async function executeProviderCall(
+  ctx: any, 
+  step: ChainStep
+): Promise<{ success: boolean; data?: unknown; costCents?: number }> {
+  // For MVP/testing, return mock success
+  // In production, this would:
+  // 1. Look up the provider's Direct Call config
+  // 2. Find the action definition
+  // 3. Execute the HTTP request with params
+  // 4. Return the mapped result
+  
+  // Simulate some latency
+  await new Promise((resolve) => setTimeout(resolve, 50 + Math.random() * 100));
+  
+  return {
+    success: true,
+    data: {
+      stepId: step.id,
+      provider: step.provider,
+      action: step.action,
+      params: step.params,
+      mockResult: `Executed ${step.action} on ${step.provider}`,
+      timestamp: Date.now(),
+    },
+    costCents: Math.ceil(Math.random() * 5), // Mock 1-5 cents cost
+  };
+}