@nordsym/apiclaw 1.4.0 → 1.4.2

package/convex/chains.ts

@@ -1,7 +1,7 @@
 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";
+import { internal } from "./_generated/api";
+import { Id } from "./_generated/dataModel";
 
 // ============================================
 // TYPES
@@ -15,13 +15,11 @@ interface ChainStep {
   provider: string;
   action: string;
   params: Record<string, unknown>;
-  // Execution modifiers
   onError?: {
     retry?: { attempts: number; backoff?: number[] };
     fallback?: ChainStep;
     abort?: boolean;
   };
-  // Parallel execution
   parallel?: ChainStep[];
 }
 
@@ -41,13 +39,255 @@ function generateResumeToken(chainId: string, stepIndex: number): string {
   return `chain_${chainId.slice(-8)}_step_${stepIndex}_${random}`;
 }
 
+// ============================================
+// DASHBOARD QUERIES (for workspace chains page)
+// ============================================
+
+/**
+ * Get chain executions for a workspace (authenticated via session token)
+ */
+export const getChainExecutions = query({
+  args: {
+    token: v.string(),
+    limit: v.optional(v.number()),
+    status: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    // Validate session
+    const session = await ctx.db
+      .query("agentSessions")
+      .withIndex("by_sessionToken", (q) => q.eq("sessionToken", args.token))
+      .first();
+
+    if (!session) {
+      return { error: "Invalid session" };
+    }
+
+    // Get chains for workspace
+    const allChains = await ctx.db
+      .query("chains")
+      .withIndex("by_workspaceId", (q) => q.eq("workspaceId", session.workspaceId))
+      .order("desc")
+      .collect();
+    
+    // Filter by status if provided
+    let filteredChains = allChains;
+    if (args.status && args.status !== "all") {
+      filteredChains = allChains.filter((c) => c.status === args.status);
+    }
+
+    // Apply limit
+    const limit = args.limit || 50;
+    const chains = filteredChains.slice(0, limit);
+
+    // For each chain, get step count from chainExecutions
+    const chainsWithStepCount = await Promise.all(
+      chains.map(async (chain) => {
+        const steps = await ctx.db
+          .query("chainExecutions")
+          .withIndex("by_chainId", (q) => q.eq("chainId", chain._id))
+          .collect();
+
+        return {
+          _id: chain._id,
+          status: chain.status,
+          currentStep: chain.currentStep,
+          stepsCount: steps.length || chain.steps?.length || 0,
+          totalCostCents: chain.totalCostCents || 0,
+          totalLatencyMs: chain.totalLatencyMs || 0,
+          error: chain.error,
+          canResume: chain.canResume,
+          resumeToken: chain.resumeToken,
+          createdAt: chain.createdAt,
+          startedAt: chain.startedAt,
+          completedAt: chain.completedAt,
+        };
+      })
+    );
+
+    return chainsWithStepCount;
+  },
+});
+
+/**
+ * Get full trace for a single chain (authenticated via session token)
+ */
+export const getChainTraceAuth = query({
+  args: {
+    token: v.string(),
+    chainId: v.id("chains"),
+  },
+  handler: async (ctx, args) => {
+    // Validate session
+    const session = await ctx.db
+      .query("agentSessions")
+      .withIndex("by_sessionToken", (q) => q.eq("sessionToken", args.token))
+      .first();
+
+    if (!session) {
+      return { error: "Invalid session" };
+    }
+
+    // Get the chain
+    const chain = await ctx.db.get(args.chainId);
+    if (!chain || chain.workspaceId !== session.workspaceId) {
+      return { error: "Chain not found" };
+    }
+
+    // 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);
+
+    // Calculate total tokens saved (estimate: ~400 tokens per step avoided)
+    const completedSteps = executions.filter((e) => e.status === "completed");
+    const tokensSaved = completedSteps.length > 1 ? (completedSteps.length - 1) * 400 : 0;
+
+    return {
+      chain: {
+        _id: chain._id,
+        status: chain.status,
+        currentStep: chain.currentStep,
+        steps: chain.steps,
+        results: chain.results,
+        error: chain.error,
+        continueOnError: chain.continueOnError,
+        timeout: chain.timeout,
+        canResume: chain.canResume,
+        resumeToken: chain.resumeToken,
+        totalCostCents: chain.totalCostCents || 0,
+        totalLatencyMs: chain.totalLatencyMs || 0,
+        createdAt: chain.createdAt,
+        startedAt: chain.startedAt,
+        completedAt: chain.completedAt,
+      },
+      executions: executions.map((e) => ({
+        _id: e._id,
+        stepId: e.stepId,
+        stepIndex: e.stepIndex,
+        status: e.status,
+        input: e.input,
+        output: e.output,
+        latencyMs: e.latencyMs,
+        costCents: e.costCents,
+        error: e.error,
+        parallelGroup: e.parallelGroup,
+        createdAt: e.createdAt,
+        startedAt: e.startedAt,
+        completedAt: e.completedAt,
+      })),
+      tokensSaved,
+    };
+  },
+});
+
+/**
+ * Resume a failed/paused chain (authenticated via session token)
+ */
+export const resumeChainAuth = mutation({
+  args: {
+    token: v.string(),
+    chainId: v.id("chains"),
+    overrides: v.optional(v.any()),
+  },
+  handler: async (ctx, args) => {
+    // Validate session
+    const session = await ctx.db
+      .query("agentSessions")
+      .withIndex("by_sessionToken", (q) => q.eq("sessionToken", args.token))
+      .first();
+
+    if (!session) {
+      return { error: "Invalid session" };
+    }
+
+    // Get the chain
+    const chain = await ctx.db.get(args.chainId);
+    if (!chain || chain.workspaceId !== session.workspaceId) {
+      return { error: "Chain not found" };
+    }
+
+    if (!chain.canResume) {
+      return { error: "Chain cannot be resumed" };
+    }
+
+    // Update chain status to pending (orchestrator will pick it up)
+    await ctx.db.patch(args.chainId, {
+      status: "pending",
+      error: undefined,
+    });
+
+    return { success: true, chainId: args.chainId };
+  },
+});
+
+/**
+ * Get chain statistics for workspace (authenticated via session token)
+ */
+export const getChainStatsAuth = query({
+  args: {
+    token: v.string(),
+  },
+  handler: async (ctx, args) => {
+    // Validate session
+    const session = await ctx.db
+      .query("agentSessions")
+      .withIndex("by_sessionToken", (q) => q.eq("sessionToken", args.token))
+      .first();
+
+    if (!session) {
+      return { error: "Invalid session" };
+    }
+
+    const chains = await ctx.db
+      .query("chains")
+      .withIndex("by_workspaceId", (q) => q.eq("workspaceId", session.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,
+    };
+  },
+});
+
 // ============================================
 // MUTATIONS
 // ============================================
 
 /**
  * Create a new chain execution record (internal)
- * Validates chain structure and initializes execution state
  */
 export const createChainInternal = internalMutation({
   args: {
@@ -63,7 +303,6 @@ export const createChainInternal = internalMutation({
     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) {
@@ -94,7 +333,6 @@ export const createChainInternal = internalMutation({
       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", {
@@ -134,11 +372,10 @@ export const createChain = mutation({
   handler: async (ctx, args) => {
     const now = Date.now();
 
-    // Validate steps have required fields
+    // Validate steps
     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) {
@@ -150,7 +387,6 @@ export const createChain = mutation({
       }
     }
 
-    // Create chain record
     const chainId = await ctx.db.insert("chains", {
       workspaceId: args.workspaceId,
       steps: args.steps,
@@ -164,7 +400,7 @@ export const createChain = mutation({
       createdAt: now,
     });
 
-    // Create execution records for each step
+    // Create execution records
     for (let i = 0; i < args.steps.length; i++) {
       const step = args.steps[i] as ChainStep;
       
@@ -205,7 +441,6 @@ export const createChainFromTemplate = mutation({
     inputs: v.optional(v.any()),
   },
   handler: async (ctx, args) => {
-    // Get template
     const template = await ctx.db
       .query("chainTemplates")
       .withIndex("by_name", (q) => 
@@ -219,7 +454,6 @@ export const createChainFromTemplate = mutation({
 
     const now = Date.now();
 
-    // Create chain from template
     const chainId = await ctx.db.insert("chains", {
       workspaceId: args.workspaceId,
       steps: template.chain,
@@ -231,7 +465,6 @@ export const createChainFromTemplate = mutation({
       createdAt: now,
     });
 
-    // Create execution records
     for (let i = 0; i < template.chain.length; i++) {
       const step = template.chain[i] as ChainStep;
       
@@ -258,7 +491,6 @@ export const createChainFromTemplate = mutation({
       }
     }
 
-    // Increment template use count
     await ctx.db.patch(template._id, {
       useCount: (template.useCount || 0) + 1,
       lastUsedAt: now,
@@ -270,7 +502,6 @@ export const createChainFromTemplate = mutation({
 
 /**
  * Execute a single step and store the result
- * Called by the orchestrator action
  */
 export const executeStep = internalMutation({
   args: {
@@ -282,7 +513,6 @@ export const executeStep = internalMutation({
   handler: async (ctx, args) => {
     const now = Date.now();
 
-    // Get execution record
     const execution = await ctx.db
       .query("chainExecutions")
       .withIndex("by_chainId_stepId", (q) => 
@@ -294,14 +524,12 @@ export const executeStep = internalMutation({
       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, {
@@ -328,7 +556,6 @@ export const completeStep = internalMutation({
   handler: async (ctx, args) => {
     const now = Date.now();
 
-    // Get execution record
     const execution = await ctx.db
       .query("chainExecutions")
       .withIndex("by_chainId_stepId", (q) => 
@@ -340,7 +567,6 @@ export const completeStep = internalMutation({
       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,
@@ -349,7 +575,6 @@ export const completeStep = internalMutation({
       completedAt: now,
     });
 
-    // Update chain results
     const chain = await ctx.db.get(args.chainId);
     if (chain) {
       const results = { ...(chain.results || {}), [args.stepId]: args.output };
@@ -368,7 +593,7 @@ export const completeStep = internalMutation({
 });
 
 /**
- * Advance chain to next step or parallel batch
+ * Advance chain to next step
  */
 export const advanceChain = internalMutation({
   args: {
@@ -382,17 +607,14 @@ export const advanceChain = internalMutation({
 
     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,
@@ -409,7 +631,6 @@ export const advanceChain = internalMutation({
 
 /**
  * Handle chain failure
- * Stores partial results and generates resume token
  */
 export const failChain = internalMutation({
   args: {
@@ -424,7 +645,6 @@ export const failChain = internalMutation({
   handler: async (ctx, args) => {
     const now = Date.now();
 
-    // Update execution record
     const execution = await ctx.db
       .query("chainExecutions")
       .withIndex("by_chainId_stepId", (q) => 
@@ -443,16 +663,13 @@ export const failChain = internalMutation({
       });
     }
 
-    // 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: {
@@ -477,10 +694,9 @@ export const failChain = internalMutation({
 export const resumeChain = mutation({
   args: {
     resumeToken: v.string(),
-    overrides: v.optional(v.any()), // Optional param overrides per step
+    overrides: v.optional(v.any()),
   },
   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))
@@ -494,7 +710,6 @@ export const resumeChain = mutation({
       throw new Error("Chain cannot be resumed");
     }
 
-    // Reset failed step to pending
     const executions = await ctx.db
       .query("chainExecutions")
       .withIndex("by_chainId_stepIndex", (q) => 
@@ -513,7 +728,6 @@ export const resumeChain = mutation({
       }
     }
 
-    // Update chain status
     await ctx.db.patch(chain._id, {
       status: "pending",
       error: undefined,
@@ -563,7 +777,7 @@ export const completeChain = internalMutation({
 });
 
 /**
- * Pause chain execution (for long-running chains)
+ * Pause chain execution
  */
 export const pauseChain = mutation({
   args: {
@@ -595,9 +809,6 @@ export const pauseChain = mutation({
 // CHAIN TEMPLATE MUTATIONS
 // ============================================
 
-/**
- * Create or update a chain template
- */
 export const saveChainTemplate = mutation({
   args: {
     id: v.optional(v.id("chainTemplates")),
@@ -611,7 +822,6 @@ export const saveChainTemplate = mutation({
     const now = Date.now();
 
     if (args.id) {
-      // Update existing
       await ctx.db.patch(args.id, {
         name: args.name,
         description: args.description,
@@ -622,7 +832,6 @@ export const saveChainTemplate = mutation({
       return args.id;
     }
 
-    // Create new
     return await ctx.db.insert("chainTemplates", {
       workspaceId: args.workspaceId,
       name: args.name,
@@ -636,9 +845,6 @@ export const saveChainTemplate = mutation({
   },
 });
 
-/**
- * Delete a chain template
- */
 export const deleteChainTemplate = mutation({
   args: {
     id: v.id("chainTemplates"),
@@ -653,9 +859,6 @@ export const deleteChainTemplate = mutation({
 // QUERIES
 // ============================================
 
-/**
- * Get chain status and results
- */
 export const getChain = query({
   args: {
     chainId: v.id("chains"),
@@ -684,9 +887,6 @@ export const getChain = query({
   },
 });
 
-/**
- * Get full execution trace for dashboard
- */
 export const getChainTrace = query({
   args: {
     chainId: v.id("chains"),
@@ -697,16 +897,13 @@ export const getChainTrace = query({
       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,
@@ -721,7 +918,6 @@ export const getChainTrace = query({
       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;
 
@@ -746,9 +942,6 @@ export const getChainTrace = query({
   },
 });
 
-/**
- * List chains for a workspace
- */
 export const listChains = query({
   args: {
     workspaceId: v.id("workspaces"),
@@ -758,14 +951,12 @@ export const listChains = query({
   handler: async (ctx, args) => {
     const limit = args.limit ?? 50;
 
-    let chainsQuery = ctx.db
+    const chains = await ctx.db
       .query("chains")
       .withIndex("by_workspaceId", (q) => q.eq("workspaceId", args.workspaceId))
-      .order("desc");
-
-    const chains = await chainsQuery.take(limit);
+      .order("desc")
+      .take(limit);
 
-    // Filter by status if provided
     let filtered = chains;
     if (args.status && args.status !== "all") {
       filtered = chains.filter((c) => c.status === args.status);
@@ -786,9 +977,6 @@ export const listChains = query({
   },
 });
 
-/**
- * List chain templates for a workspace
- */
 export const listChainTemplates = query({
   args: {
     workspaceId: v.id("workspaces"),
@@ -801,9 +989,6 @@ export const listChainTemplates = query({
   },
 });
 
-/**
- * Get chain template by name
- */
 export const getChainTemplate = query({
   args: {
     workspaceId: v.id("workspaces"),
@@ -819,9 +1004,6 @@ export const getChainTemplate = query({
   },
 });
 
-/**
- * Get chain statistics for workspace
- */
 export const getChainStats = query({
   args: {
     workspaceId: v.id("workspaces"),
@@ -841,7 +1023,6 @@ export const getChainStats = query({
     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
@@ -870,10 +1051,6 @@ export const getChainStats = query({
 // ACTIONS (Orchestration Logic)
 // ============================================
 
-/**
- * Main chain orchestrator
- * Validates chain → executes steps sequentially/parallel → handles errors
- */
 export const runChain = action({
   args: {
     workspaceId: v.id("workspaces"),
@@ -894,9 +1071,8 @@ export const runChain = action({
     totalLatencyMs?: number;
   }> => {
     const startTime = Date.now();
-    const timeout = args.timeout || 30000; // Default 30s
+    const timeout = args.timeout || 30000;
 
-    // 1. Create chain record
     const chainId = await ctx.runMutation(internal.chains.createChainInternal, {
       workspaceId: args.workspaceId,
       steps: args.steps,
@@ -908,16 +1084,13 @@ export const runChain = action({
     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,
@@ -925,13 +1098,11 @@ export const runChain = action({
             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,
@@ -939,7 +1110,6 @@ export const runChain = action({
             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;
@@ -956,11 +1126,9 @@ export const runChain = action({
           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 {
@@ -976,11 +1144,9 @@ export const runChain = action({
       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,
@@ -1007,9 +1173,6 @@ export const runChain = action({
   },
 });
 
-/**
- * Execute parallel steps concurrently
- */
 export const runParallelSteps = internalAction({
   args: {
     chainId: v.id("chains"),
@@ -1019,7 +1182,6 @@ export const runParallelSteps = internalAction({
   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,
@@ -1029,7 +1191,6 @@ export const runParallelSteps = internalAction({
       });
     }
 
-    // Execute all in parallel
     const promises = (args.steps as ChainStep[]).map(async (step) => {
       const startTime = Date.now();
       
@@ -1062,22 +1223,14 @@ export const runParallelSteps = internalAction({
 });
 
 // ============================================
-// HELPER: Execute provider call
-// Placeholder - in production, this calls the Direct Call API
+// HELPER: Execute provider call (placeholder)
 // ============================================
 
 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
+  // Simulate latency
   await new Promise((resolve) => setTimeout(resolve, 50 + Math.random() * 100));
   
   return {
@@ -1090,6 +1243,6 @@ async function executeProviderCall(
       mockResult: `Executed ${step.action} on ${step.provider}`,
       timestamp: Date.now(),
     },
-    costCents: Math.ceil(Math.random() * 5), // Mock 1-5 cents cost
+    costCents: Math.ceil(Math.random() * 5),
   };
 }