@posthog/agent 1.9.0 → 1.11.0

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 });
+  }
 }

package/src/posthog-api.ts

@@ -1,4 +1,4 @@
-import type { Task, SupportingFile, PostHogAPIConfig, PostHogResource, ResourceType, UrlMention } from './types.js';
+import type { Task, TaskRun, LogEntry, SupportingFile, PostHogAPIConfig, PostHogResource, ResourceType, UrlMention } from './types.js';
 import type { WorkflowDefinition, AgentDefinition } from './workflow-types.js';
 
 interface PostHogApiResponse<T> {
@@ -8,52 +8,14 @@ interface PostHogApiResponse<T> {
   previous?: string | null;
 }
 
-interface TaskProgressResponse {
-  has_progress: boolean;
-  id?: string;
-  status?: "started" | "in_progress" | "completed" | "failed";
-  current_step?: string;
-  completed_steps?: number;
-  total_steps?: number;
-  progress_percentage?: number;
-  output_log?: string;
-  error_message?: string;
-  created_at?: string;
-  updated_at?: string;
-  completed_at?: string;
-  workflow_id?: string;
-  workflow_run_id?: string;
-  message?: string;
-}
-
-export interface TaskProgressRecord {
-  id: string;
-  task: string;
-  status: "started" | "in_progress" | "completed" | "failed";
-  current_step?: string | null;
-  completed_steps?: number | null;
-  total_steps?: number | null;
-  progress_percentage?: number | null;
-  output_log?: string | null;
-  error_message?: string | null;
-  workflow_id?: string | null;
-  workflow_run_id?: string | null;
-  activity_id?: string | null;
-  created_at: string;
-  updated_at: string;
-  completed_at?: string | null;
-}
-
-export interface TaskProgressUpdate {
-  status?: TaskProgressRecord["status"];
-  current_step?: string | null;
-  completed_steps?: number | null;
-  total_steps?: number | null;
-  output_log?: string | null;
+export interface TaskRunUpdate {
+  status?: TaskRun["status"];
+  branch?: string | null;
+  current_stage?: string | null;
+  log?: LogEntry[];
   error_message?: string | null;
-  workflow_id?: string | null;
-  workflow_run_id?: string | null;
-  activity_id?: string | null;
+  output?: Record<string, unknown> | null;
+  state?: Record<string, unknown>;
 }
 
 export class PostHogAPIClient {
@@ -172,65 +134,76 @@ export class PostHogAPIClient {
     });
   }
 
-  async updateTaskStage(taskId: string, stageId: string): Promise<Task> {
+  // TaskRun methods
+  async listTaskRuns(taskId: string): Promise<TaskRun[]> {
     const teamId = await this.getTeamId();
-    return this.apiRequest<Task>(`/api/projects/${teamId}/tasks/${taskId}/update_stage/`, {
-      method: 'PATCH',
-      body: JSON.stringify({ current_stage: stageId }),
-    });
+    const response = await this.apiRequest<PostHogApiResponse<TaskRun>>(
+      `/api/projects/${teamId}/tasks/${taskId}/runs/`
+    );
+    return response.results || [];
   }
 
-  async setTaskBranch(taskId: string, branch: string): Promise<Task> {
+  async getTaskRun(taskId: string, runId: string): Promise<TaskRun> {
     const teamId = await this.getTeamId();
-    return this.apiRequest<Task>(`/api/projects/${teamId}/tasks/${taskId}/set_branch/`, {
+    return this.apiRequest<TaskRun>(`/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/`);
+  }
+
+  async createTaskRun(
+    taskId: string,
+    payload?: Partial<Omit<TaskRun, 'id' | 'task' | 'team' | 'created_at' | 'updated_at' | 'completed_at'>>
+  ): Promise<TaskRun> {
+    const teamId = await this.getTeamId();
+    return this.apiRequest<TaskRun>(`/api/projects/${teamId}/tasks/${taskId}/runs/`, {
       method: "POST",
-      body: JSON.stringify({ branch }),
+      body: JSON.stringify(payload || {}),
     });
   }
 
-  async attachTaskPullRequest(taskId: string, prUrl: string, branch?: string): Promise<Task> {
+  async updateTaskRun(
+    taskId: string,
+    runId: string,
+    payload: TaskRunUpdate
+  ): Promise<TaskRun> {
     const teamId = await this.getTeamId();
-    const payload: Record<string, string> = { pr_url: prUrl };
-    if (branch) {
-      payload.branch = branch;
-    }
-    return this.apiRequest<Task>(`/api/projects/${teamId}/tasks/${taskId}/attach_pr/`, {
-      method: "POST",
+    return this.apiRequest<TaskRun>(`/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/`, {
+      method: "PATCH",
       body: JSON.stringify(payload),
     });
   }
 
-  async getTaskProgress(taskId: string): Promise<TaskProgressResponse> {
+  async updateTaskRunStage(taskId: string, runId: string, stageId: string): Promise<TaskRun> {
     const teamId = await this.getTeamId();
-    return this.apiRequest<TaskProgressResponse>(`/api/projects/${teamId}/tasks/${taskId}/progress/`);
+    return this.apiRequest<TaskRun>(`/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/update_stage/`, {
+      method: 'PATCH',
+      body: JSON.stringify({ current_stage: stageId }),
+    });
   }
 
-  async createTaskProgress(
-    taskId: string,
-    payload: TaskProgressUpdate & { status: TaskProgressRecord["status"] }
-  ): Promise<TaskProgressRecord> {
+  async progressTaskRun(taskId: string, runId: string, nextStageId?: string): Promise<TaskRun> {
     const teamId = await this.getTeamId();
-    return this.apiRequest<TaskProgressRecord>(`/api/projects/${teamId}/task_progress/`, {
-      method: "POST",
-      body: JSON.stringify({
-        ...payload,
-        task: taskId,
-      }),
+    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 updateTaskProgress(
-    taskId: string,
-    progressId: string,
-    payload: TaskProgressUpdate
-  ): Promise<TaskProgressRecord> {
+  async setTaskRunOutput(taskId: string, runId: string, output: Record<string, unknown>): Promise<TaskRun> {
     const teamId = await this.getTeamId();
-    return this.apiRequest<TaskProgressRecord>(`/api/projects/${teamId}/task_progress/${progressId}/`, {
-      method: "PATCH",
-      body: JSON.stringify({
-        ...payload,
-        task: taskId,
-      }),
+    return this.apiRequest<TaskRun>(`/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/set_output/`, {
+      method: 'PATCH',
+      body: JSON.stringify({ output }),
+    });
+  }
+
+  async appendTaskRunLog(taskId: string, runId: string, entries: LogEntry[]): Promise<TaskRun> {
+    const teamId = await this.getTeamId();
+    return this.apiRequest<TaskRun>(`/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/append_log/`, {
+      method: 'POST',
+      body: JSON.stringify({ entries }),
     });
   }
 
@@ -251,14 +224,6 @@ export class PostHogAPIClient {
     return this.apiRequest<AgentDefinition[]>(`/api/agents/`);
   }
 
-  async progressTask(taskId: string, options?: { next_stage_id?: string; auto?: boolean }): Promise<Task> {
-    const teamId = await this.getTeamId();
-    return this.apiRequest<Task>(`/api/projects/${teamId}/tasks/${taskId}/progress_task/`, {
-      method: 'POST',
-      body: JSON.stringify(options || {}),
-    });
-  }
-
   /**
    * 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/stage-executor.ts

@@ -4,6 +4,7 @@ import { ClaudeAdapter } from './adapters/claude/claude-adapter.js';
 import { AgentRegistry } from './agent-registry.js';
 import type { AgentEvent, Task, McpServerConfig } from './types.js';
 import type { WorkflowStage, WorkflowStageExecutionResult, WorkflowExecutionOptions } from './workflow-types.js';
+import { RESEARCH_SYSTEM_PROMPT } from './agents/research.js';
 import { PLANNING_SYSTEM_PROMPT } from './agents/planning.js';
 import { EXECUTION_SYSTEM_PROMPT } from './agents/execution.js';
 import { PromptBuilder } from './prompt-builder.js';
@@ -57,6 +58,8 @@ export class StageExecutor {
     const cwd = options.repositoryPath || process.cwd();
 
     switch (agent.agent_type) {
+      case 'research':
+        return this.runResearch(task, cwd, options, stage.key);
       case 'planning':
         return this.runPlanning(task, cwd, options, stage.key);
       case 'execution':
@@ -70,6 +73,53 @@ export class StageExecutor {
     }
   }
 
+  private async runResearch(task: Task, cwd: string, options: WorkflowExecutionOptions, stageKey: string): Promise<WorkflowStageExecutionResult> {
+    const contextPrompt = await this.promptBuilder.buildResearchPrompt(task, cwd);
+    let prompt = RESEARCH_SYSTEM_PROMPT + '\n\n' + contextPrompt;
+
+    const stageOverrides = options.stageOverrides?.[stageKey] || options.stageOverrides?.['research'];
+    const mergedOverrides = {
+      ...(options.queryOverrides || {}),
+      ...(stageOverrides?.queryOverrides || {}),
+    } as Record<string, any>;
+
+    const baseOptions: Record<string, any> = {
+      model: 'claude-sonnet-4-5-20250929',
+      cwd,
+      permissionMode: 'plan',
+      settingSources: ['local'],
+      mcpServers: this.mcpServers
+    };
+
+    const response = query({
+      prompt,
+      options: { ...baseOptions, ...mergedOverrides },
+    });
+
+    let research = '';
+    for await (const message of response) {
+      // Emit raw SDK event first
+      this.eventHandler?.(this.adapter.createRawSDKEvent(message));
+
+      // Then emit transformed event
+      const transformed = this.adapter.transform(message);
+      if (transformed) {
+        if (transformed.type !== 'token') {
+          this.logger.debug('Research event', { type: transformed.type });
+        }
+        this.eventHandler?.(transformed);
+      }
+
+      if (message.type === 'assistant' && message.message?.content) {
+        for (const c of message.message.content) {
+          if (c.type === 'text' && c.text) research += c.text + '\n';
+        }
+      }
+    }
+
+    return { plan: research.trim() }; // Return as 'plan' field to match existing interface
+  }
+
   private async runPlanning(task: Task, cwd: string, options: WorkflowExecutionOptions, stageKey: string): Promise<WorkflowStageExecutionResult> {
     const contextPrompt = await this.promptBuilder.buildPlanningPrompt(task, cwd);
     let prompt = PLANNING_SYSTEM_PROMPT + '\n\n' + contextPrompt;

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;
+  }
+}