@posthog/agent 1.24.2 → 1.26.0

package/src/workflow/steps/research.ts

@@ -1,203 +1,223 @@
-import { query } from '@anthropic-ai/claude-agent-sdk';
-import { RESEARCH_SYSTEM_PROMPT } from '../../agents/research.js';
-import type { WorkflowStepRunner } from '../types.js';
-import type { ResearchEvaluation } from '../../types.js';
-import { finalizeStepGitActions } from '../utils.js';
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { POSTHOG_NOTIFICATIONS } from "../../acp-extensions.js";
+import { RESEARCH_SYSTEM_PROMPT } from "../../agents/research.js";
+import type { ResearchEvaluation } from "../../types.js";
+import type { WorkflowStepRunner } from "../types.js";
+import { finalizeStepGitActions } from "../utils.js";
 
 export const researchStep: WorkflowStepRunner = async ({ step, context }) => {
-    const {
-        task,
-        cwd,
-        isCloudMode,
-        options,
-        logger,
-        fileManager,
-        gitManager,
-        promptBuilder,
-        adapter,
-        mcpServers,
-        emitEvent,
-    } = context;
-
-    const stepLogger = logger.child('ResearchStep');
-
-    const existingResearch = await fileManager.readResearch(task.id);
-    if (existingResearch) {
-        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' };
-    }
-
-    stepLogger.info('Starting research phase', { taskId: task.id });
-    emitEvent(adapter.createStatusEvent('phase_start', { phase: 'research' }));
-
-    const researchPrompt = await promptBuilder.buildResearchPrompt(task, cwd);
-    const fullPrompt = `${RESEARCH_SYSTEM_PROMPT}\n\n${researchPrompt}`;
-
-    const baseOptions: Record<string, any> = {
-        model: step.model,
-        cwd,
-        permissionMode: 'plan',
-        settingSources: ['local'],
-        mcpServers,
-        // Allow research tools: read-only operations, web search, and MCP resources
-        allowedTools: [
-            'Read',
-            'Glob',
-            'Grep',
-            'WebFetch',
-            'WebSearch',
-            'ListMcpResources',
-            'ReadMcpResource',
-            'TodoWrite',
-            'BashOutput',
-        ],
-    };
-
-    const response = query({
-        prompt: fullPrompt,
-        options: { ...baseOptions, ...(options.queryOverrides || {}) },
+  const {
+    task,
+    cwd,
+    isCloudMode,
+    options,
+    logger,
+    fileManager,
+    gitManager,
+    promptBuilder,
+    sessionId,
+    mcpServers,
+    sendNotification,
+  } = context;
+
+  const stepLogger = logger.child("ResearchStep");
+
+  const existingResearch = await fileManager.readResearch(task.id);
+  if (existingResearch) {
+    stepLogger.info("Research already exists", {
+      taskId: task.id,
+      hasQuestions: !!existingResearch.questions,
+      answered: existingResearch.answered,
     });
 
-    let jsonContent = '';
-    for await (const message of response) {
-        emitEvent(adapter.createRawSDKEvent(message));
-        const transformedEvents = adapter.transform(message);
-        for (const event of transformedEvents) {
-            emitEvent(event);
-        }
-        if (message.type === 'assistant' && message.message?.content) {
-            for (const c of message.message.content) {
-                if (c.type === 'text' && c.text) {
-                    jsonContent += c.text;
-                }
-            }
-        }
-    }
-
-    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',
+    // 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,
+      });
+
+      await sendNotification(POSTHOG_NOTIFICATIONS.ARTIFACT, {
+        sessionId,
+        kind: "research_questions",
+        content: existingResearch.questions,
+      });
+
+      // In local mode, halt to allow user to answer
+      if (!isCloudMode) {
+        await sendNotification(POSTHOG_NOTIFICATIONS.PHASE_COMPLETE, {
+          sessionId,
+          phase: "research",
         });
-        return { status: 'completed', halt: true };
+        return { status: "skipped", 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');
+    return { status: "skipped" };
+  }
+
+  stepLogger.info("Starting research phase", { taskId: task.id });
+  await sendNotification(POSTHOG_NOTIFICATIONS.PHASE_START, {
+    sessionId,
+    phase: "research",
+  });
+
+  const researchPrompt = await promptBuilder.buildResearchPrompt(task, cwd);
+  const fullPrompt = `${RESEARCH_SYSTEM_PROMPT}\n\n${researchPrompt}`;
+
+  const baseOptions: Record<string, unknown> = {
+    model: step.model,
+    cwd,
+    permissionMode: "plan",
+    settingSources: ["local"],
+    mcpServers,
+    // Allow research tools: read-only operations, web search, and MCP resources
+    allowedTools: [
+      "Read",
+      "Glob",
+      "Grep",
+      "WebFetch",
+      "WebSearch",
+      "ListMcpResources",
+      "ReadMcpResource",
+      "TodoWrite",
+      "BashOutput",
+    ],
+  };
+
+  const response = query({
+    prompt: fullPrompt,
+    options: { ...baseOptions, ...(options.queryOverrides || {}) },
+  });
+
+  let jsonContent = "";
+  try {
+    for await (const message of response) {
+      // Extract text content from assistant messages
+      if (message.type === "assistant" && message.message?.content) {
+        for (const c of message.message.content) {
+          if (c.type === "text" && c.text) {
+            jsonContent += c.text;
+          }
         }
-        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;
+  } catch (error) {
+    stepLogger.error("Error during research step query", error);
+    throw error;
+  }
+
+  if (!jsonContent.trim()) {
+    stepLogger.error("No JSON output from research agent", { taskId: task.id });
+    await sendNotification(POSTHOG_NOTIFICATIONS.ERROR, {
+      sessionId,
+      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");
     }
-
-    // Always write research.json
-    await fileManager.writeResearch(task.id, evaluation);
-    stepLogger.info('Research evaluation written', {
-        taskId: task.id,
-        score: evaluation.actionabilityScore,
-        hasQuestions: !!evaluation.questions,
+    evaluation = JSON.parse(jsonMatch[0]);
+    stepLogger.info("Parsed research evaluation", {
+      taskId: task.id,
+      score: evaluation.actionabilityScore,
+      hasQuestions: !!evaluation.questions,
     });
-
-    emitEvent({
-        type: 'artifact',
-        ts: Date.now(),
-        kind: 'research_evaluation',
-        content: evaluation,
+  } 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),
     });
-
-    await gitManager.addAllPostHogFiles();
-    await finalizeStepGitActions(context, step, {
-        commitMessage: `Research phase for ${task.title}`,
+    await sendNotification(POSTHOG_NOTIFICATIONS.ERROR, {
+      sessionId,
+      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,
+  });
+
+  await sendNotification(POSTHOG_NOTIFICATIONS.ARTIFACT, {
+    sessionId,
+    kind: "research_evaluation",
+    content: evaluation,
+  });
+
+  await gitManager.addAllPostHogFiles();
+  await finalizeStepGitActions(context, step, {
+    commitMessage: `Research phase for ${task.title}`,
+  });
+
+  // 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,
     });
 
-    // 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: 'artifact',
-            ts: Date.now(),
-            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 };
-    }
-
-    // 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 };
-    }
+    await sendNotification(POSTHOG_NOTIFICATIONS.ARTIFACT, {
+      sessionId,
+      kind: "research_questions",
+      content: evaluation.questions,
+    });
+  } else {
+    stepLogger.info("Actionability score acceptable, proceeding to planning", {
+      taskId: task.id,
+      score: evaluation.actionabilityScore,
+    });
+  }
 
-    // No questions or questions already answered - proceed to planning
-    emitEvent(adapter.createStatusEvent('phase_complete', { phase: 'research' }));
-    return { status: 'completed' };
+  // In local mode, always halt after research for user review
+  if (!isCloudMode) {
+    await sendNotification(POSTHOG_NOTIFICATIONS.PHASE_COMPLETE, {
+      sessionId,
+      phase: "research",
+    });
+    return { status: "completed", halt: true };
+  }
+
+  // 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
+    await sendNotification(POSTHOG_NOTIFICATIONS.PHASE_COMPLETE, {
+      sessionId,
+      phase: "research",
+    });
+    return { status: "completed", halt: true };
+  }
+
+  // No questions or questions already answered - proceed to planning
+  await sendNotification(POSTHOG_NOTIFICATIONS.PHASE_COMPLETE, {
+    sessionId,
+    phase: "research",
+  });
+  return { status: "completed" };
 };

package/src/workflow/types.ts

@@ -1,51 +1,62 @@
-import type { Task, TaskExecutionOptions, PermissionMode } from '../types.js';
-import type { Logger } from '../utils/logger.js';
-import type { PostHogFileManager } from '../file-manager.js';
-import type { GitManager } from '../git-manager.js';
-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 { AgentSideConnection } from "@agentclientprotocol/sdk";
+import type { PostHogFileManager } from "../file-manager.js";
+import type { GitManager } from "../git-manager.js";
+import type { PostHogAPIClient } from "../posthog-api.js";
+import type { PromptBuilder } from "../prompt-builder.js";
+import type { PermissionMode, Task, TaskExecutionOptions } from "../types.js";
+import type { Logger } from "../utils/logger.js";
+
+/**
+ * Function type for sending custom PostHog notifications via ACP extNotification.
+ * Used by workflow steps to emit artifacts, phase updates, etc.
+ */
+export type SendNotification = (
+  method: string,
+  params: Record<string, unknown>,
+) => Promise<void>;
 
 export interface WorkflowRuntime {
-    task: Task;
-    taskSlug: string;
-    cwd: string;
-    isCloudMode: boolean;
-    options: TaskExecutionOptions;
-    logger: Logger;
-    fileManager: PostHogFileManager;
-    gitManager: GitManager;
-    promptBuilder: PromptBuilder;
-    progressReporter: TaskProgressReporter;
-    adapter: ProviderAdapter;
-    mcpServers?: Record<string, any>;
-    posthogAPI?: PostHogAPIClient;
-    emitEvent: (event: any) => void;
-    stepResults: Record<string, any>;
+  task: Task;
+  taskSlug: string;
+  runId: string;
+  cwd: string;
+  isCloudMode: boolean;
+  options: TaskExecutionOptions;
+  logger: Logger;
+  fileManager: PostHogFileManager;
+  gitManager: GitManager;
+  promptBuilder: PromptBuilder;
+  connection: AgentSideConnection;
+  sessionId: string;
+  mcpServers?: Record<string, unknown>;
+  posthogAPI?: PostHogAPIClient;
+  sendNotification: SendNotification;
+  stepResults: Record<string, unknown>;
 }
 
 export interface WorkflowStepDefinition {
-    id: string;
-    name: string;
-    agent: string;
-    model: string;
-    permissionMode?: PermissionMode | string;
-    commit?: boolean;
-    push?: boolean;
-    run: WorkflowStepRunner;
+  id: string;
+  name: string;
+  agent: string;
+  model: string;
+  permissionMode?: PermissionMode | string;
+  commit?: boolean;
+  push?: boolean;
+  run: WorkflowStepRunner;
 }
 
 export interface WorkflowStepRuntime {
-    step: WorkflowStepDefinition;
-    context: WorkflowRuntime;
+  step: WorkflowStepDefinition;
+  context: WorkflowRuntime;
 }
 
 export interface WorkflowStepResult {
-    status: 'completed' | 'skipped';
-    halt?: boolean;
+  status: "completed" | "skipped";
+  halt?: boolean;
 }
 
-export type WorkflowStepRunner = (runtime: WorkflowStepRuntime) => Promise<WorkflowStepResult>;
+export type WorkflowStepRunner = (
+  runtime: WorkflowStepRuntime,
+) => Promise<WorkflowStepResult>;
 
 export type WorkflowDefinition = WorkflowStepDefinition[];

package/src/workflow/utils.ts

@@ -1,8 +1,8 @@
-import type { WorkflowRuntime, WorkflowStepDefinition } from './types.js';
+import type { WorkflowRuntime, WorkflowStepDefinition } from "./types.js";
 
 interface FinalizeGitOptions {
-    commitMessage: string;
-    allowEmptyCommit?: boolean;
+  commitMessage: string;
+  allowEmptyCommit?: boolean;
 }
 
 /**
@@ -10,41 +10,44 @@ interface FinalizeGitOptions {
  * Returns true if a commit was created.
  */
 export async function finalizeStepGitActions(
-    context: WorkflowRuntime,
-    step: WorkflowStepDefinition,
-    options: FinalizeGitOptions
+  context: WorkflowRuntime,
+  step: WorkflowStepDefinition,
+  options: FinalizeGitOptions,
 ): Promise<boolean> {
-    if (!step.commit) {
-        return false;
-    }
+  if (!step.commit) {
+    return false;
+  }
 
-    const { gitManager, logger } = context;
-    const hasStagedChanges = await gitManager.hasStagedChanges();
+  const { gitManager, logger } = context;
+  const hasStagedChanges = await gitManager.hasStagedChanges();
 
-    if (!hasStagedChanges && !options.allowEmptyCommit) {
-        logger.debug('No staged changes to commit for step', { stepId: step.id });
-        return false;
-    }
+  if (!hasStagedChanges && !options.allowEmptyCommit) {
+    logger.debug("No staged changes to commit for step", { stepId: step.id });
+    return false;
+  }
 
-    try {
-        await gitManager.commitChanges(options.commitMessage);
-        logger.info('Committed changes for step', {
-            stepId: step.id,
-            message: options.commitMessage,
-        });
-    } catch (error) {
-        logger.error('Failed to commit changes for step', {
-            stepId: step.id,
-            error: error instanceof Error ? error.message : String(error),
-        });
-        throw error;
-    }
+  try {
+    await gitManager.commitChanges(options.commitMessage);
+    logger.info("Committed changes for step", {
+      stepId: step.id,
+      message: options.commitMessage,
+    });
+  } catch (error) {
+    logger.error("Failed to commit changes for step", {
+      stepId: step.id,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    throw error;
+  }
 
-    if (step.push) {
-        const branchName = await gitManager.getCurrentBranch();
-        await gitManager.pushBranch(branchName);
-        logger.info('Pushed branch after step', { stepId: step.id, branch: branchName });
-    }
+  if (step.push) {
+    const branchName = await gitManager.getCurrentBranch();
+    await gitManager.pushBranch(branchName);
+    logger.info("Pushed branch after step", {
+      stepId: step.id,
+      branch: branchName,
+    });
+  }
 
-    return true;
+  return true;
 }