@forloop-cc/forloop-opencode-plugin-planner 2.2.1

package/plugins/tools/agent-tools.ts

@@ -0,0 +1,114 @@
+import { tool } from '@opencode-ai/plugin';
+import { getToken, setToken } from '../capabilities/token-storage';
+import { validateToken } from '../capabilities/auth';
+import { ForLoopAPIClient } from '../capabilities/api-client';
+import { getTokensUrl } from '../capabilities/config';
+
+export function createTokenSetTool(client?: ForLoopAPIClient) {
+  return tool({
+    description: 'Set or update the ForLoop API token',
+    args: {
+      token: tool.schema.string()
+        .describe('API token (starts with "floop_")'),
+      profile: tool.schema.string()
+        .optional()
+        .describe('Profile name (e.g., "dev", "prod")'),
+    },
+    async execute(args, _context) {
+      if (!args.token || !args.token.startsWith('floop_')) {
+        return '❌ Invalid token format. ForLoop tokens should start with "floop_"';
+      }
+
+      try {
+        await setToken(args.token, args.profile);
+        client?.setToken(args.token);
+        
+        const message = args.profile
+          ? `✅ Token saved to profile "${args.profile}"`
+          : '✅ Default token saved successfully';
+        
+        return message;
+      } catch (error: any) {
+        return `❌ Error saving token: ${error.message}`;
+      }
+    },
+  });
+}
+
+export function createTokenGetTool() {
+  return tool({
+    description: 'Check if ForLoop API token is configured',
+    args: {
+      profile: tool.schema.string()
+        .optional()
+        .describe('Profile name to check'),
+    },
+    async execute(args, _context) {
+      const token = await getToken(args.profile);
+      
+      if (!token) {
+        return [
+          '❌ No ForLoop API token configured',
+          '',
+          'Token location: ~/.config/forloop/tokens.json',
+          '',
+          'To create a token:',
+          `  1. Go to ${getTokensUrl()}`,
+          '  2. Click "Create New Token"',
+          '  3. Copy the token',
+          '  4. Run: forloopTokenSet --token <your-token>',
+        ].join('\n');
+      }
+
+      const masked = token.slice(0, 10) + '...' + token.slice(-4);
+      return `✅ ForLoop token configured: ${masked}`;
+    },
+  });
+}
+
+export function createAgentQueryTool(client: ForLoopAPIClient) {
+  return tool({
+    description: 'Query ForLoop AI agents for analysis, suggestions, or execution',
+    args: {
+      query: tool.schema.string()
+        .describe('Natural language query or command'),
+      agentKey: tool.schema.enum(['forLoopTaskSupervisor'])
+        .optional()
+        .default('forLoopTaskSupervisor'),
+      sprintId: tool.schema.number()
+        .optional()
+        .describe('Sprint context'),
+      enableMutations: tool.schema.boolean()
+        .default(false)
+        .describe('Allow agent to make changes'),
+    },
+    async execute(args, context) {
+      const tokenResult = await validateToken();
+      if (!tokenResult.valid) {
+        return tokenResult.error;
+      }
+      client.setToken?.(tokenResult.token);
+
+      try {
+        const resolution = await resolveSprintId(args.sprintId, context.directory);
+        
+        const response = await client.chatWithAI({
+          message: args.query,
+          sprintId: resolution.sprintId,
+          selectedAgentKey: args.agentKey,
+          type: args.enableMutations ? 'feature' : 'analysis',
+        });
+
+        return [
+          `Query submitted to ${args.agentKey} agent.`,
+          '',
+          response.message || 'Processing your request...',
+        ].join('\n');
+      } catch (error: any) {
+        return `❌ Error: ${error.message}`;
+      }
+    },
+  });
+}
+
+import { resolveSprintId } from '../capabilities/context-resolver';

package/plugins/tools/ai-trigger-tools.ts

@@ -0,0 +1,79 @@
+import { tool } from '@opencode-ai/plugin';
+import { ForLoopAPIClient } from '../capabilities/api-client';
+import { validateToken } from '../capabilities/auth';
+
+/**
+ * Create tools for triggering AI agent execution via EventBridge
+ */
+export function createAITriggerTools(client: ForLoopAPIClient) {
+  const tools: Record<string, ReturnType<typeof tool>> = {};
+
+  tools['forloopAiDeveloperSprint'] = createDeveloperSprintTool(client);
+
+  return tools;
+}
+
+/**
+ * forloopAiDeveloperSprint - Trigger developer agent for sprint work
+ * Triggers the forLoopTaskSupervisor agent via EventBridge → Step Functions → ECS
+ */
+function createDeveloperSprintTool(client: ForLoopAPIClient) {
+  return tool({
+    description: 'Trigger forLoopTaskSupervisor agent to execute sprint work. This sends stories to the developer agent for implementation via EventBridge → Step Functions → ECS Fargate.',
+    args: {
+      sprintId: tool.schema.number()
+        .describe('Sprint ID to execute'),
+      message: tool.schema.string()
+        .optional()
+        .describe('Optional instructions for the developer agent')
+        .default('Start implementing the sprint stories assigned to the developer agent'),
+    },
+    async execute(args, _context) {
+      const tokenResult = await validateToken();
+      if (!tokenResult.valid) {
+        return tokenResult.error;
+      }
+
+      try {
+        console.log('[forloopAiDeveloperSprint] Triggering developer agent', {
+          sprintId: args.sprintId,
+        });
+
+        const response = await client.chatWithAI({
+          sprintId: args.sprintId,
+          message: args.message || 'Start implementing the sprint stories assigned to the developer agent',
+          selectedAgentKey: 'forLoopTaskSupervisor',
+          type: 'developer.sprint',
+          metadata: { channel: 'developer_sprint' },
+        });
+
+        const taskId = response.taskId || response.id || 'unknown';
+        const trackingId = response.trackingId || 'unknown';
+
+        return `🚀 Developer sprint triggered for execution
+
+**Execution Details:**
+- Task ID: \`${taskId}\`
+- Tracking ID: \`${trackingId}\`
+- Sprint: #${args.sprintId}
+- Agent: forLoopTaskSupervisor
+
+**What will happen:**
+1. Sprint lock is acquired
+2. ECS Fargate task starts with forLoopTaskSupervisor agent
+3. Agent fetches sprint stories and processes them
+4. Sub-agents are dispatched: forLoopDeveloper (code), forLoopTester (validation), forLoopDevops (deploy)
+5. Sprint knowledge (knowledge-application.md) is updated
+6. PR is created and auto-merged to develop
+7. You'll be notified by email when complete
+
+**Monitor Progress:**
+- Check the ForLoop dashboard for story status updates
+- Wait for email notification upon completion`
+      } catch (error: any) {
+        console.error('[forloopAiDeveloperSprint] Failed to trigger developer', error)
+        return `❌ Failed to trigger forLoopTaskSupervisor: ${error.message}`
+      }
+    },
+  });
+}

package/plugins/tools/developer-status-tool.ts

@@ -0,0 +1,97 @@
+import { tool } from '@opencode-ai/plugin';
+import { ForLoopAPIClient } from '../capabilities/api-client';
+import { resolveSprintId } from '../capabilities/context-resolver';
+import { validateToken } from '../capabilities/auth';
+
+const SFN_ICONS: Record<string, string> = {
+  RUNNING: '🚀',
+  SUCCEEDED: '✅',
+  FAILED: '❌',
+  TIMED_OUT: '⏰',
+  ABORTED: '🛑',
+  NOT_FOUND: '❓',
+  ERROR: '⚠️',
+};
+
+export function createDeveloperStatusTool(client: ForLoopAPIClient) {
+  return tool({
+    description: 'Check the status of a running developer task (Step Functions execution + story progress). Use when you want to know if a dispatched developer sprint is still running, completed, or failed.',
+    args: {
+      sprintId: tool.schema.number()
+        .optional()
+        .describe('Target sprint ID (auto-detected via env/branch/manifest)'),
+    },
+    async execute(args, context) {
+      const tokenResult = await validateToken();
+      if (!tokenResult.valid) {
+        return tokenResult.error;
+      }
+      client.setToken?.(tokenResult.token);
+
+      const resolution = await resolveSprintId(args.sprintId, context.directory);
+      if (!resolution.sprintId) {
+        return '❌ No sprint ID available. Provide sprintId or set FORLOOP_SPRINT_ID or ensure ~/.forloop/manifest.json has activeSprintId.';
+      }
+
+      try {
+        const status = await client.getDeveloperStatus(resolution.sprintId);
+
+        if (!status.hasActiveTask) {
+          const sprint = status.sprint || {};
+          return [
+            '❌ No active developer task',
+            '',
+            `Sprint #${resolution.sprintId}: ${sprint.storiesDone || 0}/${sprint.storiesTotal || 0} stories done`,
+          ].join('\n');
+        }
+
+        const task = status.task || {};
+        const exec = status.execution || {};
+        const sprint = status.sprint || {};
+        const execIcon = SFN_ICONS[exec.status] || '❓';
+
+        const lines = [
+          `${execIcon} Developer Task: ${exec.status}`,
+          '',
+          `**Sprint**: #${resolution.sprintId}`,
+          `**Task Status**: ${task.status} (${task.id ? task.id.substring(0, 8) : '?'})`,
+        ];
+
+        if (exec.startedAt) {
+          lines.push(`**Started**: ${new Date(exec.startedAt).toLocaleString()}`);
+        }
+
+        if (exec.status === 'RUNNING') {
+          const started = new Date(exec.startedAt).getTime();
+          const elapsed = Math.floor((Date.now() - started) / 1000);
+          const minutes = Math.floor(elapsed / 60);
+          const seconds = elapsed % 60;
+          lines.push(`**Elapsed**: ${minutes}m ${seconds}s`);
+        }
+
+        if (exec.stoppedAt) {
+          lines.push(`**Stopped**: ${new Date(exec.stoppedAt).toLocaleString()}`);
+        }
+
+        if (task.branchName) {
+          lines.push(`**Branch**: ${task.branchName}`);
+        }
+
+        if (task.errorMessage) {
+          lines.push(`**Error**: ${task.errorMessage}`);
+        }
+
+        if (exec.error) {
+          lines.push(`**SFN Error**: ${exec.error}`);
+        }
+
+        lines.push('');
+        lines.push(`**Sprint Progress**: ${sprint.storiesDone || 0}/${sprint.storiesTotal || 0} done, ${sprint.storiesInProgress || 0} in progress`);
+
+        return lines.join('\n');
+      } catch (error: any) {
+        return `❌ Error checking developer status: ${error.message}`;
+      }
+    },
+  });
+}

package/plugins/tools/file-tools.ts

@@ -0,0 +1,240 @@
+import { tool } from '@opencode-ai/plugin';
+import { ForLoopAPIClient } from '../capabilities/api-client';
+import { validateToken } from '../capabilities/auth';
+import * as fs from 'fs';
+import * as path from 'path';
+
+export function createFileUploadTool(client: ForLoopAPIClient) {
+  return tool({
+    description: 'Upload a file to a sprint (supports presigned S3 upload)',
+    args: {
+      filePath: tool.schema.string()
+        .describe('Local file path to upload'),
+      sprintId: tool.schema.number()
+        .describe('Target sprint ID'),
+      description: tool.schema.string()
+        .optional()
+        .describe('File description'),
+      folder: tool.schema.string()
+        .optional()
+        .describe('Folder path within sprint for S3 organization (e.g., "project", "docs", "meetings")'),
+      storyId: tool.schema.number()
+        .optional()
+        .describe('Link file to a story (e.g., doc_folder story for logical grouping)'),
+    },
+    async execute(args, _context) {
+      const tokenResult = await validateToken();
+      if (!tokenResult.valid) {
+        return tokenResult.error ?? '❌ No API token configured.';
+      }
+      client.setToken?.(tokenResult.token);
+
+      try {
+        // Check if file exists
+        if (!fs.existsSync(args.filePath)) {
+          return `❌ File not found: ${args.filePath}`;
+        }
+
+        // Read file
+        const fileContent = fs.readFileSync(args.filePath);
+        const fileName = path.basename(args.filePath);
+        const ext = path.extname(fileName);
+        const fileSize = fileContent.length;
+
+        // Determine content type
+        const mimeTypes: Record<string, string> = {
+          '.png': 'image/png',
+          '.jpg': 'image/jpeg',
+          '.jpeg': 'image/jpeg',
+          '.gif': 'image/gif',
+          '.pdf': 'application/pdf',
+          '.txt': 'text/plain',
+          '.md': 'text/markdown',
+          '.json': 'application/json',
+          '.csv': 'text/csv',
+          '.mp4': 'video/mp4',
+          '.mp3': 'audio/mpeg',
+        };
+        const contentType = mimeTypes[ext] || 'application/octet-stream';
+
+        // Get presigned URL
+        const presign = await client.createPresignedUpload({
+          sprintId: args.sprintId,
+          contentType,
+          originalName: fileName,
+          folder: args.folder,
+        });
+
+        const uploadResponse = await fetch(presign.uploadUrl, {
+          method: 'PUT',
+          headers: {
+            'Content-Type': contentType,
+            'Content-Length': String(fileSize),
+          },
+          body: fileContent,
+        });
+        if (!uploadResponse.ok) {
+          const text = await uploadResponse.text().catch(() => '');
+          return `❌ Upload failed (${uploadResponse.status}): ${text || uploadResponse.statusText}`;
+        }
+
+        // Complete upload
+        const complete = await client.completeUpload({
+          sprintId: args.sprintId,
+          fileName: presign.fileName,
+          originalName: fileName,
+          fileType: contentType,
+          size: fileSize,
+          x: 0,
+          y: 0,
+          folder: args.folder,
+          storyId: args.storyId,
+        });
+
+        const formatSize = (bytes: number) => {
+          if (bytes === 0) return '0 Bytes';
+          const k = 1024;
+          const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+          const i = Math.floor(Math.log(bytes) / Math.log(k));
+          return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+        };
+
+        return [
+          `✅ File uploaded successfully!`,
+          '',
+          `**File**: ${fileName}`,
+          `**Size**: ${formatSize(fileSize)}`,
+          `**URL**: ${complete.url}`,
+          args.description ? `**Description**: ${args.description}` : null,
+          args.folder ? `**Folder**: ${args.folder}` : null,
+          args.storyId ? `**Linked to Story**: #${args.storyId}` : null,
+        ].filter(Boolean).join('\n');
+      } catch (error: any) {
+        return `❌ Error: ${error.message}`;
+      }
+    },
+  });
+}
+
+export function createFileListTool(client: ForLoopAPIClient) {
+  return tool({
+    description: 'List files attached to a sprint',
+    args: {
+      sprintId: tool.schema.number()
+        .describe('Sprint ID to list files from'),
+    },
+    async execute(args, _context) {
+      const tokenResult = await validateToken();
+      if (!tokenResult.valid) {
+        return tokenResult.error ?? '❌ No API token configured.';
+      }
+      client.setToken?.(tokenResult.token);
+
+      try {
+        const files = await client.getSprintFiles(args.sprintId);
+        
+        if (files.length === 0) {
+          return '🗂️ No files found in this sprint.';
+        }
+
+        const formatSize = (bytes: number) => {
+          if (bytes === 0) return '0 Bytes';
+          const k = 1024;
+          const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+          const i = Math.floor(Math.log(bytes) / Math.log(k));
+          return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+        };
+
+        const lines: string[] = [`🗂️ Files in Sprint #${args.sprintId}:`, ''];
+        
+        for (const file of files) {
+          const size = formatSize(file.size);
+          const uploadedBy = file.uploader?.name || file.uploaderId ? `by ${file.uploader?.name || `User #${file.uploaderId}`}` : '';
+          const date = file.createdAt ? new Date(file.createdAt).toLocaleDateString() : '';
+          
+          lines.push(`📎 **${file.originalName || file.filename}**`);
+          lines.push(`   Size: ${size} | Type: ${file.fileType}`);
+          lines.push(`   Uploaded: ${date} ${uploadedBy}`);
+          lines.push(`   URL: ${file.url}`);
+          lines.push('');
+        }
+
+        return lines.join('\n');
+      } catch (error: any) {
+        return `❌ Error: ${error.message}`;
+      }
+    },
+  });
+}
+
+export function createFileDeleteTool(client: ForLoopAPIClient) {
+  return tool({
+    description: 'Delete a file from a sprint (permanent action)',
+    args: {
+      fileId: tool.schema.number()
+        .describe('File ID to delete'),
+      confirm: tool.schema.boolean()
+        .default(false)
+        .describe('Confirm deletion'),
+    },
+    async execute(args, _context) {
+      const tokenResult = await validateToken();
+      if (!tokenResult.valid) {
+        return tokenResult.error ?? '❌ No API token configured.';
+      }
+      client.setToken?.(tokenResult.token);
+
+      if (!args.confirm) {
+        return [
+          '⚠️ **Warning**: This action is permanent and cannot be undone!',
+          '',
+          'Use `--confirm true` to proceed with deletion.',
+        ].join('\n');
+      }
+
+      try {
+        await client.deleteFile(args.fileId);
+
+        return `✅ File #${args.fileId} deleted successfully.`;
+      } catch (error: any) {
+        return `❌ Error: ${error.message}`;
+      }
+    },
+  });
+}
+
+export function createFileDownloadUrlTool(client: ForLoopAPIClient) {
+  return tool({
+    description: 'Get a download URL for a file',
+    args: {
+      fileId: tool.schema.number()
+        .describe('File ID to download'),
+    },
+    async execute(args, _context) {
+      const tokenResult = await validateToken();
+      if (!tokenResult.valid) {
+        return tokenResult.error ?? '❌ No API token configured.';
+      }
+      client.setToken?.(tokenResult.token);
+
+      try {
+        // Log file read (tracks access)
+        await client.logFileRead(args.fileId);
+
+        // Get download URL
+        const download = await client.getFileDownloadUrl(args.fileId);
+
+        return [
+          `📥 Download URL`,
+          '',
+          `**File ID**: ${args.fileId}`,
+          `**URL**: ${download.url}`,
+          '',
+          '⚠️ This URL may expire. Download the file soon.',
+        ].join('\n');
+      } catch (error: any) {
+        return `❌ Error: ${error.message}`;
+      }
+    },
+  });
+}

package/plugins/tools/folder-tools.ts

@@ -0,0 +1,75 @@
+import { tool } from '@opencode-ai/plugin';
+import { ForLoopAPIClient } from '../capabilities/api-client';
+import { validateToken } from '../capabilities/auth';
+import { resolveSprintId } from '../capabilities/context-resolver';
+
+export function createDocFolderTool(client: ForLoopAPIClient) {
+  return tool({
+    description: 'Create a document folder for storing files (S3 storage)',
+    args: {
+      sprintId: tool.schema.number()
+        .optional()
+        .describe('Target sprint ID (auto-detected from branch or env)'),
+      title: tool.schema.string()
+        .describe('Folder name'),
+      description: tool.schema.string()
+        .optional()
+        .describe('Folder description'),
+      permissions: tool.schema.enum(['public', 'team', 'private'])
+        .optional()
+        .default('team')
+        .describe('Folder access permissions'),
+    },
+    async execute(args, context) {
+      const tokenResult = await validateToken();
+      if (!tokenResult.valid) {
+        return tokenResult.error;
+      }
+      client.setToken?.(tokenResult.token);
+
+      try {
+        // Resolve sprint ID
+        const resolution = await resolveSprintId(args.sprintId, context.directory);
+        if (!resolution.sprintId) {
+          return [
+            '❌ No sprint ID provided.',
+            '',
+            'Please specify a sprint ID using one of these methods:',
+            '  1. Pass --sprintId flag',
+            '  2. Set FORLOOP_SPRINT_ID environment variable',
+            '  3. Use a git branch named sprint-XXX',
+          ].join('\n');
+        }
+
+        // Create doc folder story
+        const story = await client.createStory({
+          title: args.title,
+          description: args.description,
+          sprintId: resolution.sprintId,
+          type: 'doc_folder',
+          metadata: JSON.stringify({
+            permissions: args.permissions,
+          }),
+          status: 'todo',
+        });
+
+        const lines: string[] = [
+          `✅ Document folder created!`,
+          '',
+          `**#${story.id}**: ${story.title}`,
+          `**Sprint**: #${resolution.sprintId}`,
+          `**Type**: doc_folder`,
+          `**Permissions**: ${args.permissions}`,
+          '',
+          `📁 **Next Steps:**`,
+          `  1. Upload files with: forloopFileUpload --sprintId ${resolution.sprintId}`,
+          `  2. List files with: forloopFileList --sprintId ${resolution.sprintId}`,
+        ];
+
+        return lines.join('\n');
+      } catch (error: any) {
+        return `❌ Error: ${error.message}`;
+      }
+    },
+  });
+}