@agentforge-ai/cli 0.4.2 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge-ai/cli",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "CLI tool for creating, running, and managing AgentForge projects",
   "type": "module",
   "bin": {

package/templates/default/README.md

@@ -1,110 +1,110 @@
-# My AgentForge Project
+# AgentForge Project
 
-Built with [AgentForge](https://github.com/Agentic-Engineering-Agency/agentforge) — a NanoClaw made with Mastra.
+Welcome to your new AgentForge project! This project was scaffolded by the `@agentforge-ai/cli`.
 
-## Quick Start
+## 🚀 Quick Start
+
+### 1. Install Dependencies
+
+If this wasn't done automatically during project creation, install the dependencies for the root project and the dashboard:
 
 ```bash
-# 1. Install dependencies
-npm install
+# Install root dependencies
+pnpm install
+
+# Install dashboard dependencies
+cd dashboard
+pnpm install
+cd ..
+```
 
-# 2. Set up your environment
-cp .env.example .env
-# Edit .env and add your API key (OpenAI, OpenRouter, Anthropic, etc.)
+### 2. Configure Your Environment
+
+Copy the example environment file and add your API keys. You only need to configure one LLM provider to get started.
+
+```bash
+cp .env.example .env.local
+```
 
-# 3. Start the Convex dev server
+Edit `.env.local` with your keys:
+
+```dotenv
+# Convex URL will be set automatically by `npx convex dev`
+CONVEX_URL=
+
+# Add your preferred LLM provider API key
+OPENAI_API_KEY=sk-...
+```
+
+### 3. Start the Development Servers
+
+AgentForge requires two concurrent processes for local development:
+
+```bash
+# Terminal 1: Start the Convex backend
 npx convex dev
 
-# 4. Start building!
-npm run dev
+# Terminal 2: Launch the web dashboard
+agentforge dashboard
+```
+
+- The **Convex backend** syncs your database schema and functions, providing a dashboard at `http://localhost:8187`.
+- The **web dashboard** provides a UI for managing your agents, available at `http://localhost:3000`.
+
+## 🤖 Your First Agent
+
+Your default agent is defined in `src/agent.ts`. You can customize its instructions, model, and tools.
+
+```typescript
+// src/agent.ts
+import { Agent } from '@agentforge-ai/core';
+
+const myAgent = new Agent({
+  id: 'my-first-agent',
+  name: 'My First Agent',
+  instructions: 'You are a helpful AI assistant...',
+  model: 'openai:gpt-4o-mini',
+});
+
+export default myAgent;
 ```
 
 ## Project Structure
 
 ```
-├── convex/          # Convex schema and functions
-│   └── schema.ts    # Database schema (agents, threads, messages, etc.)
+/my-agent-project
+├── convex/                 # Convex backend (database schema, functions)
+├── dashboard/              # Web dashboard frontend (Vite + React)
+├── skills/                 # Custom agent skills
+├── workspace/              # Default local file storage for agents
 ├── src/
-│   └── agent.ts     # Your agent definition
-├── skills/          # Custom skills directory
-├── .env.example     # Environment variable template
+│   └── agent.ts            # Your main agent definition
+├── .env.local              # Your local environment variables
 ├── package.json
 └── tsconfig.json
 ```
 
-## CLI Commands
+##  CLI Commands
+
+Use the `agentforge` CLI to manage your project from the terminal.
 
 ```bash
-# Agent Management
-agentforge agents list              # List all agents
-agentforge agents create            # Create a new agent (interactive)
-agentforge agents inspect <id>      # Show agent details
-agentforge agents edit <id>         # Edit an agent
-agentforge agents delete <id>       # Delete an agent
-
-# Chat
-agentforge chat <agent-id>          # Start chatting with an agent
-agentforge chat --session <id>      # Resume a session
-
-# Sessions & Threads
-agentforge sessions list            # List all sessions
-agentforge threads list             # List all threads
-
-# Skills
-agentforge skills list              # List installed skills
-agentforge skills install <name>    # Install a skill
-agentforge skills search <query>    # Search available skills
-
-# Cron Jobs
-agentforge cron list                # List cron jobs
-agentforge cron create              # Create a cron job (interactive)
-
-# MCP Connections
-agentforge mcp list                 # List MCP connections
-agentforge mcp add                  # Add a connection (interactive)
-agentforge mcp test <id>            # Test connection health
-
-# Files & Projects
-agentforge files list               # List files
-agentforge files upload <path>      # Upload a file
-agentforge projects list            # List projects
-agentforge projects create <name>   # Create a project
-
-# Configuration & Vault
-agentforge config list              # List all config
-agentforge vault list               # List secrets (masked)
-agentforge vault add <name> <value> # Store a secret
-
-# Utilities
-agentforge status                   # Show system health
-agentforge logs                     # Tail recent logs
-agentforge dashboard                # Open the web dashboard
-agentforge deploy                   # Deploy to production
-```
+# List all agents
+agentforge agents list
 
-## Providers
+# Chat with your agent
+agentforge chat my-first-agent
 
-AgentForge supports multiple LLM providers. Set your preferred provider in `.env`:
+# See all available commands
+agentforge --help
+```
 
-| Provider | Model Format | API Key Variable |
-|----------|-------------|-----------------|
-| OpenAI | `openai:gpt-4o-mini` | `OPENAI_API_KEY` |
-| OpenRouter | `openrouter:anthropic/claude-3.5-sonnet` | `OPENROUTER_API_KEY` |
-| Anthropic | `anthropic:claude-3-5-sonnet-20241022` | `ANTHROPIC_API_KEY` |
-| Google | `google:gemini-2.0-flash` | `GOOGLE_API_KEY` |
-| xAI | `xai:grok-2` | `XAI_API_KEY` |
 
-## Web Dashboard
 
-Launch the dashboard for a visual interface:
 
-```bash
-agentforge dashboard
-```
 
 ## Learn More
 
-- [AgentForge Documentation](https://github.com/Agentic-Engineering-Agency/agentforge)
-- [CLI Reference](https://github.com/Agentic-Engineering-Agency/agentforge/blob/main/docs/cli-reference.md)
-- [Convex Docs](https://docs.convex.dev)
-- [Mastra Docs](https://mastra.ai/docs)
+- **[AgentForge Documentation](https://github.com/Agentic-Engineering-Agency/agentforge)**: Main project repository and documentation.
+- **[Convex Docs](https://docs.convex.dev)**: Learn more about the real-time backend.
+- **[Mastra Docs](https://mastra.ai/docs)**: Understand the core AI engine.

package/templates/default/convex/agents.ts

@@ -0,0 +1,204 @@
+import { v } from "convex/values";
+import { mutation, query, action } from "./_generated/server";
+import { api } from "./_generated/api";
+
+// Query: Get all agents
+export const list = query({
+  args: {
+    userId: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    if (args.userId) {
+      return await ctx.db
+        .query("agents")
+        .withIndex("byUserId", (q) => q.eq("userId", args.userId))
+        .take(100).collect();
+    }
+    return await ctx.db.query("agents").take(100).collect();
+  },
+});
+
+// Query: Get agent by ID
+export const get = query({
+  args: { id: v.string() },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("agents")
+      .withIndex("byAgentId", (q) => q.eq("id", args.id))
+      .first();
+  },
+});
+
+// Query: Get active agents
+export const listActive = query({
+  args: {
+    userId: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    let query = ctx.db
+      .query("agents")
+      .withIndex("byIsActive", (q) => q.eq("isActive", true));
+    
+    const agents = await query.take(100).collect();
+    
+    if (args.userId) {
+      return agents.filter((agent) => agent.userId === args.userId);
+    }
+    
+    return agents;
+  },
+});
+
+// Mutation: Create a new agent
+export const create = mutation({
+  args: {
+    id: v.string(),
+    name: v.string(),
+    description: v.optional(v.string()),
+    instructions: v.string(),
+    model: v.string(),
+    provider: v.string(),
+    tools: v.optional(v.any()),
+    temperature: v.optional(v.number()),
+    maxTokens: v.optional(v.number()),
+    topP: v.optional(v.number()),
+    userId: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const agentId = await ctx.db.insert("agents", {
+      ...args,
+      isActive: true,
+      createdAt: now,
+      updatedAt: now,
+    });
+    return agentId;
+  },
+});
+
+// Mutation: Update an agent
+export const update = mutation({
+  args: {
+    id: v.string(),
+    name: v.optional(v.string()),
+    description: v.optional(v.string()),
+    instructions: v.optional(v.string()),
+    model: v.optional(v.string()),
+    provider: v.optional(v.string()),
+    tools: v.optional(v.any()),
+    temperature: v.optional(v.number()),
+    maxTokens: v.optional(v.number()),
+    topP: v.optional(v.number()),
+    isActive: v.optional(v.boolean()),
+  },
+  handler: async (ctx, args) => {
+    const { id, ...updates } = args;
+    const agent = await ctx.db
+      .query("agents")
+      .withIndex("byAgentId", (q) => q.eq("id", id))
+      .first();
+
+    if (!agent) {
+      throw new Error(`Agent with id ${id} not found`);
+    }
+
+    await ctx.db.patch(agent._id, {
+      ...updates,
+      updatedAt: Date.now(),
+    });
+
+    return agent._id;
+  },
+});
+
+// Mutation: Delete an agent
+export const remove = mutation({
+  args: { id: v.string() },
+  handler: async (ctx, args) => {
+    const agent = await ctx.db
+      .query("agents")
+      .withIndex("byAgentId", (q) => q.eq("id", args.id))
+      .first();
+
+    if (!agent) {
+      throw new Error(`Agent with id ${args.id} not found`);
+    }
+
+    await ctx.db.delete(agent._id);
+    return { success: true };
+  },
+});
+
+// Mutation: Toggle agent active status
+export const toggleActive = mutation({
+  args: { id: v.string() },
+  handler: async (ctx, args) => {
+    const agent = await ctx.db
+      .query("agents")
+      .withIndex("byAgentId", (q) => q.eq("id", args.id))
+      .first();
+
+    if (!agent) {
+      throw new Error(`Agent with id ${args.id} not found`);
+    }
+
+    await ctx.db.patch(agent._id, {
+      isActive: !agent.isActive,
+      updatedAt: Date.now(),
+    });
+
+    return { success: true, isActive: !agent.isActive };
+  },
+});
+
+// Action: Run agent with Mastra (to be implemented with Mastra integration)
+export const run = action({
+  args: {
+    agentId: v.string(),
+    prompt: v.string(),
+    threadId: v.optional(v.id("threads")),
+    userId: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    // 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`);
+    }
+
+    // Create or get thread
+    let threadId = args.threadId;
+    if (!threadId) {
+      threadId = await ctx.runMutation(api.threads.create, {
+        agentId: args.agentId,
+        userId: args.userId,
+      });
+    }
+
+    // Add user message
+    await ctx.runMutation(api.messages.add, {
+      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 response = {
+      threadId,
+      message: "Agent execution will be implemented with Mastra integration",
+      agentId: args.agentId,
+    };
+
+    // Add assistant message placeholder
+    await ctx.runMutation(api.messages.add, {
+      threadId,
+      role: "assistant",
+      content: response.message,
+    });
+
+    return response;
+  },
+});

package/templates/default/convex/apiKeys.ts

@@ -0,0 +1,133 @@
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server";
+
+// Query: List API keys
+export const list = query({
+  args: {
+    userId: v.optional(v.string()),
+    provider: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    if (args.provider) {
+      const keys = await ctx.db
+        .query("apiKeys")
+        .withIndex("byProvider", (q) => q.eq("provider", args.provider))
+        .take(100).collect();
+      
+      if (args.userId) {
+        return keys.filter((k) => k.userId === args.userId);
+      }
+      return keys;
+    }
+    
+    if (args.userId) {
+      return await ctx.db
+        .query("apiKeys")
+        .withIndex("byUserId", (q) => q.eq("userId", args.userId))
+        .take(100).collect();
+    }
+    
+    return await ctx.db.query("apiKeys").take(100).collect();
+  },
+});
+
+// Query: Get API key by ID
+export const get = query({
+  args: { id: v.id("apiKeys") },
+  handler: async (ctx, args) => {
+    return await ctx.db.get(args.id);
+  },
+});
+
+// Query: Get active API key for provider
+export const getActiveForProvider = query({
+  args: {
+    provider: v.string(),
+    userId: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    const keys = await ctx.db
+      .query("apiKeys")
+      .withIndex("byProvider", (q) => q.eq("provider", args.provider))
+      .take(100).collect();
+    
+    const activeKeys = keys.filter((k) => k.isActive);
+    
+    if (args.userId) {
+      return activeKeys.find((k) => k.userId === args.userId);
+    }
+    
+    return activeKeys[0];
+  },
+});
+
+// Mutation: Create API key
+export const create = mutation({
+  args: {
+    provider: v.string(),
+    keyName: v.string(),
+    encryptedKey: v.string(),
+    userId: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    const keyId = await ctx.db.insert("apiKeys", {
+      ...args,
+      isActive: true,
+      createdAt: Date.now(),
+    });
+    return keyId;
+  },
+});
+
+// Mutation: Update API key
+export const update = mutation({
+  args: {
+    id: v.id("apiKeys"),
+    keyName: v.optional(v.string()),
+    encryptedKey: v.optional(v.string()),
+    isActive: v.optional(v.boolean()),
+  },
+  handler: async (ctx, args) => {
+    const { id, ...updates } = args;
+    await ctx.db.patch(id, updates);
+    return id;
+  },
+});
+
+// Mutation: Toggle API key active status
+export const toggleActive = mutation({
+  args: { id: v.id("apiKeys") },
+  handler: async (ctx, args) => {
+    const key = await ctx.db.get(args.id);
+    
+    if (!key) {
+      throw new Error(`API key not found`);
+    }
+    
+    await ctx.db.patch(args.id, {
+      isActive: !key.isActive,
+    });
+    
+    return { success: true, isActive: !key.isActive };
+  },
+});
+
+// Mutation: Update last used timestamp
+export const updateLastUsed = mutation({
+  args: { id: v.id("apiKeys") },
+  handler: async (ctx, args) => {
+    await ctx.db.patch(args.id, {
+      lastUsedAt: Date.now(),
+    });
+    return args.id;
+  },
+});
+
+// Mutation: Delete API key
+export const remove = mutation({
+  args: { id: v.id("apiKeys") },
+  handler: async (ctx, args) => {
+    await ctx.db.delete(args.id);
+    return { success: true };
+  },
+});