@posthog/agent 1.0.0

package/src/stage-executor.ts

@@ -0,0 +1,137 @@
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { Logger } from './utils/logger';
+import { EventTransformer } from './event-transformer';
+import { AgentRegistry } from './agent-registry';
+import type { Task } from './types';
+import type { WorkflowStage, WorkflowStageExecutionResult, WorkflowExecutionOptions } from './workflow-types';
+import { PLANNING_SYSTEM_PROMPT } from './agents/planning';
+import { EXECUTION_SYSTEM_PROMPT } from './agents/execution';
+import { PromptBuilder } from './prompt-builder';
+import { POSTHOG_MCP } from './utils/mcp';
+
+export class StageExecutor {
+  private registry: AgentRegistry;
+  private logger: Logger;
+  private eventTransformer: EventTransformer;
+  private promptBuilder: PromptBuilder;
+
+  constructor(registry: AgentRegistry, logger: Logger, promptBuilder?: PromptBuilder) {
+    this.registry = registry;
+    this.logger = logger.child('StageExecutor');
+    this.eventTransformer = new EventTransformer();
+    this.promptBuilder = promptBuilder || new PromptBuilder({
+      getTaskFiles: async () => [],
+      generatePlanTemplate: async () => '',
+      logger,
+    });
+  }
+
+  async execute(task: Task, stage: WorkflowStage, options: WorkflowExecutionOptions): Promise<WorkflowStageExecutionResult> {
+    const isManual = stage.is_manual_only === true;
+    if (isManual) {
+      this.logger.info('Manual stage detected; skipping agent execution', { stage: stage.key });
+      return { results: [] };
+    }
+
+    const inferredAgent = stage.key.toLowerCase().includes('plan') ? 'planning_basic' : 'code_generation';
+    const agentName = stage.agent_name || inferredAgent;
+    const agent = this.registry.getAgent(agentName);
+    if (!agent) {
+      throw new Error(`Unknown agent '${agentName}' for stage '${stage.key}'`);
+    }
+
+    const permissionMode = (options.permissionMode as any) || 'acceptEdits';
+    const cwd = options.repositoryPath || process.cwd();
+
+    switch (agent.agent_type) {
+      case 'planning':
+        return this.runPlanning(task, cwd, options, stage.key);
+      case 'execution':
+        return this.runExecution(task, cwd, permissionMode, options, stage.key);
+      case 'review': // TODO: Implement review
+      case 'testing': // TODO: Implement testing
+      default:
+        // throw new Error(`Unsupported agent type: ${agent.agent_type}`);
+        console.warn(`Unsupported agent type: ${agent.agent_type}`);
+        return { results: [] };
+    }
+  }
+
+  private async runPlanning(task: Task, cwd: string, options: WorkflowExecutionOptions, stageKey: string): Promise<WorkflowStageExecutionResult> {
+    const contextPrompt = await this.promptBuilder.buildPlanningPrompt(task);
+    let prompt = PLANNING_SYSTEM_PROMPT + '\n\n' + contextPrompt;
+
+    const stageOverrides = options.stageOverrides?.[stageKey] || options.stageOverrides?.['plan'];
+    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: {
+        ...POSTHOG_MCP
+      }
+    };
+
+    const response = query({
+      prompt,
+      options: { ...baseOptions, ...mergedOverrides },
+    });
+
+    let plan = '';
+    for await (const message of response) {
+      const transformed = this.eventTransformer.transform(message);
+      if (transformed && transformed.type !== 'token') {
+        this.logger.debug('Planning event', { type: transformed.type });
+      }
+      if (message.type === 'assistant' && message.message?.content) {
+        for (const c of message.message.content) {
+          if (c.type === 'text' && c.text) plan += c.text + '\n';
+        }
+      }
+    }
+
+    return { plan: plan.trim() };
+  }
+
+  private async runExecution(task: Task, cwd: string, permissionMode: WorkflowExecutionOptions['permissionMode'], options: WorkflowExecutionOptions, stageKey: string): Promise<WorkflowStageExecutionResult> {
+    const contextPrompt = await this.promptBuilder.buildExecutionPrompt(task);
+    let prompt = EXECUTION_SYSTEM_PROMPT + '\n\n' + contextPrompt;
+
+    const stageOverrides = options.stageOverrides?.[stageKey];
+    const mergedOverrides = {
+      ...(options.queryOverrides || {}),
+      ...(stageOverrides?.queryOverrides || {}),
+    } as Record<string, any>;
+
+    const baseOptions: Record<string, any> = {
+      model: 'claude-sonnet-4-5-20250929',
+      cwd,
+      permissionMode,
+      settingSources: ['local'],
+      mcpServers: {
+        ...POSTHOG_MCP
+      }
+    };
+
+    const response = query({
+      prompt,
+      options: { ...baseOptions, ...mergedOverrides },
+    });
+    const results: any[] = [];
+    for await (const message of response) {
+      const transformed = this.eventTransformer.transform(message);
+      if (transformed && transformed.type !== 'token') {
+        this.logger.debug('Execution event', { type: transformed.type });
+      }
+      results.push(message);
+    }
+    return { results };
+  }
+}
+
+

package/src/task-manager.ts

@@ -0,0 +1,155 @@
+import { randomBytes } from 'crypto';
+
+export interface TaskExecutionState {
+  taskId: string;
+  status: 'running' | 'completed' | 'failed' | 'canceled' | 'timeout';
+  mode: 'plan_only' | 'plan_and_build' | 'build_only';
+  result?: any;
+  startedAt: number;
+  completedAt?: number;
+  abortController?: AbortController;
+}
+
+export class TaskManager {
+  private executionStates = new Map<string, TaskExecutionState>();
+  private defaultTimeout = 10 * 60 * 1000; // 10 minutes
+
+  generateExecutionId(): string {
+    return randomBytes(16).toString('hex');
+  }
+
+  startExecution(
+    taskId: string, 
+    mode: 'plan_only' | 'plan_and_build' | 'build_only',
+    executionId: string = this.generateExecutionId()
+  ): TaskExecutionState {
+    const executionState: TaskExecutionState = {
+      taskId,
+      status: 'running',
+      mode,
+      startedAt: Date.now(),
+      abortController: new AbortController(),
+    };
+
+    this.executionStates.set(executionId, executionState);
+    this.scheduleTimeout(executionId);
+    
+    return executionState;
+  }
+
+  async waitForCompletion(executionId: string): Promise<any> {
+    const execution = this.executionStates.get(executionId);
+    if (!execution) {
+      throw new Error(`Execution ${executionId} not found`);
+    }
+
+    if (execution.result && execution.status === 'completed') {
+      return execution.result;
+    }
+
+    return new Promise((resolve, reject) => {
+      const checkInterval = setInterval(() => {
+        const currentExecution = this.executionStates.get(executionId);
+        if (!currentExecution) {
+          clearInterval(checkInterval);
+          reject(new Error(`Execution ${executionId} disappeared`));
+          return;
+        }
+
+        if (currentExecution.status === 'completed' && currentExecution.result) {
+          clearInterval(checkInterval);
+          resolve(currentExecution.result);
+        } else if (
+          currentExecution.status === 'failed' || 
+          currentExecution.status === 'canceled' || 
+          currentExecution.status === 'timeout'
+        ) {
+          clearInterval(checkInterval);
+          reject(new Error(`Execution ${executionId} ${currentExecution.status}`));
+        }
+      }, 100);
+    });
+  }
+
+  completeExecution(executionId: string, result: any): void {
+    const execution = this.executionStates.get(executionId);
+    if (!execution) {
+      throw new Error(`Execution ${executionId} not found`);
+    }
+
+    execution.status = 'completed';
+    execution.result = result;
+    execution.completedAt = Date.now();
+  }
+
+  failExecution(executionId: string, error: Error): void {
+    const execution = this.executionStates.get(executionId);
+    if (!execution) {
+      throw new Error(`Execution ${executionId} not found`);
+    }
+
+    execution.status = 'failed';
+    execution.completedAt = Date.now();
+    execution.result = {
+      error: error.message,
+      status: 'failed',
+    };
+  }
+
+  cancelExecution(executionId: string): void {
+    const execution = this.executionStates.get(executionId);
+    if (!execution) {
+      throw new Error(`Execution ${executionId} not found`);
+    }
+
+    execution.status = 'canceled';
+    execution.completedAt = Date.now();
+    execution.abortController?.abort();
+    
+    if (!execution.result) {
+      execution.result = {
+        status: 'canceled',
+        message: 'Execution was canceled',
+      };
+    }
+  }
+
+  getExecution(executionId: string): TaskExecutionState | undefined {
+    return this.executionStates.get(executionId);
+  }
+
+  getAbortSignal(executionId: string): AbortSignal | undefined {
+    return this.executionStates.get(executionId)?.abortController?.signal;
+  }
+
+  getAbortController(executionId: string): AbortController | undefined {
+    return this.executionStates.get(executionId)?.abortController;
+  }
+
+  private scheduleTimeout(executionId: string, timeout: number = this.defaultTimeout): void {
+    setTimeout(() => {
+      const execution = this.executionStates.get(executionId);
+      if (execution && execution.status === 'running') {
+        execution.status = 'timeout';
+        execution.completedAt = Date.now();
+        execution.abortController?.abort();
+        
+        if (!execution.result) {
+          execution.result = {
+            status: 'timeout',
+            message: 'Execution timed out',
+          };
+        }
+      }
+    }, timeout);
+  }
+
+  cleanup(olderThan: number = 60 * 60 * 1000): void {
+    const cutoff = Date.now() - olderThan;
+    for (const [executionId, execution] of this.executionStates) {
+      if (execution.completedAt && execution.completedAt < cutoff) {
+        this.executionStates.delete(executionId);
+      }
+    }
+  }
+}

package/src/template-manager.ts

@@ -0,0 +1,149 @@
+import { promises as fs } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+export interface TemplateVariables {
+  task_id: string;
+  task_title: string;
+  task_description?: string;
+  date: string;
+  repository?: string;
+  [key: string]: string | undefined;
+}
+
+export class TemplateManager {
+  private templatesDir: string;
+
+  constructor() {
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = dirname(__filename);
+    this.templatesDir = join(__dirname, 'templates');
+  }
+
+  private async loadTemplate(templateName: string): Promise<string> {
+    try {
+      const templatePath = join(this.templatesDir, templateName);
+      return await fs.readFile(templatePath, 'utf8');
+    } catch (error) {
+      throw new Error(`Failed to load template ${templateName}: ${error}`);
+    }
+  }
+
+  private substituteVariables(template: string, variables: TemplateVariables): string {
+    let result = template;
+    
+    for (const [key, value] of Object.entries(variables)) {
+      if (value !== undefined) {
+        const placeholder = new RegExp(`{{${key}}}`, 'g');
+        result = result.replace(placeholder, value);
+      }
+    }
+    
+    result = result.replace(/{{[^}]+}}/g, '[PLACEHOLDER]');
+    
+    return result;
+  }
+
+  async generatePlan(variables: TemplateVariables): Promise<string> {
+    const template = await this.loadTemplate('plan-template.md');
+    return this.substituteVariables(template, {
+      ...variables,
+      date: variables.date || new Date().toISOString().split('T')[0]
+    });
+  }
+
+
+  async generateCustomFile(templateName: string, variables: TemplateVariables): Promise<string> {
+    const template = await this.loadTemplate(templateName);
+    return this.substituteVariables(template, {
+      ...variables,
+      date: variables.date || new Date().toISOString().split('T')[0]
+    });
+  }
+
+  async createTaskStructure(taskId: string, taskTitle: string, options?: {
+    includePlan?: boolean;
+    additionalFiles?: Array<{
+      name: string;
+      template?: string;
+      content?: string;
+    }>;
+  }): Promise<Array<{ name: string; content: string; type: 'plan' | 'context' | 'reference' | 'output' }>> {
+    const files: Array<{ name: string; content: string; type: 'plan' | 'context' | 'reference' | 'output' }> = [];
+    
+    const variables: TemplateVariables = {
+      task_id: taskId,
+      task_title: taskTitle,
+      date: new Date().toISOString().split('T')[0]
+    };
+
+    // Generate plan file if requested
+    if (options?.includePlan !== false) {
+      const planContent = await this.generatePlan(variables);
+      files.push({
+        name: 'plan.md',
+        content: planContent,
+        type: 'plan'
+      });
+    }
+
+
+    if (options?.additionalFiles) {
+      for (const file of options.additionalFiles) {
+        let content: string;
+        
+        if (file.template) {
+          content = await this.generateCustomFile(file.template, variables);
+        } else if (file.content) {
+          content = this.substituteVariables(file.content, variables);
+        } else {
+          content = `# ${file.name}\n\nPlaceholder content for ${file.name}`;
+        }
+
+        files.push({
+          name: file.name,
+          content,
+          type: file.name.includes('context') ? 'context' : 'reference'
+        });
+      }
+    }
+
+    return files;
+  }
+
+  generatePostHogReadme(): string {
+    return `# PostHog Task Files
+
+This directory contains task-related files generated by the PostHog Agent.
+
+## Structure
+
+Each task has its own subdirectory: \`.posthog/{task-id}/\`
+
+### Common Files
+
+- **plan.md** - Implementation plan generated during planning phase
+- **Supporting files** - Any additional files added for task context
+- **artifacts/** - Generated files, outputs, and temporary artifacts
+
+### Usage
+
+These files are:
+- Version controlled alongside your code
+- Used by the PostHog Agent for context
+- Available for review in pull requests
+- Organized by task ID for easy reference
+
+### Gitignore
+
+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
+
+---
+
+*Generated by PostHog Agent*
+`;
+  }
+}

package/src/templates/plan-template.md

@@ -0,0 +1,45 @@
+# Implementation Plan: {{task_title}}
+
+**Task ID:** {{task_id}}  
+**Generated:** {{date}}
+
+## Summary
+
+Brief description of what will be implemented and the overall approach.
+
+## Implementation Steps
+
+### 1. Analysis
+- [ ] Identify relevant files and components
+- [ ] Review existing patterns and constraints
+
+### 2. Changes Required
+- [ ] Files to create/modify
+- [ ] Dependencies to add/update
+
+### 3. Implementation
+- [ ] Core functionality changes
+- [ ] Tests and validation
+- [ ] Documentation updates
+
+## File Changes
+
+### New Files
+```
+path/to/new/file.ts - Purpose
+```
+
+### Modified Files
+```
+path/to/existing/file.ts - Changes needed
+```
+
+## Considerations
+
+- Key architectural decisions
+- Potential risks and mitigation
+- Testing approach
+
+---
+
+*Generated by PostHog Agent*

package/src/types.ts

@@ -0,0 +1,223 @@
+// PostHog Task model (matches Array's OpenAPI schema)
+export interface Task {
+  id: string;
+  title: string;
+  description: string;
+  origin_product: 'error_tracking' | 'eval_clusters' | 'user_created' | 'support_queue' | 'session_summaries';
+  position?: number;
+  workflow?: string | null;
+  current_stage?: string | null;
+  github_integration?: number | null;
+  repository_config?: unknown; // JSONField
+  repository_list: string;
+  primary_repository: string;
+  github_branch: string | null;
+  github_pr_url: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface SupportingFile {
+  name: string;
+  content: string;
+  type: 'plan' | 'context' | 'reference' | 'output';
+  created_at: string;
+}
+
+// Removed legacy ExecutionMode in favor of configurable workflows
+
+export enum PermissionMode {
+  PLAN = "plan",
+  DEFAULT = "default",
+  ACCEPT_EDITS = "acceptEdits",
+  BYPASS = "bypassPermissions"
+}
+
+export interface ExecutionOptions {
+  repositoryPath?: string;
+  permissionMode?: PermissionMode;
+}
+
+// Base event with timestamp
+interface BaseEvent {
+  ts: number;
+}
+
+// Streaming content events
+export interface TokenEvent extends BaseEvent {
+  type: 'token';
+  content: string;
+  contentType?: 'text' | 'thinking' | 'tool_input';
+}
+
+export interface ContentBlockStartEvent extends BaseEvent {
+  type: 'content_block_start';
+  index: number;
+  contentType: 'text' | 'tool_use' | 'thinking';
+  toolName?: string;
+  toolId?: string;
+}
+
+export interface ContentBlockStopEvent extends BaseEvent {
+  type: 'content_block_stop';
+  index: number;
+}
+
+// Tool events
+export interface ToolCallEvent extends BaseEvent {
+  type: 'tool_call';
+  toolName: string;
+  callId: string;
+  args: Record<string, any>;
+}
+
+export interface ToolResultEvent extends BaseEvent {
+  type: 'tool_result';
+  toolName: string;
+  callId: string;
+  result: any;
+}
+
+// Message lifecycle events
+export interface MessageStartEvent extends BaseEvent {
+  type: 'message_start';
+  messageId?: string;
+  model?: string;
+}
+
+export interface MessageDeltaEvent extends BaseEvent {
+  type: 'message_delta';
+  stopReason?: string;
+  stopSequence?: string;
+  usage?: {
+    outputTokens: number;
+  };
+}
+
+export interface MessageStopEvent extends BaseEvent {
+  type: 'message_stop';
+}
+
+// User message events
+export interface UserMessageEvent extends BaseEvent {
+  type: 'user_message';
+  content: string;
+  isSynthetic?: boolean;
+}
+
+// System events
+export interface StatusEvent extends BaseEvent {
+  type: 'status';
+  phase: string;
+  [key: string]: any;
+}
+
+export interface InitEvent extends BaseEvent {
+  type: 'init';
+  model: string;
+  tools: string[];
+  permissionMode: string;
+  cwd: string;
+  apiKeySource: string;
+}
+
+export interface CompactBoundaryEvent extends BaseEvent {
+  type: 'compact_boundary';
+  trigger: 'manual' | 'auto';
+  preTokens: number;
+}
+
+// Result events
+export interface DoneEvent extends BaseEvent {
+  type: 'done';
+  durationMs?: number;
+  numTurns?: number;
+  totalCostUsd?: number;
+  usage?: any;
+}
+
+export interface ErrorEvent extends BaseEvent {
+  type: 'error';
+  message: string;
+  error?: any;
+  errorType?: string;
+}
+
+// Legacy events (keeping for backwards compatibility)
+export interface DiffEvent extends BaseEvent {
+  type: 'diff';
+  file: string;
+  patch: string;
+  summary?: string;
+}
+
+export interface FileWriteEvent extends BaseEvent {
+  type: 'file_write';
+  path: string;
+  bytes: number;
+}
+
+export interface MetricEvent extends BaseEvent {
+  type: 'metric';
+  key: string;
+  value: number;
+  unit?: string;
+}
+
+export interface ArtifactEvent extends BaseEvent {
+  type: 'artifact';
+  kind: string;
+  content: any;
+}
+
+export type AgentEvent =
+  | TokenEvent
+  | ContentBlockStartEvent
+  | ContentBlockStopEvent
+  | ToolCallEvent
+  | ToolResultEvent
+  | MessageStartEvent
+  | MessageDeltaEvent
+  | MessageStopEvent
+  | UserMessageEvent
+  | StatusEvent
+  | InitEvent
+  | CompactBoundaryEvent
+  | DoneEvent
+  | ErrorEvent
+  | DiffEvent
+  | FileWriteEvent
+  | MetricEvent
+  | ArtifactEvent;
+
+export interface ExecutionResult {
+  results: any[];
+}
+
+export interface PlanResult {
+  plan: string;
+}
+
+export interface TaskExecutionResult {
+  task: Task;
+  plan?: string;
+  executionResult?: ExecutionResult;
+  // Deprecated: mode removed in workflow-based execution
+}
+
+export interface AgentConfig {
+  workingDirectory?: string;
+  onEvent?: (event: AgentEvent) => void;
+  
+  // PostHog API configuration
+  posthogApiUrl?: string;
+  posthogApiKey?: string;
+  
+  // Logging configuration
+  debug?: boolean;
+}
+
+export interface PostHogAPIConfig {
+  apiUrl: string;
+  apiKey: string;
+}