@agentforge-ai/cli 0.5.4 → 0.6.0

package/dist/default/convex/chat.ts

@@ -0,0 +1,302 @@
+/**
+ * Chat Actions for AgentForge
+ *
+ * This module provides the core chat execution pipeline:
+ * 1. User sends a message → stored via mutation
+ * 2. Convex action triggers LLM generation via Mastra Agent
+ * 3. Assistant response stored back in Convex
+ * 4. Real-time subscription updates the UI automatically
+ *
+ * Uses Mastra-native model routing via Agent.generate() with "provider/model-name" format.
+ * Mastra auto-reads provider API keys from environment variables.
+ */
+import { action, mutation, query } from "./_generated/server";
+import { v } from "convex/values";
+import { api } from "./_generated/api";
+import { Agent } from "@mastra/core/agent";
+
+// ============================================================
+// Queries
+// ============================================================
+
+/**
+ * Get the current chat state for a thread: messages + thread metadata.
+ */
+export const getThreadMessages = query({
+  args: { threadId: v.id("threads") },
+  handler: async (ctx, args) => {
+    const messages = await ctx.db
+      .query("messages")
+      .withIndex("byThread", (q) => q.eq("threadId", args.threadId))
+      .collect();
+    return messages;
+  },
+});
+
+/**
+ * List all threads for a user, ordered by most recent activity.
+ */
+export const listThreads = query({
+  args: {
+    userId: v.optional(v.string()),
+    agentId: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    let threads;
+    if (args.agentId) {
+      threads = await ctx.db
+        .query("threads")
+        .withIndex("byAgentId", (q) => q.eq("agentId", args.agentId!))
+        .collect();
+    } else if (args.userId) {
+      threads = await ctx.db
+        .query("threads")
+        .withIndex("byUserId", (q) => q.eq("userId", args.userId!))
+        .collect();
+    } else {
+      threads = await ctx.db.query("threads").collect();
+    }
+    // Sort by most recently updated
+    return threads.sort((a, b) => b.updatedAt - a.updatedAt);
+  },
+});
+
+// ============================================================
+// Mutations
+// ============================================================
+
+/**
+ * Create a new chat thread for an agent.
+ */
+export const createThread = mutation({
+  args: {
+    agentId: v.string(),
+    name: v.optional(v.string()),
+    userId: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const threadId = await ctx.db.insert("threads", {
+      name: args.name || "New Chat",
+      agentId: args.agentId,
+      userId: args.userId,
+      createdAt: now,
+      updatedAt: now,
+    });
+    return threadId;
+  },
+});
+
+/**
+ * Store a user message in a thread (called before triggering LLM).
+ */
+export const addUserMessage = mutation({
+  args: {
+    threadId: v.id("threads"),
+    content: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const messageId = await ctx.db.insert("messages", {
+      threadId: args.threadId,
+      role: "user",
+      content: args.content,
+      createdAt: Date.now(),
+    });
+    await ctx.db.patch(args.threadId, { updatedAt: Date.now() });
+    return messageId;
+  },
+});
+
+/**
+ * Store an assistant message in a thread (called after LLM responds).
+ */
+export const addAssistantMessage = mutation({
+  args: {
+    threadId: v.id("threads"),
+    content: v.string(),
+    metadata: v.optional(v.any()),
+  },
+  handler: async (ctx, args) => {
+    const messageId = await ctx.db.insert("messages", {
+      threadId: args.threadId,
+      role: "assistant",
+      content: args.content,
+      metadata: args.metadata,
+      createdAt: Date.now(),
+    });
+    await ctx.db.patch(args.threadId, { updatedAt: Date.now() });
+    return messageId;
+  },
+});
+
+// ============================================================
+// Actions (Node.js runtime — can call external APIs)
+// ============================================================
+
+/**
+ * Send a message and get an AI response.
+ *
+ * This is the main chat action. It:
+ * 1. Looks up the agent config from the database
+ * 2. Stores the user message
+ * 3. Builds conversation history from the thread
+ * 4. Calls the provider via Mastra Agent.generate()
+ * 5. Stores the assistant response
+ * 6. Records usage metrics
+ *
+ * The UI subscribes to `chat.getThreadMessages` which auto-updates
+ * when new messages are inserted.
+ */
+export const sendMessage = action({
+  args: {
+    agentId: v.string(),
+    threadId: v.id("threads"),
+    content: v.string(),
+    userId: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    // 1. Get agent configuration
+    const agent = await ctx.runQuery(api.agents.get, { id: args.agentId });
+    if (!agent) {
+      throw new Error(`Agent "${args.agentId}" not found. Please create an agent first.`);
+    }
+
+    // 2. Store the user message
+    await ctx.runMutation(api.chat.addUserMessage, {
+      threadId: args.threadId,
+      content: args.content,
+    });
+
+    // 3. Get conversation history for context
+    const history = await ctx.runQuery(api.chat.getThreadMessages, {
+      threadId: args.threadId,
+    });
+
+    // Build messages array for the LLM (last 20 messages for context window)
+    const conversationMessages = history
+      .slice(-20)
+      .map((msg: { role: string; content: string }) => ({
+        role: msg.role as "user" | "assistant" | "system",
+        content: msg.content,
+      }));
+
+    // 4. Call the LLM via Mastra Agent
+    let responseText: string;
+    let usageData: { promptTokens: number; completionTokens: number; totalTokens: number } | null = null;
+
+    try {
+      // Resolve the model provider and ID
+      const provider = agent.provider || "openrouter";
+      const modelId = agent.model || "openai/gpt-4o-mini";
+      const modelKey = `${provider}/${modelId}`;
+
+      // Generate via Mastra Agent
+      const mastraAgent = new Agent({
+        name: "agentforge-executor",
+        instructions: agent.instructions || "You are a helpful AI assistant built with AgentForge.",
+        model: modelKey,
+      });
+
+      const result = await mastraAgent.generate(conversationMessages);
+
+      responseText = result.text;
+
+      // Extract usage if available
+      if (result.usage) {
+        usageData = {
+          promptTokens: result.usage.promptTokens || 0,
+          completionTokens: result.usage.completionTokens || 0,
+          totalTokens: (result.usage.promptTokens || 0) + (result.usage.completionTokens || 0),
+        };
+      }
+    } catch (error: unknown) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      console.error("[chat.sendMessage] Mastra error:", errorMessage);
+
+      // Store error as assistant message so user sees feedback
+      responseText = `I encountered an error while processing your request: ${errorMessage}`;
+    }
+
+    // 5. Store the assistant response
+    await ctx.runMutation(api.chat.addAssistantMessage, {
+      threadId: args.threadId,
+      content: responseText,
+      metadata: usageData ? { usage: usageData } : undefined,
+    });
+
+    // 6. Record usage metrics (non-blocking, best-effort)
+    if (usageData) {
+      try {
+        await ctx.runMutation(api.usage.record, {
+          agentId: args.agentId,
+          provider: agent.provider || "openrouter",
+          model: agent.model || "unknown",
+          promptTokens: usageData.promptTokens,
+          completionTokens: usageData.completionTokens,
+          totalTokens: usageData.totalTokens,
+          userId: args.userId,
+        });
+      } catch (e) {
+        console.error("[chat.sendMessage] Usage recording failed:", e);
+      }
+    }
+
+    // 7. Log the interaction
+    try {
+      await ctx.runMutation(api.logs.add, {
+        level: "info",
+        source: "chat",
+        message: `Agent "${agent.name}" responded to user message`,
+        metadata: {
+          agentId: args.agentId,
+          threadId: args.threadId,
+          usage: usageData,
+        },
+        userId: args.userId,
+      });
+    } catch (e) {
+      console.error("[chat.sendMessage] Logging failed:", e);
+    }
+
+    return {
+      success: true,
+      threadId: args.threadId,
+      response: responseText,
+      usage: usageData,
+    };
+  },
+});
+
+/**
+ * Create a new thread and send the first message in one action.
+ * Convenience action for starting a new conversation.
+ */
+export const startNewChat = action({
+  args: {
+    agentId: v.string(),
+    content: v.string(),
+    threadName: v.optional(v.string()),
+    userId: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    // Create a new thread
+    const threadId = await ctx.runMutation(api.chat.createThread, {
+      agentId: args.agentId,
+      name: args.threadName || "New Chat",
+      userId: args.userId,
+    });
+
+    // Send the first message
+    const result = await ctx.runAction(api.chat.sendMessage, {
+      agentId: args.agentId,
+      threadId,
+      content: args.content,
+      userId: args.userId,
+    });
+
+    return {
+      ...result,
+      threadId,
+    };
+  },
+});

package/dist/default/convex/mastraIntegration.ts

@@ -1,24 +1,38 @@
-import { action } from "./_generated/server";
-import { v } from "convex/values";
-import { api } from "./_generated/api";
-
 /**
  * Mastra Integration Actions for Convex
- * 
- * These actions run in the Node.js runtime and can use Mastra
- * to execute agents and manage workflows.
+ *
+ * These actions run in the Convex Node.js runtime and execute LLM calls
+ * using Mastra-native model routing with OpenRouter as the default provider.
+ *
+ * Architecture:
+ * - For chat: use `chat.sendMessage` (preferred entry point)
+ * - For programmatic agent execution: use `mastraIntegration.executeAgent`
+ * - Model resolution: uses Mastra Agent with "provider/model-name" format
  */
+import { action } from "./_generated/server";
+import { v } from "convex/values";
+import { api } from "./_generated/api";
+import { Agent } from "@mastra/core/agent";
 
-// Return type for executeAgent to break circular type inference
+// Return type for executeAgent
 type ExecuteAgentResult = {
   success: boolean;
   threadId: string;
   sessionId: string;
   response: string;
-  usage?: Record<string, unknown>;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
 };
 
-// Action: Execute agent with Mastra
+/**
+ * Execute an agent with a prompt and return the response.
+ *
+ * This is the programmatic API for agent execution. For chat UI,
+ * prefer `chat.sendMessage` which handles thread management automatically.
+ */
 export const executeAgent = action({
   args: {
     agentId: v.string(),
@@ -30,7 +44,7 @@ export const executeAgent = action({
   handler: async (ctx, args): Promise<ExecuteAgentResult> => {
     // Get agent configuration from database
     const agent = await ctx.runQuery(api.agents.get, { id: args.agentId });
-    
+
     if (!agent) {
       throw new Error(`Agent ${args.agentId} not found`);
     }
@@ -58,50 +72,34 @@ export const executeAgent = action({
       threadId,
       agentId: args.agentId,
       userId: args.userId,
-      channel: "dashboard",
+      channel: "api",
     });
 
     try {
-      // Import Mastra dynamically (Node.js runtime)
-      // @ts-expect-error - Mastra is installed at runtime in the user's project
-      const { Agent } = await import("@mastra/core/agent");
-      
-      // Format model string for Mastra
-      const modelString = agent.model.includes("/")
-        ? agent.model
-        : `${agent.provider}/${agent.model}`;
-
-      // Create Mastra agent
-      const mastraAgent = new Agent({
-        id: agent.id,
-        name: agent.name,
-        instructions: agent.instructions,
-        model: modelString,
-        tools: agent.tools || {},
-        ...(agent.temperature && { temperature: agent.temperature }),
-        ...(agent.maxTokens && { maxTokens: agent.maxTokens }),
-        ...(agent.topP && { topP: agent.topP }),
-      });
+      // Resolve the model
+      const provider = agent.provider || "openrouter";
+      const modelId = agent.model || "openai/gpt-4o-mini";
+      const modelKey = `${provider}/${modelId}`;
 
       // Get conversation history for context
-      const messages = await ctx.runQuery(api.messages.list, { threadId }) as Array<{ role: string; content: string }>;
-      
-      // Build context from message history
-      const context = messages
-        .slice(-10) // Last 10 messages for context
-        .map((m) => `${m.role}: ${m.content}`)
-        .join("\n");
-
-      // Execute agent
-      const result: any = await mastraAgent.generate(args.prompt, {
-        ...(args.stream && { stream: args.stream }),
-        context: context || undefined,
+      const messages = await ctx.runQuery(api.messages.list, { threadId });
+      const conversationMessages = (messages as Array<{ role: string; content: string }>)
+        .slice(-20)
+        .map((m) => ({
+          role: m.role as "user" | "assistant" | "system",
+          content: m.content,
+        }));
+
+      // Execute via Mastra Agent
+      const mastraAgent = new Agent({
+        name: "agentforge-executor",
+        instructions: agent.instructions || "You are a helpful AI assistant.",
+        model: modelKey,
       });
 
-      // Extract response content
-      const responseContent: string = typeof result === "string" 
-        ? result 
-        : result.text || result.content || JSON.stringify(result);
+      const result = await mastraAgent.generate(conversationMessages);
+
+      const responseContent = result.text;
 
       // Add assistant message to thread
       await ctx.runMutation(api.messages.add, {
@@ -116,17 +114,27 @@ export const executeAgent = action({
         status: "completed",
       });
 
-      // Record usage (if available in result)
-      if (result.usage) {
+      // Build usage data
+      const usage = result.usage
+        ? {
+            promptTokens: result.usage.promptTokens || 0,
+            completionTokens: result.usage.completionTokens || 0,
+            totalTokens:
+              (result.usage.promptTokens || 0) +
+              (result.usage.completionTokens || 0),
+          }
+        : undefined;
+
+      // Record usage
+      if (usage) {
         await ctx.runMutation(api.usage.record, {
           agentId: args.agentId,
           sessionId,
-          provider: agent.provider,
-          model: agent.model,
-          promptTokens: result.usage.promptTokens || 0,
-          completionTokens: result.usage.completionTokens || 0,
-          totalTokens: result.usage.totalTokens || 0,
-          cost: result.usage.cost,
+          provider: agent.provider || "openrouter",
+          model: agent.model || "unknown",
+          promptTokens: usage.promptTokens,
+          completionTokens: usage.completionTokens,
+          totalTokens: usage.totalTokens,
           userId: args.userId,
         });
       }
@@ -136,10 +144,11 @@ export const executeAgent = action({
         threadId: threadId as string,
         sessionId,
         response: responseContent,
-        usage: result.usage,
+        usage,
       };
     } catch (error: unknown) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
 
       // Update session status to error
       await ctx.runMutation(api.sessions.updateStatus, {
@@ -147,19 +156,37 @@ export const executeAgent = action({
         status: "error",
       });
 
-      // Add error message
+      // Add error message to thread
       await ctx.runMutation(api.messages.add, {
         threadId,
         role: "assistant",
         content: `Error: ${errorMessage}`,
       });
 
+      // Log the error
+      await ctx.runMutation(api.logs.add, {
+        level: "error",
+        source: "mastraIntegration",
+        message: `Agent execution failed: ${errorMessage}`,
+        metadata: {
+          agentId: args.agentId,
+          threadId,
+          sessionId,
+        },
+        userId: args.userId,
+      });
+
       throw error;
     }
   },
 });
 
-// Action: Stream agent response
+/**
+ * Stream agent response (placeholder — streaming requires SSE/WebSocket).
+ *
+ * For now, this falls back to non-streaming execution.
+ * Full streaming support will be added via Convex HTTP actions + SSE.
+ */
 export const streamAgent = action({
   args: {
     agentId: v.string(),
@@ -168,26 +195,31 @@ export const streamAgent = action({
     userId: v.optional(v.string()),
   },
   handler: async (ctx, args): Promise<{ success: boolean; message: string }> => {
-    // Similar to executeAgent but with streaming support
-    // This would require WebSocket or SSE implementation
-    // For now, return a placeholder
+    // Fall back to non-streaming execution
+    const result = await ctx.runAction(api.mastraIntegration.executeAgent, {
+      agentId: args.agentId,
+      prompt: args.prompt,
+      threadId: args.threadId,
+      userId: args.userId,
+    });
+
     return {
-      success: true,
-      message: "Streaming support coming soon",
+      success: result.success,
+      message: result.response,
     };
   },
 });
 
-// Action: Execute workflow with multiple agents
+/**
+ * Execute workflow with multiple agents (placeholder).
+ */
 export const executeWorkflow = action({
   args: {
     workflowId: v.string(),
     input: v.any(),
     userId: v.optional(v.string()),
   },
-  handler: async (ctx, args): Promise<{ success: boolean; message: string }> => {
-    // Placeholder for workflow execution
-    // This would orchestrate multiple agents in sequence or parallel
+  handler: async (_ctx, _args): Promise<{ success: boolean; message: string }> => {
     return {
       success: true,
       message: "Workflow execution coming soon",