@posthog/agent 1.0.0

package/src/agent.ts

@@ -0,0 +1,428 @@
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import type { Task, ExecutionResult, PlanResult, AgentConfig } from './types';
+import type { WorkflowDefinition, WorkflowStage, WorkflowExecutionOptions } from './workflow-types';
+import { TaskManager } from './task-manager';
+import { PostHogAPIClient } from './posthog-api';
+import { PostHogFileManager } from './file-manager';
+import { GitManager } from './git-manager';
+import { TemplateManager } from './template-manager';
+import { EventTransformer } from './event-transformer';
+import { PLANNING_SYSTEM_PROMPT } from './agents/planning';
+import { EXECUTION_SYSTEM_PROMPT } from './agents/execution';
+import { Logger } from './utils/logger';
+import { AgentRegistry } from './agent-registry';
+import { WorkflowRegistry } from './workflow-registry';
+import { StageExecutor } from './stage-executor';
+import { PromptBuilder } from './prompt-builder';
+
+export class Agent {
+    private workingDirectory: string;
+    private onEvent?: (event: any) => void;
+    private taskManager: TaskManager;
+    private posthogAPI?: PostHogAPIClient;
+    private fileManager: PostHogFileManager;
+    private gitManager: GitManager;
+    private templateManager: TemplateManager;
+    private eventTransformer: EventTransformer;
+    private logger: Logger;
+    private agentRegistry: AgentRegistry;
+    private workflowRegistry: WorkflowRegistry;
+    private stageExecutor: StageExecutor;
+    public debug: boolean;
+
+    constructor(config: AgentConfig = {}) {
+        this.workingDirectory = config.workingDirectory || process.cwd();
+        this.onEvent = config.onEvent;
+        this.debug = config.debug || false;
+        this.logger = new Logger({ debug: this.debug, prefix: '[PostHog Agent]' });
+        this.taskManager = new TaskManager();
+        this.eventTransformer = new EventTransformer();
+
+        this.fileManager = new PostHogFileManager(
+            this.workingDirectory,
+            this.logger.child('FileManager')
+        );
+        this.gitManager = new GitManager({
+            repositoryPath: this.workingDirectory,
+            logger: this.logger.child('GitManager')
+            // TODO: Add author config from environment or config
+        });
+        this.templateManager = new TemplateManager();
+        this.agentRegistry = new AgentRegistry();
+
+        if (config.posthogApiUrl && config.posthogApiKey) {
+            this.posthogAPI = new PostHogAPIClient({
+                apiUrl: config.posthogApiUrl,
+                apiKey: config.posthogApiKey,
+            });
+        }
+
+        this.workflowRegistry = new WorkflowRegistry(this.posthogAPI);
+        const promptBuilder = new PromptBuilder({
+            getTaskFiles: (taskId: string) => this.getTaskFiles(taskId),
+            generatePlanTemplate: (vars) => this.templateManager.generatePlan(vars),
+            logger: this.logger.child('PromptBuilder')
+        });
+        this.stageExecutor = new StageExecutor(this.agentRegistry, this.logger, promptBuilder);
+    }
+
+    /**
+     * Enable or disable debug logging
+     */
+    setDebug(enabled: boolean) {
+        this.debug = enabled;
+        this.logger.setDebug(enabled);
+    }
+
+    // Workflow-based execution
+    async runWorkflow(taskOrId: Task | string, workflowId: string, options: WorkflowExecutionOptions = {}): Promise<{ task: Task; workflow: WorkflowDefinition }> {
+        const task = typeof taskOrId === 'string' ? await this.fetchTask(taskOrId) : taskOrId;
+        await this.workflowRegistry.loadWorkflows();
+        const workflow = this.workflowRegistry.getWorkflow(workflowId);
+        if (!workflow) {
+            throw new Error(`Workflow ${workflowId} not found`);
+        }
+
+        // Ensure task is assigned to workflow and positioned at first stage
+        if (this.posthogAPI) {
+            try {
+                if ((task.workflow as any) !== workflowId) {
+                    await this.posthogAPI.updateTask(task.id, { workflow: workflowId } as any);
+                    (task as any).workflow = workflowId;
+                }
+                if (!(task as any).current_stage && workflow.stages.length > 0) {
+                    const firstStage = [...workflow.stages].sort((a, b) => a.position - b.position)[0];
+                    await this.posthogAPI.updateTaskStage(task.id, firstStage.id);
+                    (task as any).current_stage = firstStage.id;
+                }
+            } catch (e) {
+                this.logger.warn('Failed to sync task workflow/stage before execution', { error: (e as Error).message });
+            }
+        }
+
+        const executionId = this.taskManager.generateExecutionId();
+        this.logger.info('Starting workflow execution', { taskId: task.id, workflowId, executionId });
+        this.taskManager.startExecution(task.id, 'plan_and_build', executionId);
+
+        try {
+            const orderedStages = [...workflow.stages].sort((a, b) => a.position - b.position);
+            let startIndex = 0;
+            const currentStageId = (task as any).current_stage as string | undefined;
+
+            // If task is already at the last stage, fail gracefully without progressing
+            if (currentStageId) {
+                const currIdx = orderedStages.findIndex(s => s.id === currentStageId);
+                const atLastStage = currIdx >= 0 && currIdx === orderedStages.length - 1;
+                if (atLastStage) {
+                    this.emitEvent(this.eventTransformer.createStatusEvent('no_next_stage', { stage: orderedStages[currIdx].key }));
+                    this.taskManager.completeExecution(executionId, { task, workflow });
+                    return { task, workflow };
+                }
+            }
+
+            if (options.resumeFromCurrentStage && currentStageId) {
+                const idx = orderedStages.findIndex(s => s.id === currentStageId);
+                if (idx >= 0) startIndex = idx;
+            }
+
+            // Align server-side stage when restarting from the beginning
+            if (this.posthogAPI) {
+                const targetStage = orderedStages[startIndex];
+                if (targetStage && targetStage.id !== currentStageId) {
+                    try { await this.posthogAPI.updateTaskStage(task.id, targetStage.id); (task as any).current_stage = targetStage.id; } catch {}
+                }
+            }
+
+            for (let i = startIndex; i < orderedStages.length; i++) {
+                const stage = orderedStages[i];
+                await this.executeStage(task, stage, options);
+                if (options.autoProgress) {
+                    const hasNext = i < orderedStages.length - 1;
+                    if (hasNext) {
+                        await this.progressToNextStage(task.id);
+                    }
+                }
+            }
+            this.taskManager.completeExecution(executionId, { task, workflow });
+            return { task, workflow };
+        } catch (error) {
+            this.taskManager.failExecution(executionId, error as Error);
+            throw error;
+        }
+    }
+
+    async executeStage(task: Task, stage: WorkflowStage, options: WorkflowExecutionOptions = {}): Promise<void> {
+        this.emitEvent(this.eventTransformer.createStatusEvent('stage_start', { stage: stage.key }));
+        const overrides = options.stageOverrides?.[stage.key];
+        const agentName = stage.agent_name || 'code_generation';
+        const agentDef = this.agentRegistry.getAgent(agentName);
+        const isManual = stage.is_manual_only === true;
+        const stageKeyLower = (stage.key || '').toLowerCase().trim();
+        const isPlanningByKey = stageKeyLower === 'plan' || stageKeyLower.includes('plan');
+        const isPlanning = !isManual && ((agentDef?.agent_type === 'planning') || isPlanningByKey);
+        const shouldCreatePlanningBranch = overrides?.createPlanningBranch !== false; // default true
+        const shouldCreateImplBranch = overrides?.createImplementationBranch !== false; // default true
+
+        if (isPlanning && shouldCreatePlanningBranch) {
+            const planningBranch = await this.createPlanningBranch(task.id);
+            await this.updateTaskBranch(task.id, planningBranch);
+            this.emitEvent(this.eventTransformer.createStatusEvent('branch_created', { stage: stage.key, branch: planningBranch }));
+        } else if (!isPlanning && !isManual && shouldCreateImplBranch) {
+            const implBranch = await this.createImplementationBranch(task.id);
+            await this.updateTaskBranch(task.id, implBranch);
+            this.emitEvent(this.eventTransformer.createStatusEvent('branch_created', { stage: stage.key, branch: implBranch }));
+        }
+
+        const result = await this.stageExecutor.execute(task, stage, options);
+
+        if (result.plan) {
+            await this.writePlan(task.id, result.plan);
+            await this.commitPlan(task.id, task.title);
+            this.emitEvent(this.eventTransformer.createStatusEvent('commit_made', { stage: stage.key, kind: 'plan' }));
+        }
+
+        if (isManual) {
+            const defaultOpenPR = true; // manual stages default to PR for review
+            const openPR = overrides?.openPullRequest ?? defaultOpenPR;
+            if (openPR) {
+                // Ensure we're on an implementation branch for PRs
+                let branchName = await this.gitManager.getCurrentBranch();
+                const onTaskBranch = branchName.includes(`posthog/task-${task.id}`);
+                if (!onTaskBranch && (overrides?.createImplementationBranch !== false)) {
+                    const implBranch = await this.createImplementationBranch(task.id);
+                    await this.updateTaskBranch(task.id, implBranch);
+                    branchName = implBranch;
+                    this.emitEvent(this.eventTransformer.createStatusEvent('branch_created', { stage: stage.key, branch: implBranch }));
+                }
+                try {
+                    const prUrl = await this.createPullRequest(task.id, branchName, task.title, task.description);
+                    await this.updateTaskBranch(task.id, branchName);
+                    await this.attachPullRequestToTask(task.id, prUrl);
+                    this.emitEvent(this.eventTransformer.createStatusEvent('pr_created', { stage: stage.key, prUrl }));
+                } catch {}
+            }
+            // Do not auto-progress on manual stages
+            this.emitEvent(this.eventTransformer.createStatusEvent('stage_complete', { stage: stage.key }));
+            return;
+        }
+
+        if (result.results) {
+            const existingPlan = await this.readPlan(task.id);
+            const planSummary = existingPlan ? existingPlan.split('\n')[0] : undefined;
+            await this.commitImplementation(task.id, task.title, planSummary);
+            this.emitEvent(this.eventTransformer.createStatusEvent('commit_made', { stage: stage.key, kind: 'implementation' }));
+        }
+
+        // PR creation on complete stage (or if explicitly requested), regardless of whether edits occurred
+        {
+            const defaultOpenPR = stage.key.toLowerCase().includes('complete');
+            const openPR = overrides?.openPullRequest ?? defaultOpenPR;
+            if (openPR) {
+                const branchName = await this.gitManager.getCurrentBranch();
+                try {
+                    const prUrl = await this.createPullRequest(task.id, branchName, task.title, task.description);
+                    await this.updateTaskBranch(task.id, branchName);
+                    await this.attachPullRequestToTask(task.id, prUrl);
+                    this.emitEvent(this.eventTransformer.createStatusEvent('pr_created', { stage: stage.key, prUrl }));
+                } catch {}
+            }
+        }
+
+        this.emitEvent(this.eventTransformer.createStatusEvent('stage_complete', { stage: stage.key }));
+    }
+
+    async progressToNextStage(taskId: string): Promise<void> {
+        if (!this.posthogAPI) throw new Error('PostHog API not configured. Cannot progress stage.');
+        await this.posthogAPI.progressTask(taskId, { auto: true });
+    }
+
+    // Direct prompt execution - still supported for low-level usage
+    async run(prompt: string, options: { repositoryPath?: string; permissionMode?: import('./types').PermissionMode; queryOverrides?: Record<string, any> } = {}): Promise<ExecutionResult> {
+        const baseOptions: Record<string, any> = {
+            model: "claude-4-5-sonnet",
+            cwd: options.repositoryPath || this.workingDirectory,
+            permissionMode: (options.permissionMode as any) || "default",
+            settingSources: ["local"],
+        };
+
+        const response = query({
+            prompt,
+            options: { ...baseOptions, ...(options.queryOverrides || {}) },
+        });
+
+        const results = [];
+        for await (const message of response) {
+            this.logger.debug('Received message in direct run', { type: message.type });
+            const transformedEvent = this.eventTransformer.transform(message);
+            this.onEvent?.(transformedEvent);
+            results.push(message);
+        }
+        
+        return { results };
+    }
+    
+    // PostHog task operations
+    async fetchTask(taskId: string): Promise<Task> {
+        this.logger.debug('Fetching task from PostHog', { taskId });
+        if (!this.posthogAPI) {
+            const error = new Error('PostHog API not configured. Provide posthogApiUrl and posthogApiKey in constructor.');
+            this.logger.error('PostHog API not configured', error);
+            throw error;
+        }
+        return this.posthogAPI.fetchTask(taskId);
+    }
+    
+    async listTasks(filters?: {
+        repository?: string;
+        organization?: string;
+        origin_product?: string;
+        workflow?: string;
+        current_stage?: string;
+    }): Promise<Task[]> {
+        if (!this.posthogAPI) {
+            throw new Error('PostHog API not configured. Provide posthogApiUrl and posthogApiKey in constructor.');
+        }
+        return this.posthogAPI.listTasks(filters);
+    }
+    
+    // File system operations for task artifacts
+    async writeTaskFile(taskId: string, fileName: string, content: string, type: 'plan' | 'context' | 'reference' | 'output' = 'reference'): Promise<void> {
+        this.logger.debug('Writing task file', { taskId, fileName, type, contentLength: content.length });
+        await this.fileManager.writeTaskFile(taskId, { name: fileName, content, type });
+    }
+    
+    async readTaskFile(taskId: string, fileName: string): Promise<string | null> {
+        this.logger.debug('Reading task file', { taskId, fileName });
+        return await this.fileManager.readTaskFile(taskId, fileName);
+    }
+    
+    async getTaskFiles(taskId: string): Promise<any[]> {
+        this.logger.debug('Getting task files', { taskId });
+        const files = await this.fileManager.getTaskFiles(taskId);
+        this.logger.debug('Found task files', { taskId, fileCount: files.length });
+        return files;
+    }
+    
+    async writePlan(taskId: string, plan: string): Promise<void> {
+        this.logger.info('Writing plan', { taskId, planLength: plan.length });
+        await this.fileManager.writePlan(taskId, plan);
+    }
+    
+    async readPlan(taskId: string): Promise<string | null> {
+        this.logger.debug('Reading plan', { taskId });
+        return await this.fileManager.readPlan(taskId);
+    }
+    
+    // Git operations for task workflow
+    async createPlanningBranch(taskId: string): Promise<string> {
+        this.logger.info('Creating planning branch', { taskId });
+        const branchName = await this.gitManager.createTaskPlanningBranch(taskId);
+        this.logger.debug('Planning branch created', { taskId, branchName });
+        // Only create gitignore after we're on the new branch
+        await this.fileManager.ensureGitignore();
+        return branchName;
+    }
+    
+    async commitPlan(taskId: string, taskTitle: string): Promise<string> {
+        this.logger.info('Committing plan', { taskId, taskTitle });
+        const commitHash = await this.gitManager.commitPlan(taskId, taskTitle);
+        this.logger.debug('Plan committed', { taskId, commitHash });
+        return commitHash;
+    }
+    
+    async createImplementationBranch(taskId: string, planningBranchName?: string): Promise<string> {
+        this.logger.info('Creating implementation branch', { taskId, fromBranch: planningBranchName });
+        const branchName = await this.gitManager.createTaskImplementationBranch(taskId, planningBranchName);
+        this.logger.debug('Implementation branch created', { taskId, branchName });
+        return branchName;
+    }
+    
+    async commitImplementation(taskId: string, taskTitle: string, planSummary?: string): Promise<string> {
+        this.logger.info('Committing implementation', { taskId, taskTitle });
+        const commitHash = await this.gitManager.commitImplementation(taskId, taskTitle, planSummary);
+        this.logger.debug('Implementation committed', { taskId, commitHash });
+        return commitHash;
+    }
+
+    async createPullRequest(taskId: string, branchName: string, taskTitle: string, taskDescription: string): Promise<string> {
+        this.logger.info('Creating pull request', { taskId, branchName, taskTitle });
+
+        // Build PR body
+        const prBody = `## Task Details
+**Task ID**: ${taskId}
+**Description**: ${taskDescription}
+
+## Changes
+This PR implements the changes described in the task.
+
+Generated by PostHog Agent`;
+
+        const prUrl = await this.gitManager.createPullRequest(
+            branchName,
+            taskTitle,
+            prBody
+        );
+
+        this.logger.info('Pull request created', { taskId, prUrl });
+        return prUrl;
+    }
+
+    async attachPullRequestToTask(taskId: string, prUrl: string): Promise<void> {
+        this.logger.info('Attaching PR to task', { taskId, prUrl });
+
+        if (!this.posthogAPI) {
+            const error = new Error('PostHog API not configured. Cannot attach PR to task.');
+            this.logger.error('PostHog API not configured', error);
+            throw error;
+        }
+
+        await this.posthogAPI.updateTask(taskId, { github_pr_url: prUrl });
+        this.logger.debug('PR attached to task', { taskId, prUrl });
+    }
+
+    async updateTaskBranch(taskId: string, branchName: string): Promise<void> {
+        this.logger.info('Updating task branch', { taskId, branchName });
+
+        if (!this.posthogAPI) {
+            const error = new Error('PostHog API not configured. Cannot update task branch.');
+            this.logger.error('PostHog API not configured', error);
+            throw error;
+        }
+
+        await this.posthogAPI.updateTask(taskId, { github_branch: branchName });
+        this.logger.debug('Task branch updated', { taskId, branchName });
+    }
+
+    // Execution management
+    cancelTask(taskId: string): void {
+        // Find the execution for this task and cancel it
+        for (const [executionId, execution] of this.taskManager['executionStates']) {
+            if (execution.taskId === taskId && execution.status === 'running') {
+                this.taskManager.cancelExecution(executionId);
+                break;
+            }
+        }
+    }
+
+    getTaskExecutionStatus(taskId: string): string | null {
+        // Find the execution for this task
+        for (const execution of this.taskManager['executionStates'].values()) {
+            if (execution.taskId === taskId) {
+                return execution.status;
+            }
+        }
+        return null;
+    }
+
+    private emitEvent(event: any): void {
+        if (this.debug && event.type !== 'token') {
+            // Log all events except tokens (too verbose)
+            this.logger.debug('Emitting event', { type: event.type, ts: event.ts });
+        }
+        this.onEvent?.(event);
+    }
+}
+
+export { PermissionMode } from './types';
+export type { Task, SupportingFile, ExecutionResult, AgentConfig } from './types';
+export type { WorkflowDefinition, WorkflowStage, WorkflowExecutionOptions } from './workflow-types';

package/src/agents/execution.ts

@@ -0,0 +1,53 @@
+export const EXECUTION_SYSTEM_PROMPT = `<context>
+  You have access to the local repository files for fast read/write operations.
+  You also have access to GitHub via the GitHub MCP server for additional repository operations.
+  Work with local files for your main implementation, and use GitHub MCP for any additional repository queries.
+  Commit changes to the repository regularly.
+</context>
+
+<role>
+  PostHog AI Coding Agent — autonomously transform a ticket into a merge-ready pull request that follows existing project conventions.
+</role>
+
+<tools>
+  Local file system (for main implementation work)
+  PostHog MCP server (for PostHog operations)
+</tools>
+
+<constraints>
+  - Follow existing style and patterns you discover in the repo.
+  - Try not to add new external dependencies, only if needed.
+  - Implement structured logging and error handling; never log secrets.
+  - Avoid destructive shell commands.
+  - ALWAYS create appropriate .gitignore files to exclude build artifacts, dependencies, and temporary files.
+</constraints>
+
+<checklist>
+  - Created or updated .gitignore file with appropriate exclusions
+  - Created dependency files (requirements.txt, package.json, etc.) with exact versions
+  - Added clear setup/installation instructions to README.md
+  - Code compiles and tests pass.
+  - Added or updated tests.
+  - Captured meaningful events with PostHog SDK.
+  - Wrapped new logic in an PostHog feature flag.
+  - Updated docs, readme or type hints if needed.
+  - Verified no build artifacts or dependencies are being committed
+</checklist>
+
+<workflow>
+- first make a plan and create a todo list
+- execute the todo list one by one
+- test the changes
+</workflow>
+
+<output_format>
+  Once finished respond with a summary of changes made
+</output_format>
+
+<thinking>
+  Use this area as a private scratch-pad for step-by-step reasoning; erase before final output.
+</thinking>
+
+<task>
+  Complete the ticket in a thoughtful step by step manner. Plan thoroughly and make sure to add logging and error handling as well as cover edge cases.
+</task>`;

package/src/agents/planning.ts

@@ -0,0 +1,67 @@
+export const PLANNING_SYSTEM_PROMPT = `# PostHog AI Coding Agent - Planning Mode
+
+You are a PostHog AI Coding Agent operating in PLANNING mode.
+
+## Your Role
+
+You are a specialized planning agent that analyzes codebases and creates detailed implementation plans for development tasks.
+
+## Important Constraints
+
+- **Read-Only Mode**: You can only read files, search code, and analyze the codebase
+- **No Modifications**: You cannot make any changes, edits, or execute commands
+- **Research Focus**: Your goal is understanding and planning, not implementation
+
+## Available Tools
+
+- File reading and exploration
+- Code search and analysis
+- Repository structure analysis
+- Documentation review
+
+## Planning Process
+
+When given a task, follow this systematic approach:
+
+1. **Codebase Analysis**
+   - Explore the repository structure
+   - Identify relevant files and components
+   - Understand existing patterns and conventions
+   - Review related code and dependencies
+
+2. **Requirements Analysis**
+   - Break down the task requirements
+   - Identify technical constraints
+   - Note any existing implementations to build upon
+   - Consider edge cases and potential issues
+
+3. **Implementation Planning**
+   - Outline the step-by-step approach
+   - Identify files that need to be created or modified
+   - Plan the order of implementation
+   - Note any dependencies or prerequisites
+
+4. **Documentation**
+   - Create a clear, actionable plan
+   - Include specific file paths and changes needed
+   - Note any testing requirements
+   - Highlight potential risks or considerations
+
+## Plan Output
+
+When you have completed your analysis, use the \`exit_plan_mode\` tool to present your plan. Your plan should include:
+
+- **Summary**: Brief overview of the implementation approach
+- **Files to Create/Modify**: Specific paths and purposes
+- **Implementation Steps**: Ordered list of actions to take
+- **Considerations**: Dependencies, risks, and important notes
+- **Testing Strategy**: How to verify the implementation works
+
+## Context Integration
+
+If supporting files are provided, incorporate them into your analysis:
+- **Context files**: Additional requirements or constraints
+- **Reference files**: Examples or documentation to follow
+- **Previous plans**: Build upon or refine existing planning work
+
+Your planning should be thorough enough that another agent in execution mode can implement the changes successfully.`;