@forloop-cc/forloop-opencode-plugin-planner 2.2.11 → 2.2.13

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@forloop-cc/forloop-opencode-plugin-planner",
-  "version": "2.2.11",
+  "version": "2.2.13",
   "description": "ForLoop integration plugin for opencode — Sprint, story, and agent tools for the ForLoop platform",
   "type": "module",
   "license": "MIT",

package/plugins/capabilities/api-client.ts

@@ -23,6 +23,9 @@ interface ClientConfig {
 export interface SprintOptions {
   includeStories?: boolean;
   includeFiles?: boolean;
+  allStories?: boolean;
+  subSprintId?: number;
+  includeSubSprints?: boolean;
 }
 
 export interface ListSprintsParams {
@@ -259,6 +262,9 @@ export class ForLoopAPIClient {
       includeStories: options?.includeStories !== false ? 'true' : 'false',
       includeFiles: options?.includeFiles !== false ? 'true' : 'false',
     });
+    if (options?.allStories) query.set('allStories', 'true');
+    if (options?.subSprintId) query.set('subSprintId', String(options.subSprintId));
+    if (options?.includeSubSprints) query.set('includeSubSprints', 'true');
     return this.request(`/api/opencode/sprints/${id}?${query}`);
   }
 
@@ -309,6 +315,39 @@ export class ForLoopAPIClient {
     });
   }
 
+  async getSubSprints(sprintId: number): Promise<any[]> {
+    return this.request(`/api/opencode/sprints/${sprintId}/sub-sprints`);
+  }
+
+  async createSubSprint(sprintId: number, data: {
+    title?: string;
+    startDate: string;
+    endDate: string;
+  }): Promise<any> {
+    return this.request(`/api/opencode/sprints/${sprintId}/sub-sprints`, {
+      method: 'POST',
+      body: JSON.stringify(data),
+    });
+  }
+
+  async updateSubSprint(subSprintId: number, data: Partial<{
+    title: string;
+    startDate: string;
+    endDate: string;
+    status: 'planned' | 'in_progress' | 'completed';
+  }>): Promise<any> {
+    return this.request(`/api/opencode/sub-sprints/${subSprintId}`, {
+      method: 'PUT',
+      body: JSON.stringify(data),
+    });
+  }
+
+  async deleteSubSprint(subSprintId: number): Promise<void> {
+    await this.request(`/api/opencode/sub-sprints/${subSprintId}`, {
+      method: 'DELETE',
+    });
+  }
+
   async addStoryComment(storyId: number, body: string, authorAgentKey?: string): Promise<any> {
     const payload: Record<string, unknown> = { body };
     if (authorAgentKey) payload.authorAgentKey = authorAgentKey;
@@ -521,6 +560,10 @@ export class ForLoopAPIClient {
     });
   }
 
+  /**
+   * @deprecated Use writeConversationEvent() for new integrations.
+   * Kept for backward compatibility with existing plugin hooks.
+   */
   async recordMessage(data: MessageRecord): Promise<any> {
     return this.request('/api/opencode/messages', {
       method: 'POST',
@@ -535,6 +578,13 @@ export class ForLoopAPIClient {
     });
   }
 
+  async writeConversationEvent(data: WriteConversationEventInput): Promise<any> {
+    return this.request('/api/opencode/conversations/events', {
+      method: 'POST',
+      body: JSON.stringify(data),
+    });
+  }
+
   async sendStreamChunk(data: {
     taskId: string;
     trackingId: string;
@@ -556,6 +606,21 @@ export interface AgentSuggestionRequest {
   query?: string;
 }
 
+export interface WriteConversationEventInput {
+  operation: 'append_turn' | 'start_turn' | 'complete_turn' | 'delete_turn';
+  sprintId: number;
+  targetAgent: string;
+  actor: { senderType: string; senderId: string };
+  conversationId?: string;
+  sessionId?: string;
+  turnId?: string;
+  messageId?: string;
+  requestId?: string;
+  userMessage?: string;
+  agentResponse?: string;
+  metadata?: Record<string, unknown>;
+}
+
 export interface ConversationHistoryParams {
   sprintId?: number;
   limit?: number;

package/plugins/forloop-plugin.ts

@@ -7,6 +7,10 @@ import {
   createSprintCreateTool,
   createSprintUpdateTool,
   createSprintDeleteTool,
+  createSubSprintListTool,
+  createSubSprintCreateTool,
+  createSubSprintUpdateTool,
+  createSubSprintDeleteTool,
 } from './tools/sprint-tools';
 import { 
   createStoryCreateTool, 
@@ -102,6 +106,12 @@ export default async (ctx: any) => {
       'forloopSprintUpdate': createSprintUpdateTool(client),
       'forloopSprintDelete': createSprintDeleteTool(client),
       
+      // Sub-Sprint (Iteration) Operations
+      'forloopSubSprintList'  : createSubSprintListTool(client),
+      'forloopSubSprintCreate' : createSubSprintCreateTool(client),
+      'forloopSubSprintUpdate' : createSubSprintUpdateTool(client),
+      'forloopSubSprintDelete' : createSubSprintDeleteTool(client),
+      
       // Story Operations
       'forloopStoryCreate': createStoryCreateTool(client),
       'forloopStoryGet': createStoryGetTool(client),

package/plugins/hooks/message-recorder.ts

@@ -1,29 +1,31 @@
 import { ForLoopAPIClient } from '../capabilities/api-client';
-import type { MessageRecord } from '../capabilities/api-client';
+import type { WriteConversationEventInput } from '../capabilities/api-client';
 import { isLambdaExecution } from '../capabilities/config';
 import fs from 'fs';
 import path from 'path';
 
+interface PendingUserMessage {
+  messageId: string;
+  content: string;
+  agent: string;
+  model: any;
+  timestamp: number;
+}
+
 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();
+  return agent;
+}
+
+function getActor(): { senderType: string; senderId: string } {
+  return {
+    senderType: process.env.FORLOOP_SENDER_TYPE || 'user',
+    senderId: process.env.FORLOOP_SENDER_ID || 'unknown',
+  };
 }
 
 function buildConversationId(sprintId: number, agent: string, sessionId: string): string {
-  const senderType = process.env.FORLOOP_SENDER_TYPE || 'user';
-  const senderId = process.env.FORLOOP_SENDER_ID || 'unknown';
-  return `sprint:${sprintId}:agent:${agent}:${senderType}:${senderId}`;
+  const actor = getActor();
+  return `sprint:${sprintId}:agent:${agent}:${actor.senderType}:${actor.senderId}`;
 }
 
 function readActiveSprintId(): number | null {
@@ -40,9 +42,11 @@ function readActiveSprintId(): number | null {
   }
 }
 
-async function recordAssistantMessage(
+const userMessageBuffer = new Map<string, PendingUserMessage>();
+
+async function writeConversationTurn(
   client: ForLoopAPIClient,
-  data: MessageRecord,
+  input: WriteConversationEventInput,
   attempts: number
 ): Promise<void> {
   for (let i = 0; i < attempts; i++) {
@@ -50,20 +54,15 @@ async function recordAssistantMessage(
       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') {
-        console.log(`[ForLoop] No matching user message — user message may not be recorded yet`);
-        return;
+      const result = await client.writeConversationEvent(input);
+      if (!result?.ok) {
+        console.warn(`[ForLoop] Write event returned not ok: ${result?.error || 'unknown'}`);
       }
-      // After recording, try summarization (no-op if < 30 rounds)
-      client.summarizeConversation(data.sprintId).catch((err: Error) => {
-        console.warn('[ForLoop] Summarization trigger failed:', err.message);
-      });
       return;
     } catch (err: any) {
-      console.warn(`[ForLoop] Attempt ${i + 1}/${attempts} failed:`, err.message);
+      console.warn(`[ForLoop] Write event attempt ${i + 1}/${attempts} failed:`, err.message);
       if (i === attempts - 1) {
-        console.warn('[ForLoop] Failed to record assistant message after all retries');
+        console.warn('[ForLoop] Failed to write conversation event after all retries');
       }
     }
   }
@@ -85,7 +84,6 @@ export function createChatMessageHook(client: ForLoopAPIClient) {
     const { message, parts } = output;
     const content = extractTextFromParts(parts);
 
-    // Log incoming user message for debug visibility (Lambda)
     if (content && messageID) {
       console.log(`[ForLoop] REQUEST — user message (${content.length} chars)`, {
         sprintId,
@@ -95,25 +93,15 @@ export function createChatMessageHook(client: ForLoopAPIClient) {
       });
     }
 
-    // Only record messages with a model (indicates actual LLM processing,
-    // not system events like context compaction or summary generation)
     if (!model || !model.providerID) return;
+    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,
+    userMessageBuffer.set(sessionID, {
       messageId: messageID || message.id,
-      conversationId,
-      role: 'user',
       content,
-      agent: agent ? normalizeAgentKey(agent) : undefined,
+      agent: agent || 'unknown',
       model,
       timestamp: message.time?.created ?? Date.now(),
-    }).catch((err: Error) => {
-      console.warn('[ForLoop] Failed to record user message:', err.message);
     });
   };
 }
@@ -198,21 +186,36 @@ export function createEventHook(client: ForLoopAPIClient) {
             preview: bufferedText.substring(0, 500),
           });
 
+          const pendingUserMsg = userMessageBuffer.get(info.sessionID);
+          userMessageBuffer.delete(info.sessionID);
+
+          if (!pendingUserMsg) {
+            console.log('[ForLoop] Skipping write — no buffered user message for this session (stream handler handles the save)');
+            break;
+          }
+
           const conversationId = buildConversationId(
             sprintId,
             info.agent || 'unknown',
             info.sessionID
           );
-          recordAssistantMessage(client, {
+          writeConversationTurn(client, {
+            operation: 'append_turn',
             sprintId,
+            targetAgent: info.agent ? normalizeAgentKey(info.agent) : 'unknown',
+            actor: getActor(),
+            conversationId,
             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(),
+            userMessage: pendingUserMsg.content,
+            agentResponse: bufferedText,
+            metadata: {
+              source: 'opencode-plugin',
+              agent: info.agent ? normalizeAgentKey(info.agent) : null,
+              model: info.model || null,
+              userMessageId: pendingUserMsg.messageId || null,
+              recordedAt: info.time?.created ?? Date.now(),
+            },
           }, 3);
           break;
         }
@@ -220,8 +223,17 @@ export function createEventHook(client: ForLoopAPIClient) {
           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);
+          const conversationId = buildConversationId(sprintId, 'unknown', sessionID);
+          client.writeConversationEvent({
+            operation: 'delete_turn',
+            sprintId,
+            targetAgent: 'forLoopPlanner',
+            actor: getActor(),
+            conversationId,
+            messageId: messageID,
+            metadata: { source: 'opencode-plugin' },
+          }).catch((err: Error) => {
+            console.warn('[ForLoop] Failed to delete conversation turn:', err.message);
           });
           break;
         }
@@ -243,21 +255,36 @@ export function createEventHook(client: ForLoopAPIClient) {
         if (!info || info.role !== 'assistant') return;
         const bufferedText = textBuffer.get(info.id);
         if (!bufferedText) return;
+        const pendingUserMsg = userMessageBuffer.get(info.sessionID);
+        userMessageBuffer.delete(info.sessionID);
+
+        if (!pendingUserMsg) {
+          console.log('[ForLoop] Skipping write — no buffered user message for this session');
+          break;
+        }
+
         const conversationId = buildConversationId(
           sprintId,
           info.agent || 'unknown',
           info.sessionID
         );
-        recordAssistantMessage(client, {
+        writeConversationTurn(client, {
+          operation: 'append_turn',
           sprintId,
+          targetAgent: info.agent ? normalizeAgentKey(info.agent) : 'unknown',
+          actor: getActor(),
+          conversationId,
           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(),
+          userMessage: pendingUserMsg.content,
+          agentResponse: bufferedText,
+          metadata: {
+            source: 'opencode-plugin',
+            agent: info.agent ? normalizeAgentKey(info.agent) : null,
+            model: info.model || null,
+            userMessageId: pendingUserMsg.messageId || null,
+            recordedAt: info.time?.created ?? Date.now(),
+          },
         }, 3);
         break;
       }
@@ -265,8 +292,17 @@ export function createEventHook(client: ForLoopAPIClient) {
         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);
+        const conversationId = buildConversationId(sprintId, 'unknown', sessionID);
+        client.writeConversationEvent({
+          operation: 'delete_turn',
+          sprintId,
+          targetAgent: 'forLoopPlanner',
+          actor: getActor(),
+          conversationId,
+          messageId: messageID,
+          metadata: { source: 'opencode-plugin' },
+        }).catch((err: Error) => {
+          console.warn('[ForLoop] Failed to delete conversation turn:', err.message);
         });
         break;
       }

package/plugins/tools/sprint-tools.ts

@@ -17,6 +17,9 @@ export function createSprintGetTool(client: ForLoopAPIClient) {
       includeFiles: tool.schema.boolean()
         .default(true)
         .describe('Include files in response'),
+      includeSubSprints: tool.schema.boolean()
+        .default(true)
+        .describe('Include sub-sprints array in response'),
     },
     async execute(args, context) {
       const tokenResult = await validateToken();
@@ -42,6 +45,7 @@ export function createSprintGetTool(client: ForLoopAPIClient) {
         const sprint = await client.getSprint(resolution.sprintId, {
           includeStories: args.includeStories,
           includeFiles: args.includeFiles,
+          includeSubSprints: args.includeSubSprints,
         });
 
         const lines = [
@@ -288,3 +292,145 @@ export function createSprintDeleteTool(client: ForLoopAPIClient) {
     },
   });
 }
+
+export function createSubSprintListTool(client: ForLoopAPIClient) {
+  return tool({
+    description: 'List all iterations (sub-sprints) within a sprint',
+    args: {
+      sprintId: tool.schema.number()
+        .optional()
+        .describe('Sprint ID (defaults to FORLOOP_SPRINT_ID env or current branch)'),
+    },
+    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 resolved. Use --sprintId, set FORLOOP_SPRINT_ID, or use a sprint-XXX branch.'
+      }
+      try {
+        const subSprints = await client.getSubSprints(resolution.sprintId)
+        if (subSprints.length === 0) {
+          return `Sprint #${resolution.sprintId} has no iterations yet.`
+        }
+        const lines = [`Iterations for sprint #${resolution.sprintId}:`, '']
+        for (const s of subSprints) {
+          const active = s.status === 'in_progress' ? ' ▶ ACTIVE' : ''
+          lines.push(
+            `  #${s.id}: ${s.title} | ${formatDate(s.startDate)} – ${formatDate(s.endDate)} | ${s.status}${active}`
+          )
+        }
+        return lines.join('\n')
+      } catch (error: any) {
+        return `Failed to list iterations: ${error.message}`
+      }
+    },
+  })
+}
+
+export function createSubSprintCreateTool(client: ForLoopAPIClient) {
+  return tool({
+    description: 'Create a new iteration (sub-sprint). The previously active iteration is auto-completed.',
+    args: {
+      sprintId: tool.schema.number()
+        .optional()
+        .describe('Sprint ID (defaults to FORLOOP_SPRINT_ID env or current branch)'),
+      title: tool.schema.string()
+        .optional()
+        .describe('Iteration title (auto-generates as "Sprint Title — Iteration N" if not provided)'),
+      startDate: tool.schema.string()
+        .describe('Start date (YYYY-MM-DD)'),
+      endDate: tool.schema.string()
+        .describe('End date (YYYY-MM-DD)'),
+    },
+    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 resolved. Use --sprintId, set FORLOOP_SPRINT_ID, or use a sprint-XXX branch.'
+      }
+      if (!args.startDate || !args.endDate) {
+        return 'startDate and endDate are required (YYYY-MM-DD format).'
+      }
+      try {
+        const subSprint = await client.createSubSprint(resolution.sprintId, {
+          title: args.title,
+          startDate: args.startDate,
+          endDate: args.endDate,
+        })
+        return `Iteration created: #${subSprint.id} "${subSprint.title}" (${formatDate(subSprint.startDate)} – ${formatDate(subSprint.endDate)}) status: ${subSprint.status}`
+      } catch (error: any) {
+        return `Failed to create iteration: ${error.message}`
+      }
+    },
+  })
+}
+
+export function createSubSprintUpdateTool(client: ForLoopAPIClient) {
+  return tool({
+    description: 'Update an iteration (sub-sprint) title, dates, or status. Activating an iteration (status: in_progress) auto-completes the previous one.',
+    args: {
+      subSprintId: tool.schema.number()
+        .describe('Sub-sprint ID to update'),
+      title: tool.schema.string()
+        .optional()
+        .describe('New iteration title'),
+      startDate: tool.schema.string()
+        .optional()
+        .describe('New start date (YYYY-MM-DD)'),
+      endDate: tool.schema.string()
+        .optional()
+        .describe('New end date (YYYY-MM-DD)'),
+      status: tool.schema.string()
+        .optional()
+        .describe('New status: planned, in_progress, or completed'),
+    },
+    async execute(args, context) {
+      const tokenResult = await validateToken()
+      if (!tokenResult.valid) return tokenResult.error
+      client.setToken?.(tokenResult.token)
+
+      if (!args.subSprintId) return 'subSprintId is required.'
+      try {
+        const updateData: Record<string, unknown> = {}
+        if (args.title !== undefined) updateData.title = args.title
+        if (args.startDate !== undefined) updateData.startDate = args.startDate
+        if (args.endDate !== undefined) updateData.endDate = args.endDate
+        if (args.status !== undefined) updateData.status = args.status
+        if (Object.keys(updateData).length === 0) return 'No update fields provided.'
+        const updated = await client.updateSubSprint(args.subSprintId, updateData)
+        return `Iteration updated: #${updated.id} "${updated.title}" status: ${updated.status}`
+      } catch (error: any) {
+        return `Failed to update iteration: ${error.message}`
+      }
+    },
+  })
+}
+
+export function createSubSprintDeleteTool(client: ForLoopAPIClient) {
+  return tool({
+    description: 'Soft-delete an iteration (sub-sprint). Linked stories retain their subSprintId and will not appear in default sprint views.',
+    args: {
+      subSprintId: tool.schema.number()
+        .describe('Sub-sprint ID to delete'),
+    },
+    async execute(args, context) {
+      const tokenResult = await validateToken()
+      if (!tokenResult.valid) return tokenResult.error
+      client.setToken?.(tokenResult.token)
+
+      if (!args.subSprintId) return 'subSprintId is required.'
+      try {
+        await client.deleteSubSprint(args.subSprintId)
+        return `Iteration #${args.subSprintId} deleted.`
+      } catch (error: any) {
+        return `Failed to delete iteration: ${error.message}`
+      }
+    },
+  })
+}