@posthog/agent 1.10.0 → 1.12.0

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

@@ -161,7 +161,7 @@ export class GitManager {
     await this.runGitCommand(`push ${forceFlag} -u origin ${branchName}`);
   }
 
-  // Utility methods for PostHog task workflow
+  // Utility methods for PostHog task execution
   async createTaskPlanningBranch(taskId: string, baseBranch?: string): Promise<string> {
     let branchName = `posthog/task-${taskId}-planning`;
     let counter = 1;
@@ -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 });
+  }
 }

package/src/posthog-api.ts

@@ -1,5 +1,4 @@
 import type { Task, TaskRun, LogEntry, SupportingFile, PostHogAPIConfig, PostHogResource, ResourceType, UrlMention } from './types.js';
-import type { WorkflowDefinition, AgentDefinition } from './workflow-types.js';
 
 interface PostHogApiResponse<T> {
   results?: T[];
@@ -107,8 +106,6 @@ export class PostHogAPIClient {
     repository?: string;
     organization?: string;
     origin_product?: string;
-    workflow?: string;
-    current_stage?: string;
   }): Promise<Task[]> {
     const teamId = await this.getTeamId();
     const url = new URL(`${this.baseUrl}/api/projects/${teamId}/tasks/`);
@@ -171,26 +168,6 @@ export class PostHogAPIClient {
     });
   }
 
-  async updateTaskRunStage(taskId: string, runId: string, stageId: string): Promise<TaskRun> {
-    const teamId = await this.getTeamId();
-    return this.apiRequest<TaskRun>(`/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/update_stage/`, {
-      method: 'PATCH',
-      body: JSON.stringify({ current_stage: stageId }),
-    });
-  }
-
-  async progressTaskRun(taskId: string, runId: string, nextStageId?: string): Promise<TaskRun> {
-    const teamId = await this.getTeamId();
-    const payload: Record<string, string> = {};
-    if (nextStageId) {
-      payload.next_stage_id = nextStageId;
-    }
-    return this.apiRequest<TaskRun>(`/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/progress_run/`, {
-      method: 'POST',
-      body: JSON.stringify(payload),
-    });
-  }
-
   async setTaskRunOutput(taskId: string, runId: string, output: Record<string, unknown>): Promise<TaskRun> {
     const teamId = await this.getTeamId();
     return this.apiRequest<TaskRun>(`/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/set_output/`, {
@@ -207,23 +184,6 @@ export class PostHogAPIClient {
     });
   }
 
-  // Workflow endpoints
-  async fetchWorkflow(workflowId: string): Promise<WorkflowDefinition> {
-    const teamId = await this.getTeamId();
-    return this.apiRequest<WorkflowDefinition>(`/api/projects/${teamId}/workflows/${workflowId}/`);
-  }
-
-  async listWorkflows(): Promise<WorkflowDefinition[]> {
-    const teamId = await this.getTeamId();
-    const response = await this.apiRequest<PostHogApiResponse<WorkflowDefinition>>(`/api/projects/${teamId}/workflows/`);
-    return response.results || [];
-  }
-
-  // Agent catalog exposure
-  async listAgents(): Promise<AgentDefinition[]> {
-    return this.apiRequest<AgentDefinition[]>(`/api/agents/`);
-  }
-
   /**
    * Fetch error details from PostHog error tracking
    */

package/src/prompt-builder.ts

@@ -206,6 +206,59 @@ export class PromptBuilder {
     return { description: processedDescription, referencedFiles };
   }
 
+  async buildResearchPrompt(task: Task, repositoryPath?: string): Promise<string> {
+    // Process file references in description
+    const { description: descriptionAfterFiles, referencedFiles } = await this.processFileReferences(
+      task.description,
+      repositoryPath
+    );
+
+    // Process URL references in description  
+    const { description: processedDescription, referencedResources } = await this.processUrlReferences(
+      descriptionAfterFiles
+    );
+
+    let prompt = '';
+    prompt += `## Current Task\n\n**Task**: ${task.title}\n**Description**: ${processedDescription}`;
+
+    if ((task as any).primary_repository) {
+      prompt += `\n**Repository**: ${(task as any).primary_repository}`;
+    }
+
+    // Add referenced files from @ mentions
+    if (referencedFiles.length > 0) {
+      prompt += `\n\n## Referenced Files\n\n`;
+      for (const file of referencedFiles) {
+        prompt += `### ${file.path}\n\`\`\`\n${file.content}\n\`\`\`\n\n`;
+      }
+    }
+
+    // Add referenced resources from URL mentions
+    if (referencedResources.length > 0) {
+      prompt += `\n\n## Referenced Resources\n\n`;
+      for (const resource of referencedResources) {
+        prompt += `### ${resource.title} (${resource.type})\n**URL**: ${resource.url}\n\n${resource.content}\n\n`;
+      }
+    }
+
+    try {
+      const taskFiles = await this.getTaskFiles(task.id);
+      const contextFiles = taskFiles.filter((f: any) => f.type === 'context' || f.type === 'reference');
+      if (contextFiles.length > 0) {
+        prompt += `\n\n## Supporting Files`;
+        for (const file of contextFiles) {
+          prompt += `\n\n### ${file.name} (${file.type})\n${file.content}`;
+        }
+      }
+    } catch (error) {
+      this.logger.debug('No existing task files found for research', { taskId: task.id });
+    }
+
+    prompt += `\n\nPlease explore the codebase thoroughly and generate 3-5 clarifying questions that will help guide the implementation of this task. Use the \`create_plan\` tool to create a research.md artifact with your questions in the markdown format specified in your system prompt.`;
+
+    return prompt;
+  }
+
   async buildPlanningPrompt(task: Task, repositoryPath?: string): Promise<string> {
     // Process file references in description
     const { description: descriptionAfterFiles, referencedFiles } = await this.processFileReferences(

package/src/structured-extraction.ts

@@ -0,0 +1,167 @@
+import OpenAI from 'openai';
+import { Logger } from './utils/logger.js';
+
+export interface ExtractedQuestion {
+  id: string;
+  question: string;
+  options: string[];
+}
+
+export interface ExtractedQuestionWithAnswer extends ExtractedQuestion {
+  recommendedAnswer: string;
+  justification: string;
+}
+
+const questionsOnlySchema = {
+  type: 'object',
+  properties: {
+    questions: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          question: { type: 'string' },
+          options: {
+            type: 'array',
+            items: { type: 'string' }
+          }
+        },
+        required: ['id', 'question', 'options'],
+        additionalProperties: false
+      }
+    }
+  },
+  required: ['questions'],
+  additionalProperties: false
+};
+
+const questionsWithAnswersSchema = {
+  type: 'object',
+  properties: {
+    questions: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          question: { type: 'string' },
+          options: {
+            type: 'array',
+            items: { type: 'string' }
+          },
+          recommendedAnswer: { type: 'string' },
+          justification: { type: 'string' }
+        },
+        required: ['id', 'question', 'options', 'recommendedAnswer', 'justification'],
+        additionalProperties: false
+      }
+    }
+  },
+  required: ['questions'],
+  additionalProperties: false
+};
+
+export interface StructuredExtractor {
+  extractQuestions(researchContent: string): Promise<ExtractedQuestion[]>;
+  extractQuestionsWithAnswers(researchContent: string): Promise<ExtractedQuestionWithAnswer[]>;
+}
+
+export class OpenAIExtractor implements StructuredExtractor {
+  private client: OpenAI;
+  private logger: Logger;
+
+  constructor(logger?: Logger) {
+    const apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+      throw new Error('OPENAI_API_KEY environment variable is required for structured extraction');
+    }
+    
+    this.client = new OpenAI({ apiKey });
+    this.logger = logger || new Logger({ debug: false, prefix: '[OpenAIExtractor]' });
+  }
+
+  async extractQuestions(researchContent: string): Promise<ExtractedQuestion[]> {
+    this.logger.debug('Extracting questions from research content', {
+      contentLength: researchContent.length,
+    });
+
+    const completion = await this.client.chat.completions.create({
+      model: 'gpt-4o-mini',
+      messages: [
+        {
+          role: 'system',
+          content: 'Extract the research questions from the provided markdown. Return a JSON object matching the schema.',
+        },
+        {
+          role: 'user',
+          content: researchContent,
+        },
+      ],
+      response_format: {
+        type: 'json_schema',
+        json_schema: {
+          name: 'questions',
+          strict: true,
+          schema: questionsOnlySchema,
+        },
+      },
+    });
+
+    const content = completion.choices[0].message.content;
+    if (!content) {
+      throw new Error('No content in OpenAI response');
+    }
+
+    const parsed = JSON.parse(content) as { questions: ExtractedQuestion[] };
+    
+    this.logger.info('Successfully extracted questions', {
+      questionCount: parsed.questions.length,
+    });
+
+    return parsed.questions;
+  }
+
+  async extractQuestionsWithAnswers(
+    researchContent: string,
+  ): Promise<ExtractedQuestionWithAnswer[]> {
+    this.logger.debug('Extracting questions with recommended answers', {
+      contentLength: researchContent.length,
+    });
+
+    const completion = await this.client.chat.completions.create({
+      model: 'gpt-4o-mini',
+      messages: [
+        {
+          role: 'system',
+          content: 'Extract the research questions from the markdown and provide recommended answers based on the analysis. For each question, include a recommendedAnswer (the letter: a, b, c, etc.) and a brief justification. Return a JSON object matching the schema.',
+        },
+        {
+          role: 'user',
+          content: researchContent,
+        },
+      ],
+      response_format: {
+        type: 'json_schema',
+        json_schema: {
+          name: 'questions_with_answers',
+          strict: true,
+          schema: questionsWithAnswersSchema,
+        },
+      },
+    });
+
+    const content = completion.choices[0].message.content;
+    if (!content) {
+      throw new Error('No content in OpenAI response');
+    }
+
+    const parsed = JSON.parse(content) as { questions: ExtractedQuestionWithAnswer[] };
+    
+    this.logger.info('Successfully extracted questions with answers', {
+      questionCount: parsed.questions.length,
+    });
+
+    return parsed.questions;
+  }
+}

package/src/task-progress-reporter.ts

@@ -51,45 +51,13 @@ export class TaskProgressReporter {
     }
   }
 
-  async stageStarted(stageKey: string, stageIndex: number): Promise<void> {
-    await this.update({
-      status: 'in_progress',
-    }, `Stage started: ${stageKey}`);
-  }
-
-  async stageCompleted(stageKey: string, completedStages: number): Promise<void> {
-    await this.update({
-      status: 'in_progress',
-    }, `Stage completed: ${stageKey}`);
-  }
-
-  async branchCreated(stageKey: string, branchName: string): Promise<void> {
-    await this.appendLog(`Branch created (${stageKey}): ${branchName}`);
-  }
-
-  async commitMade(stageKey: string, kind: 'plan' | 'implementation'): Promise<void> {
-    await this.appendLog(`Commit made (${stageKey}, ${kind})`);
-  }
-
-  async pullRequestCreated(stageKey: string, prUrl: string): Promise<void> {
-    await this.appendLog(`Pull request created (${stageKey}): ${prUrl}`);
-  }
-
-  async noNextStage(stageKey?: string): Promise<void> {
-    await this.appendLog(
-      stageKey
-        ? `No next stage available after '${stageKey}'. Execution halted.`
-        : 'No next stage available. Execution halted.'
-    );
-  }
-
   async complete(): Promise<void> {
-    await this.update({ status: 'completed' }, 'Workflow execution completed');
+    await this.update({ status: 'completed' }, 'Task execution completed');
   }
 
   async fail(error: Error | string): Promise<void> {
     const message = typeof error === 'string' ? error : error.message;
-    await this.update({ status: 'failed', error_message: message }, `Workflow execution failed: ${message}`);
+    await this.update({ status: 'failed', error_message: message }, `Task execution failed: ${message}`);
   }
 
   async appendLog(line: string): Promise<void> {

package/src/template-manager.ts

@@ -17,14 +17,45 @@ export class TemplateManager {
   constructor() {
     const __filename = fileURLToPath(import.meta.url);
     const __dirname = dirname(__filename);
+
+    // Exhaustive list of possible template locations
     const candidateDirs = [
-      join(__dirname, 'templates'),
+      // Standard build output (dist/src/template-manager.js -> dist/templates)
       join(__dirname, '..', 'templates'),
+
+      // If preserveModules creates nested structure (dist/src/template-manager.js -> dist/src/templates)
+      join(__dirname, 'templates'),
+
+      // Development scenarios (src/template-manager.ts -> src/templates)
+      join(__dirname, '..', '..', 'src', 'templates'),
+
+      // Package root templates directory
       join(__dirname, '..', '..', 'templates'),
-      join(__dirname, '..', '..', 'src', 'templates')
+
+      // When node_modules symlink or installed (node_modules/@posthog/agent/dist/src/... -> node_modules/@posthog/agent/dist/templates)
+      join(__dirname, '..', '..', 'dist', 'templates'),
+
+      // When consumed from node_modules deep in tree
+      join(__dirname, '..', '..', '..', 'templates'),
+      join(__dirname, '..', '..', '..', 'dist', 'templates'),
+      join(__dirname, '..', '..', '..', 'src', 'templates'),
+
+      // When bundled by Vite/Webpack (e.g., .vite/build/index.js -> node_modules/@posthog/agent/dist/templates)
+      // Try to find node_modules from current location
+      join(__dirname, '..', 'node_modules', '@posthog', 'agent', 'dist', 'templates'),
+      join(__dirname, '..', '..', 'node_modules', '@posthog', 'agent', 'dist', 'templates'),
+      join(__dirname, '..', '..', '..', 'node_modules', '@posthog', 'agent', 'dist', 'templates'),
     ];
 
     const resolvedDir = candidateDirs.find((dir) => existsSync(dir));
+
+    if (!resolvedDir) {
+      console.error('[TemplateManager] Could not find templates directory.');
+      console.error('[TemplateManager] Current file:', __filename);
+      console.error('[TemplateManager] Current dir:', __dirname);
+      console.error('[TemplateManager] Tried:', candidateDirs.map(d => `\n  - ${d} (exists: ${existsSync(d)})`).join(''));
+    }
+
     this.templatesDir = resolvedDir ?? candidateDirs[0];
   }
 
@@ -33,7 +64,7 @@ export class TemplateManager {
       const templatePath = join(this.templatesDir, templateName);
       return await fs.readFile(templatePath, 'utf8');
     } catch (error) {
-      throw new Error(`Failed to load template ${templateName}: ${error}`);
+      throw new Error(`Failed to load template ${templateName} from ${this.templatesDir}: ${error}`);
     }
   }
 
@@ -60,7 +91,6 @@ export class TemplateManager {
     });
   }
 
-
   async generateCustomFile(templateName: string, variables: TemplateVariables): Promise<string> {
     const template = await this.loadTemplate(templateName);
     return this.substituteVariables(template, {
@@ -147,7 +177,7 @@ These files are:
 Customize \`.posthog/.gitignore\` to control which files are committed:
 - Include plans and documentation by default
 - Exclude temporary files and sensitive data
-- Customize based on your team's workflow
+- Customize based on your team's needs
 
 ---