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

package/plugins/hooks/message-recorder.ts

@@ -0,0 +1,258 @@
+import { ForLoopAPIClient } from '../capabilities/api-client';
+import type { MessageRecord } from '../capabilities/api-client';
+import { isLambdaExecution } from '../capabilities/config';
+import fs from 'fs';
+import path from 'path';
+
+function normalizeAgentKey(agent: string): string {
+  if (/^forLoop[A-Z]/.test(agent)) {
+    return (
+      'forloop-' +
+      agent
+        .slice(7)
+        .replace(/([a-z])([A-Z])/g, '$1-$2')
+        .toLowerCase()
+    );
+  }
+  return agent
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+    .toLowerCase();
+}
+
+function buildConversationId(sprintId: number, agent: string, sessionId: string): string {
+  return `sprint:${sprintId}:agent:${normalizeAgentKey(agent)}:opencode:${sessionId}`;
+}
+
+function readActiveSprintId(): number | null {
+  try {
+    const home = process.env.HOME || '/tmp/home';
+    const manifestPath = path.join(home, '.forloop', 'manifest.json');
+    if (!fs.existsSync(manifestPath)) return null;
+    const raw = fs.readFileSync(manifestPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    const id = parsed?.activeSprintId;
+    return Number.isFinite(id) ? Number(id) : null;
+  } catch {
+    return null;
+  }
+}
+
+async function recordAssistantMessage(
+  client: ForLoopAPIClient,
+  data: MessageRecord,
+  attempts: number
+): Promise<void> {
+  for (let i = 0; i < attempts; i++) {
+    try {
+      if (i > 0) {
+        await new Promise((resolve) => setTimeout(resolve, 600 * i));
+      }
+      const result = await client.recordMessage(data);
+      if (result?.message !== 'no matching user message to update') return;
+      console.log(`[ForLoop] Retry ${i + 1}/${attempts}: user row not found yet`);
+    } catch (err: any) {
+      console.warn(`[ForLoop] Attempt ${i + 1}/${attempts} failed:`, err.message);
+      if (i === attempts - 1) {
+        console.warn('[ForLoop] Failed to record assistant message after all retries');
+      }
+    }
+  }
+}
+
+function extractTextFromParts(parts: any[]): string {
+  return parts
+    .filter((p: any) => p.type === 'text')
+    .map((p: any) => p.text || '')
+    .join('');
+}
+
+export function createChatMessageHook(client: ForLoopAPIClient) {
+  return async (input: any, output: any) => {
+    const sprintId = readActiveSprintId();
+    if (!sprintId) return;
+
+    // Only record on user's local machine; Lambda records via its own system
+    if (isLambdaExecution()) return;
+
+    const { sessionID, agent, model, messageID } = input;
+
+    // Only record messages with a model (indicates actual LLM processing,
+    // not system events like context compaction or summary generation)
+    if (!model || !model.providerID) return;
+
+    const { message, parts } = output;
+    const content = extractTextFromParts(parts);
+    if (!content) return;
+
+    const conversationId = buildConversationId(sprintId, agent || 'unknown', sessionID);
+
+    // Fire-and-forget: don't await - must not block the LLM from receiving the message
+    client.recordMessage({
+      sprintId,
+      sessionId: sessionID,
+      messageId: messageID || message.id,
+      conversationId,
+      role: 'user',
+      content,
+      agent: agent ? normalizeAgentKey(agent) : undefined,
+      model,
+      timestamp: message.time?.created ?? Date.now(),
+    }).catch((err: Error) => {
+      console.warn('[ForLoop] Failed to record user message:', err.message);
+    });
+  };
+}
+
+export function createEventHook(client: ForLoopAPIClient) {
+  const textBuffer = new Map<string, string>();
+  const readyToStream = new Set<string>(); // messageIDs that have passed the context phase
+
+  const writeStreamChunk = (sprintId: number, trackingId: string, taskId: string, text: string, done: boolean) => {
+    try {
+      const dir = '/tmp/forloop-stream';
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      const filePath = path.join(dir, `sprint_${sprintId}.json`);
+      let data: Record<string, any> = {};
+      try { data = JSON.parse(fs.readFileSync(filePath, 'utf8')); } catch {}
+      const existing = data[trackingId] || { index: 0 };
+      data[trackingId] = {
+        trackingId,
+        taskId: taskId || '',
+        sprintId,
+        text,
+        index: existing.index + 1,
+        done,
+        lastUpdated: Date.now(),
+      };
+      fs.writeFileSync(filePath, JSON.stringify(data));
+    } catch (err: any) {
+      console.warn('[ForLoop] Failed to write stream chunk:', err.message);
+    }
+  };
+
+  return async ({ event }: { event: { type: string; properties: any } }) => {
+    const sprintId = readActiveSprintId();
+    if (!sprintId) return;
+
+    const trackingId = process.env.FORLOOP_TRACKING_ID;
+    const taskId = process.env.FORLOOP_TASK_ID;
+    const isLambda = isLambdaExecution();
+
+    // Lambda with streaming: write chunks to file for parent process to poll
+    if (isLambda && trackingId && process.env.FORLOOP_STREAM_ENABLED === 'true') {
+      switch (event.type) {
+        case 'message.part.updated': {
+          const part = event.properties?.part;
+          const messageID = part?.messageID || '';
+          console.error('[stream-event] message.part.updated', { type: part?.type, trackingId, sprintId, messageID });
+
+          // Skip non-text parts — but track that this messageID is now in "generation" phase
+          if (!part || part.type !== 'text') {
+            if (messageID && (part?.type === 'reasoning' || part?.type === 'tool' || part?.type === 'step-start')) {
+              readyToStream.add(messageID);
+            }
+            break;
+          }
+
+          // Skip the initial context text (the conversation history loaded by the agent).
+          // Context text is massive (30K+ chars), assistant responses are small (<5K).
+          // Also track that we've seen the context and subsequent text is streamable.
+          const textLen = (part.text || '').length;
+          if (!readyToStream.has(messageID) && textLen > 5000) {
+            console.error('[stream-event] skipping context text', { trackingId, messageID, textLen });
+            readyToStream.add(messageID); // mark as past context
+            break;
+          }
+
+          readyToStream.add(messageID);
+          const current = textBuffer.get(part.messageID) || '';
+          textBuffer.set(part.messageID, part.text || current);
+          console.error('[stream-event] writing chunk', { trackingId, textLen });
+          writeStreamChunk(sprintId, trackingId, taskId || '', part.text || '', false);
+          break;
+        }
+        case 'message.updated': {
+          const info = event.properties?.info;
+          if (!info || info.role !== 'assistant') break;
+          const bufferedText = textBuffer.get(info.id);
+          if (!bufferedText) break;
+          writeStreamChunk(sprintId, trackingId, taskId || '', bufferedText, true);
+
+          const conversationId = buildConversationId(
+            sprintId,
+            info.agent || 'unknown',
+            info.sessionID
+          );
+          recordAssistantMessage(client, {
+            sprintId,
+            sessionId: info.sessionID,
+            messageId: info.id,
+            conversationId,
+            role: 'assistant',
+            content: bufferedText,
+            agent: info.agent ? normalizeAgentKey(info.agent) : undefined,
+            model: info.model,
+            timestamp: info.time?.created ?? Date.now(),
+          }, 3);
+          break;
+        }
+        case 'message.removed': {
+          const { sessionID, messageID } = event.properties || {};
+          if (!sessionID || !messageID) break;
+          textBuffer.delete(messageID);
+          client.removeMessage(messageID, sprintId, sessionID).catch((err: Error) => {
+            console.warn('[ForLoop] Failed to remove message:', err.message);
+          });
+          break;
+        }
+      }
+      return;
+    }
+
+    // Local machine: no streaming, just record messages
+    if (isLambda) return;
+
+    switch (event.type) {
+      case 'message.part.updated': {
+        const part = event.properties?.part;
+        if (!part || part.type !== 'text') return;
+        const current = textBuffer.get(part.messageID) || '';
+        textBuffer.set(part.messageID, part.text || current);
+        break;
+      }
+      case 'message.updated': {
+        const info = event.properties?.info;
+        if (!info || info.role !== 'assistant') return;
+        const bufferedText = textBuffer.get(info.id);
+        if (!bufferedText) return;
+        const conversationId = buildConversationId(
+          sprintId,
+          info.agent || 'unknown',
+          info.sessionID
+        );
+        recordAssistantMessage(client, {
+          sprintId,
+          sessionId: info.sessionID,
+          messageId: info.id,
+          conversationId,
+          role: 'assistant',
+          content: bufferedText,
+          agent: info.agent ? normalizeAgentKey(info.agent) : undefined,
+          model: info.model,
+          timestamp: info.time?.created ?? Date.now(),
+        }, 3);
+        break;
+      }
+      case 'message.removed': {
+        const { sessionID, messageID } = event.properties || {};
+        if (!sessionID || !messageID) return;
+        textBuffer.delete(messageID);
+        client.removeMessage(messageID, sprintId, sessionID).catch((err: Error) => {
+          console.warn('[ForLoop] Failed to remove message:', err.message);
+        });
+        break;
+      }
+    }
+  };
+}

package/plugins/hooks/shell-env.ts

@@ -0,0 +1,62 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { getConfig } from '../capabilities/config';
+
+const execAsync = promisify(exec);
+
+interface ShellEnvInput {
+  directory?: string;
+}
+
+interface ShellEnvOutput {
+  env: Record<string, string>;
+}
+
+export async function injectEnvironment(
+  input: ShellEnvInput,
+  output: ShellEnvOutput
+): Promise<void> {
+  const tokenPath = path.join(
+    process.env.HOME || process.env.USERPROFILE || '.',
+    '.config',
+    'forloop',
+    'tokens.json'
+  );
+
+  let token: string | null = null;
+  try {
+    const content = await fs.readFile(tokenPath, 'utf-8');
+    const tokens = JSON.parse(content);
+    const profile = process.env.FORLOOP_TOKEN_PROFILE;
+    token = (profile && tokens.profiles?.[profile]) || tokens.default || null;
+  } catch (error: any) {
+    if (error.code !== 'ENOENT') {
+      console.warn('[ForLoop] Error reading token file:', error.message);
+    }
+  }
+
+  if (!token) {
+    console.warn('[ForLoop] Token not configured');
+    return;
+  }
+
+  const config = getConfig();
+  output.env.FORLOOP_API_URL = config.apiUrl;
+  output.env.FORLOOP_TOKEN_SET = 'true';
+
+  try {
+    const result = await execAsync('git rev-parse --abbrev-ref HEAD', {
+      cwd: input.directory,
+    });
+    const branch = result.stdout.trim();
+    const match = branch.match(/sprint-(\d+)/);
+    
+    if (match) {
+      output.env.FORLOOP_SPRINT_ID = match[1];
+      console.log(`[ForLoop] Detected sprint ${match[1]} from branch ${branch}`);
+    }
+  } catch (error) {
+  }
+}

package/plugins/tools/agent-sprint-tools.ts

@@ -0,0 +1,100 @@
+import { tool } from '@opencode-ai/plugin';
+import { ForLoopAPIClient } from '../capabilities/api-client';
+import { resolveSprintId } from '../capabilities/context-resolver';
+import { validateToken } from '../capabilities/auth';
+
+export function createAgentListTool(client: ForLoopAPIClient) {
+  return tool({
+    description: 'List all available AI agents in the catalog',
+    args: {},
+    async execute(_args, _context) {
+      const tokenResult = await validateToken();
+      if (!tokenResult.valid) {
+        return tokenResult.error;
+      }
+      client.setToken?.(tokenResult.token);
+
+      try {
+        const agents = await client.listAiAgents();
+
+        if (agents.length === 0) {
+          return 'No AI agents found in the catalog.';
+        }
+
+        const lines = [
+          '🤖 Available AI Agents:',
+          '',
+        ];
+
+        for (const agent of agents) {
+          const defaultBadge = agent.defaultEnabled ? ' (default enabled)' : '';
+          lines.push(`**${agent.key}** - ${agent.name}${defaultBadge}`);
+          lines.push(`  ${agent.description}`);
+          lines.push(`  Category: ${agent.category || 'N/A'}`);
+          lines.push('');
+        }
+
+        return lines.join('\n');
+      } catch (error: any) {
+        return `❌ Error: ${error.message}`;
+      }
+    },
+  });
+}
+
+export function createSprintAiAgentsUpdateTool(client: ForLoopAPIClient) {
+  return tool({
+    description: 'Enable or disable AI agents for a sprint',
+    args: {
+      sprintId: tool.schema.number()
+        .optional()
+        .describe('Target sprint ID (uses active sprint if not provided)'),
+      enabledAgentKeys: tool.schema.array(tool.schema.string())
+        .describe('Array of agent keys to enable for this sprint'),
+    },
+    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 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');
+      }
+
+      try {
+        const agentKeys = args.enabledAgentKeys.filter(Boolean);
+        
+        if (agentKeys.length === 0) {
+          return '❌ No agent keys provided. Please specify at least one agent key to enable.';
+        }
+
+        const sprintAiAgents = await client.updateSprintAiAgents(resolution.sprintId, agentKeys);
+
+        const lines = [
+          `✅ Updated AI agents for sprint #${resolution.sprintId}`,
+          '',
+          'Enabled agents:',
+        ];
+
+        for (const sprintAgent of sprintAiAgents) {
+          lines.push(`  - ${sprintAgent.agent.name} (${sprintAgent.agentKey})`);
+        }
+
+        return lines.join('\n');
+      } catch (error: any) {
+        return `❌ Error: ${error.message}`;
+      }
+    },
+  });
+}

package/plugins/tools/agent-suggestion-tools.ts

@@ -0,0 +1,275 @@
+import { tool } from '@opencode-ai/plugin';
+import { ForLoopAPIClient } from '../capabilities/api-client';
+import { resolveSprintId } from '../capabilities/context-resolver';
+import { validateToken } from '../capabilities/auth';
+
+export function createAgentSuggestTool(client: ForLoopAPIClient) {
+  return tool({
+    description: 'Get AI suggestions for story breakdowns, estimates, and planning',
+    args: {
+      type: tool.schema.enum([
+        'breakdown',
+        'estimate',
+        'acceptance_criteria',
+        'test_cases',
+        'related',
+        'sprint_planning',
+      ]).describe('Type of suggestion needed'),
+      sprintId: tool.schema.number()
+        .optional()
+        .describe('Sprint ID for context'),
+      storyId: tool.schema.number()
+        .optional()
+        .describe('Story ID to analyze'),
+      query: tool.schema.string()
+        .optional()
+        .describe('Specific question or requirement'),
+    },
+    async execute(args, _context) {
+      const tokenResult = await validateToken();
+      if (!tokenResult.valid) {
+        return tokenResult.error;
+      }
+      client.setToken?.(tokenResult.token);
+
+      if (!args.sprintId && !args.storyId) {
+        return [
+          '❌ Please provide sprintId or storyId',
+          '',
+          'Examples:',
+          '  forloopAgentSuggest --type breakdown --sprintId 123',
+          '  forloopAgentSuggest --type estimate --storyId 456',
+        ].join('\n');
+      }
+
+      try {
+        const response = await client.getAgentSuggestions({
+          sprintId: args.sprintId,
+          storyId: args.storyId,
+          type: args.type,
+          query: args.query,
+        });
+
+        const lines = [
+          `🤖 AI Suggestions (${response.agentKey})`,
+          `Confidence: ${(response.confidence * 100).toFixed(0)}%`,
+          '',
+          '**Suggestions:**',
+          '',
+        ];
+
+        for (const suggestion of response.suggestions) {
+          lines.push(`- ${suggestion}`);
+        }
+
+        return lines.join('\n');
+      } catch (error: any) {
+        return `❌ Error: ${error.message}`;
+      }
+    },
+  });
+}
+
+export function createStoryBreakdownTool(client: ForLoopAPIClient) {
+  return tool({
+    description: 'Break down a story into actionable subtasks',
+    args: {
+      storyId: tool.schema.number()
+        .describe('Story ID to break down'),
+    },
+    async execute(args, _context) {
+      const tokenResult = await validateToken();
+      if (!tokenResult.valid) {
+        return tokenResult.error;
+      }
+      client.setToken?.(tokenResult.token);
+
+      try {
+        const breakdown = await client.getStoryBreakdown(args.storyId);
+
+        const lines = [
+          `📋 Story Breakdown: #${breakdown.storyId}`,
+          `**${breakdown.title}**`,
+          '',
+          '**Subtasks to consider:**',
+          '',
+        ];
+
+        for (let i = 0; i < breakdown.breakdown.length; i++) {
+          lines.push(`${i + 1}. ${breakdown.breakdown[i]}`);
+        }
+
+        lines.push('');
+        lines.push(`💡 Generated by ${breakdown.agentKey}`);
+
+        return lines.join('\n');
+      } catch (error: any) {
+        return `❌ Error: ${error.message}`;
+      }
+    },
+  });
+}
+
+export function createStoryEstimateTool(client: ForLoopAPIClient) {
+  return tool({
+    description: 'Get AI-powered story point estimates',
+    args: {
+      storyId: tool.schema.number()
+        .describe('Story ID to estimate'),
+    },
+    async execute(args, _context) {
+      const tokenResult = await validateToken();
+      if (!tokenResult.valid) {
+        return tokenResult.error;
+      }
+      client.setToken?.(tokenResult.token);
+
+      try {
+        const estimate = await client.getStoryEstimate(args.storyId);
+
+        const lines = [
+          `⏱️ Story Estimate: #${estimate.storyId}`,
+          `**${estimate.title}**`,
+          '',
+          `Current Points: ${estimate.currentPoints || 'Not set'}`,
+          `Suggested Points: ${estimate.suggestedPoints}`,
+          '',
+          '**Estimation rationale:**',
+          '',
+        ];
+
+        for (const item of estimate.estimates) {
+          lines.push(`- ${item}`);
+        }
+
+        return lines.join('\n');
+      } catch (error: any) {
+        return `❌ Error: ${error.message}`;
+      }
+    },
+  });
+}
+
+export function createConversationHistoryTool(client: ForLoopAPIClient) {
+  return tool({
+    description: 'View conversation history with AI agents from opencode sessions',
+    args: {
+      sprintId: tool.schema.number()
+        .optional()
+        .describe('Filter by sprint'),
+      limit: tool.schema.number()
+        .min(1)
+        .max(200)
+        .default(50)
+        .describe('Number of messages to retrieve'),
+    },
+    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);
+      const sprintId = resolution.sprintId || args.sprintId;
+
+      try {
+        const history = await client.getConversationHistory({
+          sprintId,
+          limit: args.limit,
+        });
+
+        const messages = history.messages || [];
+        if (messages.length === 0) {
+          return 'No conversation history found.';
+        }
+
+        const lines = [
+          `💬 Conversation History (${history.total || messages.length} total)`,
+          '',
+        ];
+
+        for (const msg of messages.slice(0, args.limit)) {
+          const preview = (msg.userMessage || 'No message').substring(0, 80);
+          const hasResponse = msg.agentResponse && msg.agentResponse.trim();
+
+          lines.push(`📌 **${preview}**${preview.length >= 80 ? '...' : ''}`);
+
+          if (msg.conversationId) {
+            const agentMatch = msg.conversationId.match(/agent:([^:]+)/);
+            if (agentMatch) {
+              lines.push(`   Agent: ${agentMatch[1]} | ${formatDate(msg.timestamp)}`);
+            } else {
+              lines.push(`   ${formatDate(msg.timestamp)}`);
+            }
+          } else {
+            lines.push(`   ${formatDate(msg.timestamp)}`);
+          }
+
+          if (hasResponse) {
+            const respPreview = msg.agentResponse.substring(0, 100);
+            lines.push(`   → ${respPreview}${msg.agentResponse.length > 100 ? '...' : ''}`);
+          }
+
+          lines.push('');
+        }
+
+        return lines.join('\n');
+      } catch (error: any) {
+        return `❌ Error: ${error.message}`;
+      }
+    },
+  });
+}
+
+export function createClearHistoryTool(client: ForLoopAPIClient) {
+  return tool({
+    description: 'Clear opencode conversation history for a sprint',
+    args: {
+      sprintId: tool.schema.number()
+        .optional()
+        .describe('Clear only for specific sprint'),
+      confirm: tool.schema.boolean()
+        .default(false)
+        .describe('Confirm deletion'),
+    },
+    async execute(args, context) {
+      const tokenResult = await validateToken();
+      if (!tokenResult.valid) {
+        return tokenResult.error;
+      }
+      client.setToken?.(tokenResult.token);
+
+      if (!args.confirm) {
+        return [
+          '⚠️ Warning: This will permanently delete conversation history.',
+          '',
+          'Use --confirm true to proceed.',
+          'Or specify --sprintId to delete only for a specific sprint.',
+        ].join('\n');
+      }
+
+      const resolution = await resolveSprintId(args.sprintId, context.directory);
+      const sprintId = resolution.sprintId || args.sprintId;
+
+      try {
+        const result = await client.clearConversationHistory({
+          sprintId,
+        });
+
+        return `✅ Deleted ${result.count} messages successfully.`;
+      } catch (error: any) {
+        return `❌ Error: ${error.message}`;
+      }
+    },
+  });
+}
+
+function formatDate(dateString: string): string {
+  return new Date(dateString).toLocaleDateString('en-US', {
+    month: 'short',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  });
+}