@posthog/agent 1.16.6 → 1.17.0

package/src/file-manager.ts

@@ -1,6 +1,6 @@
 import { promises as fs } from 'fs';
-import { join, dirname } from 'path';
-import type { SupportingFile } from './types.js';
+import { join } from 'path';
+import type { SupportingFile, ResearchEvaluation } from './types.js';
 import { Logger } from './utils/logger.js';
 
 export interface TaskFile {
@@ -9,24 +9,6 @@ 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;
@@ -170,48 +152,35 @@ export class PostHogFileManager {
     return await this.readTaskFile(taskId, 'requirements.md');
   }
 
-  async writeResearch(taskId: string, content: string): Promise<void> {
+  async writeResearch(taskId: string, data: ResearchEvaluation): Promise<void> {
     this.logger.debug('Writing research', {
       taskId,
-      contentLength: content.length,
-      contentPreview: content.substring(0, 200)
+      score: data.actionabilityScore,
+      hasQuestions: !!data.questions,
+      questionCount: data.questions?.length ?? 0,
+      answered: data.answered ?? false,
     });
 
     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',
+      name: 'research.json',
       content: JSON.stringify(data, null, 2),
       type: 'artifact'
     });
 
-    this.logger.info('Questions file written', { taskId });
+    this.logger.info('Research file written', { 
+      taskId, 
+      score: data.actionabilityScore,
+      hasQuestions: !!data.questions,
+      answered: data.answered ?? false,
+    });
   }
 
-  async readQuestions(taskId: string): Promise<QuestionsFile | null> {
+  async readResearch(taskId: string): Promise<ResearchEvaluation | null> {
     try {
-      const content = await this.readTaskFile(taskId, 'questions.json');
-      return content ? JSON.parse(content) as QuestionsFile : null;
+      const content = await this.readTaskFile(taskId, 'research.json');
+      return content ? JSON.parse(content) as ResearchEvaluation : null;
     } catch (error) {
-      this.logger.debug('Failed to parse questions.json', { error });
+      this.logger.debug('Failed to parse research.json', { error });
       return null;
     }
   }
@@ -241,28 +210,4 @@ export class PostHogFileManager {
     
     return files;
   }
-
-  async ensureGitignore(): Promise<void> {
-    const gitignorePath = join(this.repositoryPath, '.posthog', '.gitignore');
-    const gitignoreContent = `# PostHog task artifacts - customize as needed
-# Exclude temporary files
-*/temp/
-*/cache/
-*/.env
-*/.secrets
-
-# Include plans and documentation by default
-!*/plan.md
-!*/context.md
-!*/requirements.md
-!*/README.md
-`;
-
-    try {
-      await fs.access(gitignorePath);
-    } catch {
-      await fs.mkdir(dirname(gitignorePath), { recursive: true });
-      await fs.writeFile(gitignorePath, gitignoreContent, 'utf8');
-    }
-  }
 }

package/src/git-manager.ts

@@ -135,7 +135,13 @@ export class GitManager {
   }
 
   async addAllPostHogFiles(): Promise<void> {
-    await this.runGitCommand('add .posthog/');
+    try {
+      // Use -A flag to add all changes (including new files) and ignore errors if directory is empty
+      await this.runGitCommand('add -A .posthog/');
+    } catch (error) {
+      // If the directory doesn't exist or has no files, that's fine - just log and continue
+      this.logger.debug('No PostHog files to add', { error });
+    }
   }
 
   async commitChanges(message: string, options?: {

package/src/templates/plan-template.md

@@ -38,8 +38,4 @@ path/to/existing/file.ts - Changes needed
 
 - Key architectural decisions
 - Potential risks and mitigation
-- Testing approach
-
----
-
-*Generated by PostHog Agent*
+- Testing approach

package/src/types.ts

@@ -1,6 +1,6 @@
 
 // import and export to keep a single type file
-import type { CanUseTool, PermissionResult } from '@anthropic-ai/claude-agent-sdk/sdkTypes.js';
+import type { CanUseTool, PermissionResult } from '@anthropic-ai/claude-agent-sdk';
 export type { CanUseTool, PermissionResult };
 
 // PostHog Task model (matches Array's OpenAPI schema)
@@ -345,4 +345,27 @@ export interface UrlMention {
   type: ResourceType;
   id?: string;
   label?: string;
+}
+
+// Research evaluation types
+export interface ResearchQuestion {
+  id: string;
+  question: string;
+  options: string[];
+}
+
+export interface ResearchAnswer {
+  questionId: string;
+  selectedOption: string;
+  customInput?: string;
+}
+
+export interface ResearchEvaluation {
+  actionabilityScore: number;    // 0-1 confidence score
+  context: string;               // brief summary for planning
+  keyFiles: string[];            // files needing modification
+  blockers?: string[];           // what's preventing full confidence
+  questions?: ResearchQuestion[]; // only if score < 0.7
+  answered?: boolean;            // whether questions have been answered
+  answers?: ResearchAnswer[];    // user's answers to questions
 }

package/src/workflow/steps/plan.ts

@@ -26,8 +26,8 @@ export const planStep: WorkflowStepRunner = async ({ step, context }) => {
         return { status: 'skipped' };
     }
 
-    const questionsData = await fileManager.readQuestions(task.id);
-    if (!questionsData || !questionsData.answered) {
+    const researchData = await fileManager.readResearch(task.id);
+    if (researchData?.questions && !researchData.answered) {
         stepLogger.info('Waiting for answered research questions', { taskId: task.id });
         emitEvent(adapter.createStatusEvent('phase_complete', { phase: 'research_questions' }));
         return { status: 'skipped', halt: true };
@@ -35,29 +35,36 @@ export const planStep: WorkflowStepRunner = async ({ step, context }) => {
 
     stepLogger.info('Starting planning phase', { taskId: task.id });
     emitEvent(adapter.createStatusEvent('phase_start', { phase: 'planning' }));
-
-    const researchContent = await fileManager.readResearch(task.id);
     let researchContext = '';
-    if (researchContent) {
-        researchContext += `## Research Analysis\n\n${researchContent}\n\n`;
-    }
-
-    researchContext += `## Implementation Decisions\n\n`;
-    for (const question of questionsData.questions) {
-        const answer = questionsData.answers?.find(
-            (a: any) => a.questionId === question.id
-        );
+    if (researchData) {
+        researchContext += `## Research Context\n\n${researchData.context}\n\n`;
+        if (researchData.keyFiles.length > 0) {
+            researchContext += `**Key Files:**\n${researchData.keyFiles.map(f => `- ${f}`).join('\n')}\n\n`;
+        }
+        if (researchData.blockers && researchData.blockers.length > 0) {
+            researchContext += `**Considerations:**\n${researchData.blockers.map(b => `- ${b}`).join('\n')}\n\n`;
+        }
 
-        researchContext += `### ${question.question}\n\n`;
-        if (answer) {
-            researchContext += `**Selected:** ${answer.selectedOption}\n`;
-            if (answer.customInput) {
-                researchContext += `**Details:** ${answer.customInput}\n`;
+        // Add answered questions if they exist
+        if (researchData.questions && researchData.answers && researchData.answered) {
+            researchContext += `## Implementation Decisions\n\n`;
+            for (const question of researchData.questions) {
+                const answer = researchData.answers.find(
+                    (a) => 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 {
+                    researchContext += `**Selected:** Not answered\n`;
+                }
+                researchContext += `\n`;
             }
-        } else {
-            researchContext += `**Selected:** Not answered\n`;
         }
-        researchContext += `\n`;
     }
 
     const planningPrompt = await promptBuilder.buildPlanningPrompt(task, cwd);

package/src/workflow/steps/research.ts

@@ -1,7 +1,7 @@
 import { query } from '@anthropic-ai/claude-agent-sdk';
 import { RESEARCH_SYSTEM_PROMPT } from '../../agents/research.js';
-import type { ExtractedQuestionWithAnswer } from '../../structured-extraction.js';
 import type { WorkflowStepRunner } from '../types.js';
+import type { ResearchEvaluation } from '../../types.js';
 import { finalizeStepGitActions } from '../utils.js';
 
 export const researchStep: WorkflowStepRunner = async ({ step, context }) => {
@@ -16,7 +16,6 @@ export const researchStep: WorkflowStepRunner = async ({ step, context }) => {
         promptBuilder,
         adapter,
         mcpServers,
-        extractor,
         emitEvent,
     } = context;
 
@@ -24,7 +23,29 @@ export const researchStep: WorkflowStepRunner = async ({ step, context }) => {
 
     const existingResearch = await fileManager.readResearch(task.id);
     if (existingResearch) {
-        stepLogger.info('Research already exists, skipping step', { taskId: task.id });
+        stepLogger.info('Research already exists', { taskId: task.id, hasQuestions: !!existingResearch.questions, answered: existingResearch.answered });
+        
+        // If there are unanswered questions, re-emit them so UI can prompt user
+        if (existingResearch.questions && !existingResearch.answered) {
+            stepLogger.info('Re-emitting unanswered research questions', { 
+                taskId: task.id,
+                questionCount: existingResearch.questions.length 
+            });
+            
+            emitEvent({
+                type: 'artifact',
+                ts: Date.now(),
+                kind: 'research_questions',
+                content: existingResearch.questions,
+            });
+            
+            // In local mode, halt to allow user to answer
+            if (!isCloudMode) {
+                emitEvent(adapter.createStatusEvent('phase_complete', { phase: 'research' }));
+                return { status: 'skipped', halt: true };
+            }
+        }
+        
         return { status: 'skipped' };
     }
 
@@ -59,7 +80,7 @@ export const researchStep: WorkflowStepRunner = async ({ step, context }) => {
         options: { ...baseOptions, ...(options.queryOverrides || {}) },
     });
 
-    let researchContent = '';
+    let jsonContent = '';
     for await (const message of response) {
         emitEvent(adapter.createRawSDKEvent(message));
         const transformed = adapter.transform(message);
@@ -69,100 +90,114 @@ export const researchStep: WorkflowStepRunner = async ({ step, context }) => {
         if (message.type === 'assistant' && message.message?.content) {
             for (const c of message.message.content) {
                 if (c.type === 'text' && c.text) {
-                    researchContent += `${c.text}\n`;
+                    jsonContent += c.text;
                 }
             }
         }
     }
 
-    if (researchContent.trim()) {
-        await fileManager.writeResearch(task.id, researchContent.trim());
-        stepLogger.info('Research completed', { taskId: task.id });
+    if (!jsonContent.trim()) {
+        stepLogger.error('No JSON output from research agent', { taskId: task.id });
+        emitEvent({
+            type: 'error',
+            ts: Date.now(),
+            message: 'Research agent returned no output',
+        });
+        return { status: 'completed', halt: true };
+    }
+
+    // Parse JSON response
+    let evaluation: ResearchEvaluation;
+    try {
+        // Extract JSON from potential markdown code blocks or other wrapping
+        const jsonMatch = jsonContent.match(/\{[\s\S]*\}/);
+        if (!jsonMatch) {
+            throw new Error('No JSON object found in response');
+        }
+        evaluation = JSON.parse(jsonMatch[0]);
+        stepLogger.info('Parsed research evaluation', {
+            taskId: task.id,
+            score: evaluation.actionabilityScore,
+            hasQuestions: !!evaluation.questions,
+        });
+    } catch (error) {
+        stepLogger.error('Failed to parse research JSON', {
+            taskId: task.id,
+            error: error instanceof Error ? error.message : String(error),
+            content: jsonContent.substring(0, 500),
+        });
+        emitEvent({
+            type: 'error',
+            ts: Date.now(),
+            message: `Failed to parse research JSON: ${
+                error instanceof Error ? error.message : String(error)
+            }`,
+        });
+        return { status: 'completed', halt: true };
+    }
+
+    // Add answered/answers fields to evaluation
+    if (evaluation.questions && evaluation.questions.length > 0) {
+        evaluation.answered = false;
+        evaluation.answers = undefined;
     }
 
+    // Always write research.json
+    await fileManager.writeResearch(task.id, evaluation);
+    stepLogger.info('Research evaluation written', {
+        taskId: task.id,
+        score: evaluation.actionabilityScore,
+        hasQuestions: !!evaluation.questions,
+    });
+
+    emitEvent({
+        type: 'artifact',
+        ts: Date.now(),
+        kind: 'research_evaluation',
+        content: evaluation,
+    });
+
     await gitManager.addAllPostHogFiles();
     await finalizeStepGitActions(context, step, {
         commitMessage: `Research phase for ${task.title}`,
     });
 
-    if (extractor && researchContent.trim()) {
-        try {
-            stepLogger.info('Extracting questions from research.md', { taskId: task.id });
-            const parsedQuestions = await extractor.extractQuestions(researchContent);
-
-            await fileManager.writeQuestions(task.id, {
-                questions: parsedQuestions,
-                answered: false,
-                answers: null,
-            });
-
-            emitEvent({
-                type: 'artifact',
-                ts: Date.now(),
-                kind: 'research_questions',
-                content: parsedQuestions,
-            });
-
-            stepLogger.info('Questions extracted successfully', {
-                taskId: task.id,
-                count: parsedQuestions.length,
-            });
-        } catch (error) {
-            stepLogger.error('Failed to extract questions', {
-                taskId: task.id,
-                error: error instanceof Error ? error.message : String(error),
-            });
-            emitEvent({
-                type: 'error',
-                ts: Date.now(),
-                message: `Failed to extract questions: ${
-                    error instanceof Error ? error.message : String(error)
-                }`,
-            });
-        }
-    } else if (!extractor) {
-        stepLogger.warn(
-            'Question extractor not available, skipping question extraction. Ensure LLM gateway is configured.'
-        );
+    // Log whether questions need answering
+    if (evaluation.actionabilityScore < 0.7 && evaluation.questions && evaluation.questions.length > 0) {
+        stepLogger.info('Actionability score below threshold, questions needed', {
+            taskId: task.id,
+            score: evaluation.actionabilityScore,
+            questionCount: evaluation.questions.length,
+        });
+        
         emitEvent({
-            type: 'status',
+            type: 'artifact',
             ts: Date.now(),
-            phase: 'extraction_skipped',
-            message: 'Question extraction skipped - extractor not configured',
+            kind: 'research_questions',
+            content: evaluation.questions,
+        });
+    } else {
+        stepLogger.info('Actionability score acceptable, proceeding to planning', {
+            taskId: task.id,
+            score: evaluation.actionabilityScore,
         });
     }
 
+    // In local mode, always halt after research for user review
     if (!isCloudMode) {
         emitEvent(adapter.createStatusEvent('phase_complete', { phase: 'research' }));
         return { status: 'completed', halt: true };
     }
 
-    const questionsData = await fileManager.readQuestions(task.id);
-    if (questionsData && !questionsData.answered && extractor && researchContent.trim()) {
-        const researchQuestions = await extractor.extractQuestionsWithAnswers(researchContent);
-        const answers = (researchQuestions as ExtractedQuestionWithAnswer[]).map((qa) => ({
-            questionId: qa.id,
-            selectedOption: qa.recommendedAnswer,
-            customInput: qa.justification,
-        }));
-
-        await fileManager.writeQuestions(task.id, {
-            questions: researchQuestions.map((qa) => ({
-                id: qa.id,
-                question: qa.question,
-                options: qa.options,
-            })),
-            answered: true,
-            answers,
-        });
-
-        await gitManager.addAllPostHogFiles();
-        await finalizeStepGitActions(context, step, {
-            commitMessage: `Answer research questions for ${task.title}`,
-        });
-        stepLogger.info('Auto-answered research questions', { taskId: task.id });
+    // In cloud mode, check if questions need answering
+    const researchData = await fileManager.readResearch(task.id);
+    if (researchData?.questions && !researchData.answered) {
+        // Questions need answering - halt for user input in cloud mode too
+        emitEvent(adapter.createStatusEvent('phase_complete', { phase: 'research' }));
+        return { status: 'completed', halt: true };
     }
 
+    // No questions or questions already answered - proceed to planning
     emitEvent(adapter.createStatusEvent('phase_complete', { phase: 'research' }));
     return { status: 'completed' };
 };

package/src/workflow/types.ts

@@ -6,7 +6,6 @@ import type { PromptBuilder } from '../prompt-builder.js';
 import type { TaskProgressReporter } from '../task-progress-reporter.js';
 import type { ProviderAdapter } from '../adapters/types.js';
 import type { PostHogAPIClient } from '../posthog-api.js';
-import type { StructuredExtractor } from '../structured-extraction.js';
 
 export interface WorkflowRuntime {
     task: Task;
@@ -22,7 +21,6 @@ export interface WorkflowRuntime {
     adapter: ProviderAdapter;
     mcpServers?: Record<string, any>;
     posthogAPI?: PostHogAPIClient;
-    extractor?: StructuredExtractor;
     emitEvent: (event: any) => void;
     stepResults: Record<string, any>;
 }

package/dist/_virtual/_commonjsHelpers.js

@@ -1,6 +0,0 @@
-function getDefaultExportFromCjs (x) {
-	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
-}
-
-export { getDefaultExportFromCjs };
-//# sourceMappingURL=_commonjsHelpers.js.map

package/dist/_virtual/_commonjsHelpers.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"_commonjsHelpers.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;"}

package/dist/_virtual/index.js

@@ -1,4 +0,0 @@
-var secureJsonParse = {exports: {}};
-
-export { secureJsonParse as __module };
-//# sourceMappingURL=index.js.map

package/dist/_virtual/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;"}