@posthog/agent 1.10.0 → 1.11.0

package/src/agent.ts

@@ -16,6 +16,7 @@ import { WorkflowRegistry } from './workflow-registry.js';
 import { StageExecutor } from './stage-executor.js';
 import { PromptBuilder } from './prompt-builder.js';
 import { TaskProgressReporter } from './task-progress-reporter.js';
+import { OpenAIExtractor, type ExtractedQuestion, type ExtractedQuestionWithAnswer } from './structured-extraction.js';
 
 export class Agent {
     private workingDirectory: string;
@@ -31,6 +32,8 @@ export class Agent {
     private workflowRegistry: WorkflowRegistry;
     private stageExecutor: StageExecutor;
     private progressReporter: TaskProgressReporter;
+    private promptBuilder: PromptBuilder;
+    private extractor?: OpenAIExtractor;
     private mcpServers?: Record<string, any>;
     public debug: boolean;
 
@@ -88,7 +91,7 @@ export class Agent {
         }
 
         this.workflowRegistry = new WorkflowRegistry(this.posthogAPI);
-        const promptBuilder = new PromptBuilder({
+        this.promptBuilder = new PromptBuilder({
             getTaskFiles: (taskId: string) => this.getTaskFiles(taskId),
             generatePlanTemplate: (vars) => this.templateManager.generatePlan(vars),
             posthogClient: this.posthogAPI,
@@ -97,12 +100,17 @@ export class Agent {
         this.stageExecutor = new StageExecutor(
             this.agentRegistry,
             this.logger,
-            promptBuilder,
+            this.promptBuilder,
             undefined, // eventHandler set via setEventHandler below
             this.mcpServers
         );
         this.stageExecutor.setEventHandler((event) => this.emitEvent(event));
         this.progressReporter = new TaskProgressReporter(this.posthogAPI, this.logger);
+        
+        // Initialize OpenAI extractor if API key is available
+        if (process.env.OPENAI_API_KEY) {
+            this.extractor = new OpenAIExtractor(this.logger.child('OpenAIExtractor'));
+        }
     }
 
     /**
@@ -328,6 +336,341 @@ export class Agent {
         this.emitEvent(this.adapter.createStatusEvent('stage_complete', { stage: stage.key }));
     }
 
+    // Adaptive task execution - 3-phase workflow (research → plan → build)
+    async runTask(taskOrId: Task | string, options: import('./types.js').TaskExecutionOptions = {}): Promise<void> {
+        await this._configureLlmGateway();
+
+        const task = typeof taskOrId === 'string' ? await this.fetchTask(taskOrId) : taskOrId;
+        const cwd = options.repositoryPath || this.workingDirectory;
+        const isCloudMode = options.isCloudMode ?? false;
+        const taskSlug = (task as any).slug || task.id;
+
+        this.logger.info('Starting adaptive task execution', { taskId: task.id, taskSlug, isCloudMode });
+
+        // Initialize progress reporter for task run tracking (needed for PR attachment)
+        await this.progressReporter.start(task.id, { totalSteps: 3 }); // 3 phases: research, plan, build
+        this.emitEvent(this.adapter.createStatusEvent('run_started', { runId: this.progressReporter.runId }));
+
+        // Phase 1: Branch check
+        const existingBranch = await this.gitManager.getTaskBranch(taskSlug);
+        if (!existingBranch) {
+            this.logger.info('Creating task branch', { taskSlug });
+            const branchName = `posthog/task-${taskSlug}`;
+            await this.gitManager.createOrSwitchToBranch(branchName);
+            this.emitEvent(this.adapter.createStatusEvent('branch_created', { branch: branchName }));
+            
+            // Initial commit
+            await this.fileManager.ensureGitignore();
+            await this.gitManager.addAllPostHogFiles();
+            if (isCloudMode) {
+                await this.gitManager.commitAndPush(`Initialize task ${taskSlug}`, { allowEmpty: true });
+            } else {
+                await this.gitManager.commitChanges(`Initialize task ${taskSlug}`);
+            }
+        } else {
+            this.logger.info('Switching to existing task branch', { branch: existingBranch });
+            await this.gitManager.switchToBranch(existingBranch);
+        }
+
+        // Phase 2: Research
+        const researchExists = await this.fileManager.readResearch(task.id);
+        if (!researchExists) {
+            this.logger.info('Starting research phase', { taskId: task.id });
+            this.emitEvent(this.adapter.createStatusEvent('phase_start', { phase: 'research' }));
+            
+            // Run research agent
+            const researchPrompt = await this.promptBuilder.buildResearchPrompt(task, cwd);
+            const { RESEARCH_SYSTEM_PROMPT } = await import('./agents/research.js');
+            const fullPrompt = RESEARCH_SYSTEM_PROMPT + '\n\n' + researchPrompt;
+            
+            const baseOptions: Record<string, any> = {
+                model: 'claude-sonnet-4-5-20250929',
+                cwd,
+                permissionMode: 'plan',
+                settingSources: ['local'],
+                mcpServers: this.mcpServers,
+            };
+
+            const response = query({
+                prompt: fullPrompt,
+                options: { ...baseOptions, ...(options.queryOverrides || {}) },
+            });
+
+            let researchContent = '';
+            for await (const message of response) {
+                this.emitEvent(this.adapter.createRawSDKEvent(message));
+                const transformed = this.adapter.transform(message);
+                if (transformed) {
+                    this.emitEvent(transformed);
+                }
+                if (message.type === 'assistant' && message.message?.content) {
+                    for (const c of message.message.content) {
+                        if (c.type === 'text' && c.text) researchContent += c.text + '\n';
+                    }
+                }
+            }
+
+            // Write research.md
+            if (researchContent.trim()) {
+                await this.fileManager.writeResearch(task.id, researchContent.trim());
+                this.logger.info('Research completed', { taskId: task.id });
+            }
+
+            // Commit research
+            await this.gitManager.addAllPostHogFiles();
+            
+            // Extract questions using structured output and save to questions.json
+            if (this.extractor) {
+                try {
+                    this.logger.info('Extracting questions from research.md', { taskId: task.id });
+                    const questions = await this.extractQuestionsFromResearch(task.id, false);
+                    
+                    this.logger.info('Questions extracted successfully', { taskId: task.id, count: questions.length });
+                    
+                    // Save questions.json
+                    await this.fileManager.writeQuestions(task.id, {
+                        questions,
+                        answered: false,
+                        answers: null,
+                    });
+                    
+                    this.logger.info('Questions saved to questions.json', { taskId: task.id });
+                    
+                    // Emit event for Array to pick up (local mode)
+                    if (!isCloudMode) {
+                        this.emitEvent({
+                            type: 'artifact',
+                            ts: Date.now(),
+                            kind: 'research_questions',
+                            content: questions,
+                        });
+                        this.logger.info('Emitted research_questions artifact event', { taskId: task.id });
+                    }
+                } catch (error) {
+                    this.logger.error('Failed to extract questions', { error: error instanceof Error ? error.message : String(error) });
+                    this.emitEvent({
+                        type: 'error',
+                        ts: Date.now(),
+                        message: `Failed to extract questions: ${error instanceof Error ? error.message : String(error)}`,
+                    });
+                }
+            } else {
+                this.logger.warn('OpenAI extractor not available (OPENAI_API_KEY not set), skipping question extraction');
+                this.emitEvent({
+                    type: 'status',
+                    ts: Date.now(),
+                    phase: 'extraction_skipped',
+                    message: 'Question extraction skipped - OPENAI_API_KEY not configured',
+                });
+            }
+            
+            if (isCloudMode) {
+                await this.gitManager.commitAndPush(`Research phase for ${task.title}`);
+            } else {
+                await this.gitManager.commitChanges(`Research phase for ${task.title}`);
+                this.emitEvent(this.adapter.createStatusEvent('phase_complete', { phase: 'research' }));
+                return; // Local mode: return to user
+            }
+        }
+
+        // Phase 3: Auto-answer questions (cloud mode only)
+        if (isCloudMode) {
+            const questionsData = await this.fileManager.readQuestions(task.id);
+            if (questionsData && !questionsData.answered) {
+                this.logger.info('Auto-answering research questions', { taskId: task.id });
+                
+                // Extract questions with recommended answers using structured output
+                if (this.extractor) {
+                    const questionsWithAnswers = await this.extractQuestionsFromResearch(task.id, true) as ExtractedQuestionWithAnswer[];
+                    
+                    // Save answers to questions.json
+                    await this.fileManager.writeQuestions(task.id, {
+                        questions: questionsWithAnswers.map(qa => ({
+                            id: qa.id,
+                            question: qa.question,
+                            options: qa.options,
+                        })),
+                        answered: true,
+                        answers: questionsWithAnswers.map(qa => ({
+                            questionId: qa.id,
+                            selectedOption: qa.recommendedAnswer,
+                            customInput: qa.justification,
+                        })),
+                    });
+                    
+                    this.logger.info('Auto-answers saved to questions.json', { taskId: task.id });
+                    await this.gitManager.addAllPostHogFiles();
+                    await this.gitManager.commitAndPush(`Answer research questions for ${task.title}`);
+                } else {
+                    this.logger.warn('OpenAI extractor not available, skipping auto-answer');
+                }
+            }
+        }
+
+        // Phase 4: Plan
+        const planExists = await this.readPlan(task.id);
+        if (!planExists) {
+            // Check if questions have been answered
+            const questionsData = await this.fileManager.readQuestions(task.id);
+            if (!questionsData || !questionsData.answered) {
+                this.logger.info('Waiting for user answers to research questions');
+                this.emitEvent(this.adapter.createStatusEvent('phase_complete', { phase: 'research_questions' }));
+                return; // Wait for user to answer questions
+            }
+
+            this.logger.info('Starting planning phase', { taskId: task.id });
+            this.emitEvent(this.adapter.createStatusEvent('phase_start', { phase: 'planning' }));
+            
+            // Build context with research + questions + answers
+            const research = await this.fileManager.readResearch(task.id);
+            let researchContext = '';
+            if (research) {
+                researchContext += `## Research Analysis\n\n${research}\n\n`;
+            }
+            
+            // Add questions and answers
+            researchContext += `## Implementation Decisions\n\n`;
+            const answers = questionsData.answers || [];
+            for (const question of questionsData.questions) {
+                const answer = answers.find((a: any) => a.questionId === question.id);
+                
+                researchContext += `### ${question.question}\n\n`;
+                if (answer) {
+                    researchContext += `**Selected:** ${answer.selectedOption}\n`;
+                    if (answer.customInput) {
+                        researchContext += `**Details:** ${answer.customInput}\n`;
+                    }
+                } else {
+                    this.logger.warn('No answer found for question', { questionId: question.id });
+                    researchContext += `**Selected:** Not answered\n`;
+                }
+                researchContext += '\n';
+            }
+            
+            // Run planning agent with full context
+            const planningPrompt = await this.promptBuilder.buildPlanningPrompt(task, cwd);
+            const { PLANNING_SYSTEM_PROMPT } = await import('./agents/planning.js');
+            const fullPrompt = PLANNING_SYSTEM_PROMPT + '\n\n' + planningPrompt + '\n\n' + researchContext;
+            
+            const baseOptions: Record<string, any> = {
+                model: 'claude-sonnet-4-5-20250929',
+                cwd,
+                permissionMode: 'plan',
+                settingSources: ['local'],
+                mcpServers: this.mcpServers,
+            };
+
+            const response = query({
+                prompt: fullPrompt,
+                options: { ...baseOptions, ...(options.queryOverrides || {}) },
+            });
+
+            let planContent = '';
+            for await (const message of response) {
+                this.emitEvent(this.adapter.createRawSDKEvent(message));
+                const transformed = this.adapter.transform(message);
+                if (transformed) {
+                    this.emitEvent(transformed);
+                }
+                if (message.type === 'assistant' && message.message?.content) {
+                    for (const c of message.message.content) {
+                        if (c.type === 'text' && c.text) planContent += c.text + '\n';
+                    }
+                }
+            }
+
+            // Write plan.md
+            if (planContent.trim()) {
+                await this.writePlan(task.id, planContent.trim());
+                this.logger.info('Plan completed', { taskId: task.id });
+            }
+
+            // Commit plan
+            await this.gitManager.addAllPostHogFiles();
+            if (isCloudMode) {
+                await this.gitManager.commitAndPush(`Planning phase for ${task.title}`);
+            } else {
+                await this.gitManager.commitChanges(`Planning phase for ${task.title}`);
+                this.emitEvent(this.adapter.createStatusEvent('phase_complete', { phase: 'planning' }));
+                return; // Local mode: return to user
+            }
+        }
+
+        // Phase 5: Build
+        const latestRun = task.latest_run;
+        const prExists = latestRun?.output && (latestRun.output as any).pr_url;
+        
+        if (!prExists) {
+            this.logger.info('Starting build phase', { taskId: task.id });
+            this.emitEvent(this.adapter.createStatusEvent('phase_start', { phase: 'build' }));
+            
+            // Run execution agent
+            const executionPrompt = await this.promptBuilder.buildExecutionPrompt(task, cwd);
+            const { EXECUTION_SYSTEM_PROMPT } = await import('./agents/execution.js');
+            const fullPrompt = EXECUTION_SYSTEM_PROMPT + '\n\n' + executionPrompt;
+            
+            const { PermissionMode } = await import('./types.js');
+            const permissionMode = options.permissionMode || PermissionMode.ACCEPT_EDITS;
+            const baseOptions: Record<string, any> = {
+                model: 'claude-sonnet-4-5-20250929',
+                cwd,
+                permissionMode,
+                settingSources: ['local'],
+                mcpServers: this.mcpServers,
+            };
+
+            const response = query({
+                prompt: fullPrompt,
+                options: { ...baseOptions, ...(options.queryOverrides || {}) },
+            });
+
+            for await (const message of response) {
+                this.emitEvent(this.adapter.createRawSDKEvent(message));
+                const transformed = this.adapter.transform(message);
+                if (transformed) {
+                    this.emitEvent(transformed);
+                }
+            }
+
+            // Commit and push implementation
+            // Stage ALL changes (not just .posthog/)
+            const hasChanges = await this.gitManager.hasChanges();
+            if (hasChanges) {
+                await this.gitManager.addFiles(['.']); // Stage all changes
+                await this.gitManager.commitChanges(`Implementation for ${task.title}`);
+                
+                // Push to origin
+                const branchName = await this.gitManager.getCurrentBranch();
+                await this.gitManager.pushBranch(branchName);
+                
+                this.logger.info('Implementation committed and pushed', { taskId: task.id });
+            } else {
+                this.logger.warn('No changes to commit in build phase', { taskId: task.id });
+            }
+
+            // Create PR
+            const branchName = await this.gitManager.getCurrentBranch();
+            const prUrl = await this.createPullRequest(task.id, branchName, task.title, task.description);
+            this.logger.info('Pull request created', { taskId: task.id, prUrl });
+            this.emitEvent(this.adapter.createStatusEvent('pr_created', { prUrl }));
+            
+            // Attach PR to task run
+            try {
+                await this.attachPullRequestToTask(task.id, prUrl, branchName);
+                this.logger.info('PR attached to task successfully', { taskId: task.id, prUrl });
+            } catch (error) {
+                this.logger.warn('Could not attach PR to task', { error: error instanceof Error ? error.message : String(error) });
+            }
+        } else {
+            this.logger.info('PR already exists, skipping build phase', { taskId: task.id });
+        }
+
+        // Phase 6: Complete
+        await this.progressReporter.complete();
+        this.logger.info('Task execution complete', { taskId: task.id });
+        this.emitEvent(this.adapter.createStatusEvent('task_complete', { taskId: task.id }));
+    }
+
     async progressToNextStage(taskId: string, currentStageKey?: string): Promise<void> {
         if (!this.posthogAPI || !this.progressReporter.runId) {
             throw new Error('PostHog API not configured or no active run. Cannot progress stage.');
@@ -437,6 +780,25 @@ export class Agent {
         this.logger.debug('Reading plan', { taskId });
         return await this.fileManager.readPlan(taskId);
     }
+
+    async extractQuestionsFromResearch(taskId: string, includeAnswers: boolean = false): Promise<ExtractedQuestion[] | ExtractedQuestionWithAnswer[]> {
+        this.logger.info('Extracting questions from research.md', { taskId, includeAnswers });
+        
+        if (!this.extractor) {
+            throw new Error('OpenAI extractor not initialized. Set OPENAI_API_KEY environment variable.');
+        }
+
+        const researchContent = await this.fileManager.readResearch(taskId);
+        if (!researchContent) {
+            throw new Error('research.md not found for task ' + taskId);
+        }
+
+        if (includeAnswers) {
+            return await this.extractor.extractQuestionsWithAnswers(researchContent);
+        } else {
+            return await this.extractor.extractQuestions(researchContent);
+        }
+    }
     
     // Git operations for task workflow
     async createPlanningBranch(taskId: string): Promise<string> {

package/src/agents/research.ts

@@ -0,0 +1,103 @@
+export const RESEARCH_SYSTEM_PROMPT = `# PostHog AI Coding Agent - Research Mode
+
+You are a PostHog AI Coding Agent operating in RESEARCH mode.
+
+## Your Role
+
+You are a research agent that explores codebases to understand implementation context and generate clarifying questions for development tasks.
+
+## Important Constraints
+
+- **Read-Only Mode**: You can only read files, search code, and analyze the codebase
+- **No Modifications**: You cannot make any changes or edits to code files
+- **Research Focus**: Your goal is understanding and asking the right questions
+
+## Available Tools
+
+- File reading and exploration
+- Code search and analysis
+- Repository structure analysis
+- Documentation review
+- \`create_plan\` tool for creating your research artifact
+
+## Research Process
+
+When given a task, follow this systematic approach:
+
+1. **Codebase Analysis**
+   - Explore the repository structure
+   - Identify relevant files and components
+   - Understand existing patterns and conventions
+   - Review related code and dependencies
+   - Look for similar implementations or patterns
+
+2. **Decision Point Identification**
+   - Identify areas where implementation decisions need to be made
+   - Find multiple viable approaches in the codebase
+   - Note where user preferences would affect the implementation
+   - Consider architectural or design pattern choices
+
+3. **Question Generation**
+   - Generate 3-5 clarifying questions
+   - Each question should offer 2-3 concrete options based on codebase analysis
+   - Options should reference actual patterns/approaches found in the code
+   - Always include option c) as "Something else (please specify)" for flexibility
+   - Focus on high-impact decisions that affect the implementation approach
+
+## Output Format
+
+After completing your research, you MUST use the \`create_plan\` tool to create a research.md artifact with your questions.
+
+The artifact MUST follow this EXACT markdown format (this is critical for parsing):
+
+\`\`\`markdown
+# Research Questions
+
+Based on my analysis of the codebase, here are the key questions to guide implementation:
+
+## Question 1: [Question text - be specific and clear]
+
+**Options:**
+- a) [Concrete option based on existing pattern - reference specific files/components]
+- b) [Alternative approach based on another pattern - reference specific files/components]  
+- c) Something else (please specify)
+
+## Question 2: [Next question - be specific and clear]
+
+**Options:**
+- a) [Option with specific code references]
+- b) [Alternative with specific code references]
+- c) Something else (please specify)
+
+## Question 3: [Continue with 3-5 questions total]
+
+**Options:**
+- a) [Option]
+- b) [Alternative]
+- c) Something else (please specify)
+\`\`\`
+
+## CRITICAL FORMAT REQUIREMENTS
+
+- Use EXACTLY "## Question N:" format for question headers (h2 level, not h3)
+- Each question MUST be followed by "**Options:**" on its own line
+- Each option MUST start with "- a)", "- b)", "- c)", etc.
+- Always include "c) Something else (please specify)" as the last option
+- Do NOT add extra sections between questions
+- Keep context and analysis BEFORE the questions section, not mixed in
+
+## Important Requirements
+
+- Generate 2-5 questions (no more, no less)
+- Make options specific and reference actual code/patterns you find
+- Each question must have at least 2 concrete options plus "Something else"
+- Focus on architectural and implementation approach decisions
+- Reference specific files, components, or patterns in your options
+- Make sure the questions help guide a clear implementation path
+
+## Final Step
+
+Once you have completed your research and identified the questions, use the \`create_plan\` tool to create the research.md artifact with the markdown content above. Do NOT use any other tools after creating the artifact.
+
+Your research should be thorough enough that the questions help clarify the user's preferences and guide the planning phase effectively.`;
+

package/src/file-manager.ts

@@ -9,6 +9,24 @@ export interface TaskFile {
   type: 'plan' | 'context' | 'reference' | 'output' | 'artifact';
 }
 
+export interface QuestionData {
+  id: string;
+  question: string;
+  options: string[];
+}
+
+export interface AnswerData {
+  questionId: string;
+  selectedOption: string;
+  customInput?: string;
+}
+
+export interface QuestionsFile {
+  questions: QuestionData[];
+  answered: boolean;
+  answers: AnswerData[] | null;
+}
+
 export class PostHogFileManager {
   private repositoryPath: string;
   private logger: Logger;
@@ -152,6 +170,52 @@ export class PostHogFileManager {
     return await this.readTaskFile(taskId, 'requirements.md');
   }
 
+  async writeResearch(taskId: string, content: string): Promise<void> {
+    this.logger.debug('Writing research', {
+      taskId,
+      contentLength: content.length,
+      contentPreview: content.substring(0, 200)
+    });
+
+    await this.writeTaskFile(taskId, {
+      name: 'research.md',
+      content: content,
+      type: 'artifact'
+    });
+
+    this.logger.info('Research file written', { taskId });
+  }
+
+  async readResearch(taskId: string): Promise<string | null> {
+    return await this.readTaskFile(taskId, 'research.md');
+  }
+
+  async writeQuestions(taskId: string, data: QuestionsFile): Promise<void> {
+    this.logger.debug('Writing questions', {
+      taskId,
+      questionCount: data.questions.length,
+      answered: data.answered,
+    });
+
+    await this.writeTaskFile(taskId, {
+      name: 'questions.json',
+      content: JSON.stringify(data, null, 2),
+      type: 'artifact'
+    });
+
+    this.logger.info('Questions file written', { taskId });
+  }
+
+  async readQuestions(taskId: string): Promise<QuestionsFile | null> {
+    try {
+      const content = await this.readTaskFile(taskId, 'questions.json');
+      return content ? JSON.parse(content) as QuestionsFile : null;
+    } catch (error) {
+      this.logger.debug('Failed to parse questions.json', { error });
+      return null;
+    }
+  }
+
   async getTaskFiles(taskId: string): Promise<SupportingFile[]> {
     const fileNames = await this.listTaskFiles(taskId);
     const files: SupportingFile[] = [];

package/src/git-manager.ts

@@ -341,4 +341,56 @@ Generated by PostHog Agent`;
       throw new Error(`Failed to create PR: ${error}`);
     }
   }
+
+  async getTaskBranch(taskSlug: string): Promise<string | null> {
+    try {
+      // Get all branches matching the task slug pattern
+      const branches = await this.runGitCommand('branch --list --all');
+      const branchPattern = `posthog/task-${taskSlug}`;
+      
+      // Look for exact match or with counter suffix
+      const lines = branches.split('\n').map(l => l.trim().replace(/^\*\s+/, ''));
+      for (const line of lines) {
+        const cleanBranch = line.replace('remotes/origin/', '');
+        if (cleanBranch.startsWith(branchPattern)) {
+          return cleanBranch;
+        }
+      }
+      
+      return null;
+    } catch (error) {
+      this.logger.debug('Failed to get task branch', { taskSlug, error });
+      return null;
+    }
+  }
+
+  async commitAndPush(message: string, options?: { allowEmpty?: boolean }): Promise<void> {
+    const hasChanges = await this.hasStagedChanges();
+    
+    if (!hasChanges && !options?.allowEmpty) {
+      this.logger.debug('No changes to commit, skipping');
+      return;
+    }
+
+    let command = `commit -m "${message.replace(/"/g, '\\"')}"`;
+    
+    if (options?.allowEmpty) {
+      command += ' --allow-empty';
+    }
+
+    const authorName = this.authorName;
+    const authorEmail = this.authorEmail;
+
+    if (authorName && authorEmail) {
+      command += ` --author="${authorName} <${authorEmail}>"`;
+    }
+
+    await this.runGitCommand(command);
+    
+    // Push to origin
+    const currentBranch = await this.getCurrentBranch();
+    await this.pushBranch(currentBranch);
+    
+    this.logger.info('Committed and pushed changes', { branch: currentBranch, message });
+  }
 }