@posthog/agent 1.10.0 → 1.11.0

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

package/src/types.ts

@@ -66,6 +66,14 @@ export interface ExecutionOptions {
   permissionMode?: PermissionMode;
 }
 
+export interface TaskExecutionOptions {
+  repositoryPath?: string;
+  permissionMode?: PermissionMode;
+  isCloudMode?: boolean; // Determines local vs cloud behavior (local pauses after each phase)
+  autoProgress?: boolean;
+  queryOverrides?: Record<string, any>;
+}
+
 // Base event with timestamp
 interface BaseEvent {
   ts: number;

package/src/workflow-types.ts

@@ -1,6 +1,6 @@
 import type { PermissionMode, AgentEvent } from './types.js';
 
-export type AgentType = 'planning' | 'execution' | 'review' | 'testing';
+export type AgentType = 'research' | 'planning' | 'execution' | 'review' | 'testing';
 
 export interface AgentDefinition {
   id: string;