@agentforge-ai/cli 0.5.4 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge-ai/cli",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "CLI tool for creating, running, and managing AgentForge projects",
   "type": "module",
   "bin": {
@@ -12,20 +12,12 @@
     "templates",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src/",
-    "clean": "rm -rf dist"
-  },
   "dependencies": {
+    "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "convex": "^1.17.0",
-    "chalk": "^5.3.0",
     "fs-extra": "^11.2.0",
+    "gray-matter": "^4.0.3",
     "ora": "^8.0.0",
     "prompts": "^2.4.2"
   },
@@ -48,5 +40,14 @@
     "type": "git",
     "url": "https://github.com/Agentic-Engineering-Agency/agentforge.git",
     "directory": "packages/cli"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "clean": "rm -rf dist"
   }
-}
+}

package/templates/default/agentforge.config.ts

@@ -1,23 +1,117 @@
 /**
- * Example AgentForge Configuration File
- * 
- * This file defines your agents and their configurations.
- * The CLI uses this to deploy to AgentForge Cloud.
+ * AgentForge Configuration File
+ *
+ * This file defines your agents, workspace, skills, and model failover
+ * configuration. The CLI uses this to manage your AgentForge project.
  */
 
 export default {
   name: 'my-agent-project',
   version: '1.0.0',
-  
+
+  /**
+   * Workspace configuration — Mastra Workspace integration.
+   *
+   * Skills are auto-discovered from the directories listed in `skills`.
+   * Each skill directory should contain a SKILL.md file following the
+   * Agent Skills Specification.
+   *
+   * @see https://mastra.ai/docs/workspace/skills
+   */
+  workspace: {
+    /** Base path for the workspace filesystem. */
+    basePath: './workspace',
+    /** Directories containing agent skills (relative to basePath). */
+    skills: ['/skills'],
+    /** Enable BM25 keyword search for skill discovery. */
+    search: true,
+    /** Paths to auto-index for search. */
+    autoIndexPaths: ['/skills'],
+  },
+
+  /**
+   * Model Failover Configuration
+   *
+   * Defines the global default failover chain and retry policy.
+   * Individual agents can override these settings.
+   *
+   * Environment variables required:
+   *   OPENROUTER_API_KEY  — OpenRouter API key (routes to all providers)
+   *   OPENAI_API_KEY      — OpenAI direct API key
+   *   ANTHROPIC_API_KEY   — Anthropic direct API key
+   *   GEMINI_API_KEY      — Google Gemini API key
+   *   VENICE_API_KEY      — Venice AI API key (optional)
+   */
+  failover: {
+    /**
+     * Global default failover chain.
+     * Used when an agent does not specify its own `failoverModels`.
+     * Models are tried in order: primary → fallback1 → fallback2 → ...
+     */
+    defaultChain: [
+      { provider: 'openrouter', model: 'openai/gpt-4o-mini' },
+      { provider: 'openai', model: 'gpt-4o-mini' },
+      { provider: 'anthropic', model: 'claude-3-5-haiku-20241022' },
+      { provider: 'google', model: 'gemini-2.0-flash' },
+    ],
+
+    /**
+     * Retry policy for each model in the chain.
+     */
+    retryPolicy: {
+      /** Max retries per model before failing over to next. */
+      maxRetries: 2,
+      /** Initial backoff delay in ms. */
+      backoffMs: 1000,
+      /** Backoff multiplier for exponential backoff. */
+      backoffMultiplier: 2,
+      /** Maximum backoff delay in ms. */
+      maxBackoffMs: 30000,
+    },
+
+    /**
+     * Circuit breaker configuration.
+     * Opens the circuit (skips the provider) after repeated failures.
+     */
+    circuitBreaker: {
+      /** Consecutive failures before opening the circuit. */
+      failureThreshold: 5,
+      /** Time in ms before attempting to close the circuit. */
+      resetTimeoutMs: 60000,
+      /** Successes in half-open state before fully closing. */
+      successThreshold: 2,
+    },
+
+    /** Global timeout per LLM request in ms. */
+    timeoutMs: 30000,
+
+    /** Enable cost tracking per request. */
+    trackCost: true,
+
+    /** Enable latency monitoring. */
+    trackLatency: true,
+  },
+
   agents: [
     {
       id: 'support-agent',
       name: 'Customer Support Agent',
       model: 'gpt-4o',
+      provider: 'openrouter',
       instructions: `You are a helpful customer support agent.
         
 Be polite, professional, and try to resolve customer issues quickly.
 If you don't know the answer, escalate to a human agent.`,
+      /**
+       * Agent-level failover models.
+       * These override the global `failover.defaultChain` for this agent.
+       * The primary model (provider + model above) is always tried first.
+       */
+      failoverModels: [
+        { provider: 'openai', model: 'gpt-4o' },
+        { provider: 'anthropic', model: 'claude-sonnet-4-20250514' },
+        { provider: 'google', model: 'gemini-2.5-flash' },
+      ],
       tools: [
         {
           name: 'searchKnowledgeBase',
@@ -48,11 +142,19 @@ If you don't know the answer, escalate to a human agent.`,
     {
       id: 'code-assistant',
       name: 'Code Assistant',
-      model: 'anthropic/claude-3-opus',
+      model: 'claude-sonnet-4-20250514',
+      provider: 'anthropic',
       instructions: `You are an expert programming assistant.
         
 Help users write clean, efficient, and well-documented code.
 Explain your reasoning and provide examples when helpful.`,
+      /**
+       * Agent-level failover: Anthropic → OpenAI → Google
+       */
+      failoverModels: [
+        { provider: 'openai', model: 'gpt-4.1' },
+        { provider: 'google', model: 'gemini-2.5-pro' },
+      ],
       tools: [
         {
           name: 'runCode',
@@ -70,6 +172,24 @@ Explain your reasoning and provide examples when helpful.`,
     },
   ],
   
+  // Sandbox configuration for agent tool execution isolation
+  sandbox: {
+    // Provider: 'local' (default), 'docker', 'e2b', or 'none'
+    provider: 'local',
+    // Docker-specific options (only used when provider is 'docker')
+    docker: {
+      image: 'node:22-slim',
+      resourceLimits: {
+        memoryMb: 512,
+        cpuShares: 512,
+        networkDisabled: false,
+        pidsLimit: 256,
+      },
+      // Timeout in seconds before auto-killing the container
+      timeout: 300,
+    },
+  },
+
   // Optional: Environment variables available to all agents
   env: {
     SUPPORT_EMAIL: 'support@example.com',

package/templates/default/convex/agents.ts

@@ -38,13 +38,13 @@ export const listActive = query({
     const activeQuery = ctx.db
       .query("agents")
       .withIndex("byIsActive", (q) => q.eq("isActive", true));
-    
+
     const agents = await activeQuery.collect();
-    
+
     if (args.userId) {
       return agents.filter((agent) => agent.userId === args.userId);
     }
-    
+
     return agents;
   },
 });
@@ -151,7 +151,12 @@ export const toggleActive = mutation({
   },
 });
 
-// Action: Run agent with Mastra (to be implemented with Mastra integration)
+/**
+ * Run an agent with a prompt.
+ *
+ * Delegates to `chat.sendMessage` for the actual LLM execution.
+ * This action handles thread creation if no threadId is provided.
+ */
 export const run = action({
   args: {
     agentId: v.string(),
@@ -162,7 +167,7 @@ export const run = action({
   handler: async (ctx, args): Promise<{ threadId: string; message: string; agentId: string }> => {
     // Get agent configuration
     const agent = await ctx.runQuery(api.agents.get, { id: args.agentId });
-    
+
     if (!agent) {
       throw new Error(`Agent with id ${args.agentId} not found`);
     }
@@ -176,28 +181,17 @@ export const run = action({
       });
     }
 
-    // Add user message
-    await ctx.runMutation(api.messages.add, {
+    // Delegate to the chat action for actual LLM execution
+    const result = await ctx.runAction(api.chat.sendMessage, {
+      agentId: args.agentId,
       threadId,
-      role: "user",
       content: args.prompt,
-    });
-
-    // TODO: Integrate with Mastra to run the agent
-    // This will be implemented in the Mastra integration phase
-    // For now, return a placeholder response
-    const responseMessage = "Agent execution will be implemented with Mastra integration";
-
-    // Add assistant message placeholder
-    await ctx.runMutation(api.messages.add, {
-      threadId,
-      role: "assistant",
-      content: responseMessage,
+      userId: args.userId,
     });
 
     return {
       threadId: threadId as string,
-      message: responseMessage,
+      message: result.response,
       agentId: args.agentId,
     };
   },

package/templates/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,
+    };
+  },
+});