@posthog/agent 1.1.0 → 1.3.0

package/CLAUDE.md

@@ -114,16 +114,43 @@ const task = await agent.fetchTask("task_abc123");
 const result = await agent.runTask(task, ExecutionMode.PLAN_AND_BUILD);
 ```
 
-### Array App Integration
+### Progress Updates
 ```typescript
-// Fetch task from PostHog and run with selected mode
-const result = await agent.runTask(taskId, userSelectedMode, {
-    repositoryPath: selectedRepoPath,
-    permissionMode: PermissionMode.DEFAULT,
-    onEvent: (event) => updateUI(event)
-});
+const posthogClient = agent.getPostHogClient();
+const poller = setInterval(async () => {
+    const progress = await posthogClient?.getTaskProgress(taskId);
+    if (progress?.has_progress) {
+        updateUI(progress.status, progress.current_step, progress.completed_steps, progress.total_steps);
+    }
+}, 3000);
+
+try {
+    await agent.runWorkflow(taskId, workflowId, {
+        repositoryPath: selectedRepoPath,
+        permissionMode: PermissionMode.DEFAULT,
+        autoProgress: true,
+    });
+} finally {
+    clearInterval(poller);
+}
+```
+
+> The agent still emits transformed events via the `onEvent` callback, so UI layers can combine streaming updates with periodic polling if desired.
 
-// Plan is stored in .posthog/{taskId}/plan.md and committed to Git
+```typescript
+// Handle the hook provided when constructing the Agent
+import type { AgentEvent } from '@posthog/agent';
+
+private handleLiveEvent(event: AgentEvent) {
+    switch (event.type) {
+        case 'status':
+            this.updateUI(event.phase, event.stage);
+            break;
+        case 'error':
+            this.showError(event.message);
+            break;
+    }
+}
 ```
 
 ### Working with Task Files
@@ -212,10 +239,11 @@ await agent.writeTaskFile(task.id, "requirements.md",
     "context"
 );
 
-// 4. Execute with PLAN_AND_BUILD mode
-const result = await agent.runTask(task, ExecutionMode.PLAN_AND_BUILD, {
+// 4. Execute with PLAN_AND_BUILD mode and rely on PostHog polling for progress
+const result = await agent.runWorkflow(task.id, workflowId, {
+    repositoryPath: "/path/to/repo",
     permissionMode: PermissionMode.DEFAULT,
-    onEvent: (event) => console.log(event)
+    autoProgress: true,
 });
 
 // 5. Review results
@@ -227,31 +255,36 @@ console.log("Plan location:", `.posthog/${task.id}/plan.md`);
 ### Array App Integration Pattern
 
 ```typescript
-// How Array app uses the SDK
 class ArrayTaskExecution {
-    async executeTask(taskId: string, mode: ExecutionMode, repoPath: string) {
-        const result = await this.agent.runTask(taskId, mode, {
-            repositoryPath: repoPath,
-            permissionMode: PermissionMode.DEFAULT,
-            onEvent: (event) => this.updateUI(event)
-        });
-        
-        // Show branches created for user review
-        this.showBranchesForReview(taskId, mode);
-        return result;
+    async executeTask(taskId: string, workflowId: string, repoPath: string) {
+        const poller = setInterval(() => this.pollProgress(taskId), 3000);
+        try {
+            await this.agent.runWorkflow(taskId, workflowId, {
+                repositoryPath: repoPath,
+                permissionMode: PermissionMode.DEFAULT,
+                autoProgress: true,
+            });
+        } finally {
+            clearInterval(poller);
+        }
+
+        this.showBranchesForReview(taskId);
     }
-    
-    private updateUI(event: any) {
-        switch (event.type) {
-            case 'status':
-                this.updateProgressBar(event.data?.status);
-                break;
-            case 'file_write':
-                this.showFileChange(event.data);
-                break;
-            case 'done':
-                this.showCompletion();
-                break;
+
+    private async pollProgress(taskId: string) {
+        const client = this.agent.getPostHogClient();
+        if (!client) {
+            return;
+        }
+
+        const progress = await client.getTaskProgress(taskId);
+        if (progress.has_progress) {
+            this.updateProgressBar({
+                status: progress.status,
+                currentStep: progress.current_step,
+                completed: progress.completed_steps,
+                total: progress.total_steps,
+            });
         }
     }
 }
@@ -293,4 +326,4 @@ try {
 - **File I/O**: Efficient `.posthog/` folder management with minimal disk usage
 - **API Calls**: Cached PostHog task data to minimize network requests
 - **Event Streaming**: Real-time updates without blocking execution
-- **Template Processing**: Lazy-loaded templates with variable substitution
+- **Template Processing**: Lazy-loaded templates with variable substitution

package/README.md

@@ -15,17 +15,24 @@ bun run example
 - **PostHog Integration**: Fetches existing tasks from PostHog API
 - **Configurable Workflows**: Execute tasks via PostHog-defined or local workflows
 - **Branch Management**: Automatic branch creation for planning and implementation
-- **Event Streaming**: Real-time events for UI integration
+- **Progress Tracking**: Execution status stored in PostHog `TaskProgress` records for easy polling
 
 ## Usage
 
 ```typescript
 import { Agent, PermissionMode } from '@posthog/agent';
+import type { AgentEvent } from '@posthog/agent';
 
 const agent = new Agent({
     workingDirectory: "/path/to/repo",
     posthogApiUrl: "https://app.posthog.com",
-    posthogApiKey: process.env.POSTHOG_API_KEY
+    posthogApiKey: process.env.POSTHOG_API_KEY, // Used for both API and MCP
+    onEvent: (event) => {
+      // Streamed updates for responsive UIs
+      if (event.type !== 'token') {
+        handleLiveEvent(event);
+      }
+    },
 });
 
 // Run by workflow
@@ -38,6 +45,15 @@ await agent.runWorkflow(taskId, workflowId, {
 });
 ```
 
+For local MCP development:
+
+```typescript
+const agent = new Agent({
+  workingDirectory: "/path/to/repo",
+  posthogMcpUrl: 'http://localhost:8787/mcp',
+});
+```
+
 ## Workflow
 
 Each task execution creates Git branches:
@@ -78,22 +94,47 @@ your-repo/
 └── (your code)
 ```
 
-## Array App Integration
+## Progress Updates
+
+Progress for each task execution is persisted to PostHog's `TaskProgress` model, so UIs can poll for updates without relying on streaming hooks:
 
 ```typescript
-const result = await agent.runTask(taskId, userSelectedMode, {
-    repositoryPath: selectedRepo,
-    onEvent: (event) => {
-        // Update UI based on event type
-        switch (event.type) {
-            case 'status': updateProgress(event.data); break;
-            case 'file_write': showFileChange(event.data); break;
-            case 'done': showCompletion(); break;
-        }
-    }
+const agent = new Agent({
+  workingDirectory: repoPath,
+  posthogApiUrl: "https://app.posthog.com",
+  posthogApiKey: process.env.POSTHOG_KEY,
 });
+
+const poller = setInterval(async () => {
+  const progress = await agent.getPostHogClient()?.getTaskProgress(taskId);
+  if (progress?.has_progress) {
+    renderProgress(progress.status, progress.current_step, progress.completed_steps, progress.total_steps);
+  }
+}, 3000);
+
+try {
+  await agent.runWorkflow(taskId, workflowId, { repositoryPath: repoPath });
+} finally {
+  clearInterval(poller);
+}
+
+// Live stream still available through the onEvent hook
+function handleLiveEvent(event: AgentEvent) {
+  switch (event.type) {
+    case 'status':
+      // optimistic UI update
+      break;
+    case 'error':
+      notifyError(event.message);
+      break;
+    default:
+      break;
+  }
+}
 ```
 
+> Prefer streaming updates? Pass an `onEvent` handler when constructing the agent to keep receiving real-time events while progress is also written to PostHog.
+
 ## Requirements
 
 - Bun runtime
@@ -139,4 +180,4 @@ await agent.runWorkflow(taskId, workflowId, {
 });
 ```
 
-Precedence for query options: base defaults in the SDK < global `queryOverrides` < per-stage `stageOverrides[stageKey].queryOverrides`.
+Precedence for query options: base defaults in the SDK < global `queryOverrides` < per-stage `stageOverrides[stageKey].queryOverrides`.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { Agent, } from './src/agent.js';
 export { PermissionMode, } from './src/types.js';
-export type { Task, SupportingFile, ExecutionResult, AgentConfig } from './src/types.js';
+export type { Task, SupportingFile, ExecutionResult, AgentConfig, McpServerConfig } from './src/types.js';
 export type { WorkflowDefinition, WorkflowStage, WorkflowExecutionOptions, AgentDefinition } from './src/workflow-types.js';
 export { Logger, LogLevel, } from './src/utils/logger.js';
 export type { LoggerConfig } from './src/utils/logger.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,OAAO,EACH,KAAK,GACR,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACH,cAAc,GACjB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACR,IAAI,EACJ,cAAc,EACd,eAAe,EACf,WAAW,EACd,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,kBAAkB,EAClB,aAAa,EACb,wBAAwB,EACxB,eAAe,EAChB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACH,MAAM,EACN,QAAQ,GACX,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACR,YAAY,EACf,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,OAAO,EACH,KAAK,GACR,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACH,cAAc,GACjB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACR,IAAI,EACJ,cAAc,EACd,eAAe,EACf,WAAW,EACX,eAAe,EAClB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,kBAAkB,EAClB,aAAa,EACb,wBAAwB,EACxB,eAAe,EAChB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACH,MAAM,EACN,QAAQ,GACX,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACR,YAAY,EACf,MAAM,uBAAuB,CAAC"}

package/dist/src/agent.d.ts

@@ -1,5 +1,6 @@
 import type { Task, ExecutionResult, AgentConfig } from './types.js';
 import type { WorkflowDefinition, WorkflowStage, WorkflowExecutionOptions } from './workflow-types.js';
+import { PostHogAPIClient } from './posthog-api.js';
 export declare class Agent {
     private workingDirectory;
     private onEvent?;
@@ -13,6 +14,8 @@ export declare class Agent {
     private agentRegistry;
     private workflowRegistry;
     private stageExecutor;
+    private progressReporter;
+    private mcpServers?;
     debug: boolean;
     constructor(config?: AgentConfig);
     /**
@@ -31,6 +34,7 @@ export declare class Agent {
         queryOverrides?: Record<string, any>;
     }): Promise<ExecutionResult>;
     fetchTask(taskId: string): Promise<Task>;
+    getPostHogClient(): PostHogAPIClient | undefined;
     listTasks(filters?: {
         repository?: string;
         organization?: string;
@@ -48,7 +52,7 @@ export declare class Agent {
     createImplementationBranch(taskId: string, planningBranchName?: string): Promise<string>;
     commitImplementation(taskId: string, taskTitle: string, planSummary?: string): Promise<string>;
     createPullRequest(taskId: string, branchName: string, taskTitle: string, taskDescription: string): Promise<string>;
-    attachPullRequestToTask(taskId: string, prUrl: string): Promise<void>;
+    attachPullRequestToTask(taskId: string, prUrl: string, branchName?: string): Promise<void>;
     updateTaskBranch(taskId: string, branchName: string): Promise<void>;
     cancelTask(taskId: string): void;
     getTaskExecutionStatus(taskId: string): string | null;

package/dist/src/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/agent.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,eAAe,EAAc,WAAW,EAAE,MAAM,YAAY,CAAC;AACjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAEvG,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAcpD,qBAAa,KAAK;IACd,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,OAAO,CAAC,CAAuB;IACvC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,UAAU,CAAC,CAAmB;IACtC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,UAAU,CAAC,CAAsB;IAClC,KAAK,EAAE,OAAO,CAAC;gBAEV,MAAM,GAAE,WAAgB;IAqEpC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO;IAMnB,WAAW,CAAC,QAAQ,EAAE,IAAI,GAAG,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,IAAI,CAAC;QAAC,QAAQ,EAAE,kBAAkB,CAAA;KAAE,CAAC;IAwFvJ,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,IAAI,CAAC;IAuFrG,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMlD,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,OAAO,YAAY,EAAE,cAAc,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAO,GAAG,OAAO,CAAC,eAAe,CAAC;IA0BpL,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU9C,gBAAgB,IAAI,gBAAgB,GAAG,SAAS;IAI1C,SAAS,CAAC,OAAO,CAAC,EAAE;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,aAAa,CAAC,EAAE,MAAM,CAAC;KAC1B,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAQb,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,GAAG,SAAS,GAAG,WAAW,GAAG,QAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhJ,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAKtE,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAO5C,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKtD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAMhD,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IASrD,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAO9D,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,kBAAkB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOxF,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAO9F,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuBlH,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa1F,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAczE,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAUhC,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAUrD,OAAO,CAAC,SAAS;CAapB;AAED,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACrF,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/src/agent.js

@@ -10,6 +10,7 @@ import { AgentRegistry } from './agent-registry.js';
 import { WorkflowRegistry } from './workflow-registry.js';
 import { StageExecutor } from './stage-executor.js';
 import { PromptBuilder } from './prompt-builder.js';
+import { TaskProgressReporter } from './task-progress-reporter.js';
 export { PermissionMode } from './types.js';
 
 class Agent {
@@ -25,11 +26,34 @@ class Agent {
     agentRegistry;
     workflowRegistry;
     stageExecutor;
+    progressReporter;
+    mcpServers;
     debug;
     constructor(config = {}) {
         this.workingDirectory = config.workingDirectory || process.cwd();
         this.onEvent = config.onEvent;
         this.debug = config.debug || false;
+        // Build default PostHog MCP server configuration
+        const posthogMcpUrl = config.posthogMcpUrl
+            || process.env.POSTHOG_MCP_URL
+            || 'https://mcp.posthog.com/mcp';
+        // Add auth if API key provided
+        const headers = {};
+        if (config.posthogApiKey) {
+            headers['Authorization'] = `Bearer ${config.posthogApiKey}`;
+        }
+        const defaultMcpServers = {
+            posthog: {
+                type: 'http',
+                url: posthogMcpUrl,
+                ...(Object.keys(headers).length > 0 ? { headers } : {}),
+            }
+        };
+        // Merge default PostHog MCP with user-provided servers (user config takes precedence)
+        this.mcpServers = {
+            ...defaultMcpServers,
+            ...config.mcpServers
+        };
         this.logger = new Logger({ debug: this.debug, prefix: '[PostHog Agent]' });
         this.taskManager = new TaskManager();
         this.eventTransformer = new EventTransformer();
@@ -53,7 +77,10 @@ class Agent {
             generatePlanTemplate: (vars) => this.templateManager.generatePlan(vars),
             logger: this.logger.child('PromptBuilder')
         });
-        this.stageExecutor = new StageExecutor(this.agentRegistry, this.logger, promptBuilder);
+        this.stageExecutor = new StageExecutor(this.agentRegistry, this.logger, promptBuilder, undefined, // eventHandler set via setEventHandler below
+        this.mcpServers);
+        this.stageExecutor.setEventHandler((event) => this.emitEvent(event));
+        this.progressReporter = new TaskProgressReporter(this.posthogAPI, this.logger);
     }
     /**
      * Enable or disable debug logging
@@ -70,6 +97,7 @@ class Agent {
         if (!workflow) {
             throw new Error(`Workflow ${workflowId} not found`);
         }
+        const orderedStages = [...workflow.stages].sort((a, b) => a.position - b.position);
         // Ensure task is assigned to workflow and positioned at first stage
         if (this.posthogAPI) {
             try {
@@ -90,8 +118,12 @@ class Agent {
         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);
+        await this.progressReporter.start(task.id, {
+            workflowId,
+            workflowRunId: executionId,
+            totalSteps: orderedStages.length,
+        });
         try {
-            const orderedStages = [...workflow.stages].sort((a, b) => a.position - b.position);
             let startIndex = 0;
             const currentStageId = task.current_stage;
             // If task is already at the last stage, fail gracefully without progressing
@@ -99,7 +131,10 @@ class Agent {
                 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 }));
+                    const finalStageKey = orderedStages[currIdx]?.key;
+                    this.emitEvent(this.eventTransformer.createStatusEvent('no_next_stage', { stage: finalStageKey }));
+                    await this.progressReporter.noNextStage(finalStageKey);
+                    await this.progressReporter.complete();
                     this.taskManager.completeExecution(executionId, { task, workflow });
                     return { task, workflow };
                 }
@@ -122,7 +157,9 @@ class Agent {
             }
             for (let i = startIndex; i < orderedStages.length; i++) {
                 const stage = orderedStages[i];
+                await this.progressReporter.stageStarted(stage.key, i);
                 await this.executeStage(task, stage, options);
+                await this.progressReporter.stageCompleted(stage.key, i + 1);
                 if (options.autoProgress) {
                     const hasNext = i < orderedStages.length - 1;
                     if (hasNext) {
@@ -130,10 +167,12 @@ class Agent {
                     }
                 }
             }
+            await this.progressReporter.complete();
             this.taskManager.completeExecution(executionId, { task, workflow });
             return { task, workflow };
         }
         catch (error) {
+            await this.progressReporter.fail(error);
             this.taskManager.failExecution(executionId, error);
             throw error;
         }
@@ -153,17 +192,20 @@ class Agent {
             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 }));
+            await this.progressReporter.branchCreated(stage.key, 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 }));
+            await this.progressReporter.branchCreated(stage.key, 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' }));
+            await this.progressReporter.commitMade(stage.key, 'plan');
         }
         if (isManual) {
             const defaultOpenPR = true; // manual stages default to PR for review
@@ -177,12 +219,14 @@ class Agent {
                     await this.updateTaskBranch(task.id, implBranch);
                     branchName = implBranch;
                     this.emitEvent(this.eventTransformer.createStatusEvent('branch_created', { stage: stage.key, branch: implBranch }));
+                    await this.progressReporter.branchCreated(stage.key, 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);
+                    await this.attachPullRequestToTask(task.id, prUrl, branchName);
                     this.emitEvent(this.eventTransformer.createStatusEvent('pr_created', { stage: stage.key, prUrl }));
+                    await this.progressReporter.pullRequestCreated(stage.key, prUrl);
                 }
                 catch { }
             }
@@ -195,6 +239,7 @@ class Agent {
             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' }));
+            await this.progressReporter.commitMade(stage.key, 'implementation');
         }
         // PR creation on complete stage (or if explicitly requested), regardless of whether edits occurred
         {
@@ -205,8 +250,9 @@ class Agent {
                 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);
+                    await this.attachPullRequestToTask(task.id, prUrl, branchName);
                     this.emitEvent(this.eventTransformer.createStatusEvent('pr_created', { stage: stage.key, prUrl }));
+                    await this.progressReporter.pullRequestCreated(stage.key, prUrl);
                 }
                 catch { }
             }
@@ -221,10 +267,11 @@ class Agent {
     // Direct prompt execution - still supported for low-level usage
     async run(prompt, options = {}) {
         const baseOptions = {
-            model: "claude-4-5-sonnet",
+            model: "claude-sonnet-4-5-20250929",
             cwd: options.repositoryPath || this.workingDirectory,
             permissionMode: options.permissionMode || "default",
             settingSources: ["local"],
+            mcpServers: this.mcpServers,
         };
         const response = query({
             prompt,
@@ -232,7 +279,7 @@ class Agent {
         });
         const results = [];
         for await (const message of response) {
-            this.logger.debug('Received message in direct run', { type: message.type });
+            this.logger.debug('Received message in direct run', message);
             const transformedEvent = this.eventTransformer.transform(message);
             this.onEvent?.(transformedEvent);
             results.push(message);
@@ -249,6 +296,9 @@ class Agent {
         }
         return this.posthogAPI.fetchTask(taskId);
     }
+    getPostHogClient() {
+        return this.posthogAPI;
+    }
     async listTasks(filters) {
         if (!this.posthogAPI) {
             throw new Error('PostHog API not configured. Provide posthogApiUrl and posthogApiKey in constructor.');
@@ -320,14 +370,14 @@ Generated by PostHog Agent`;
         this.logger.info('Pull request created', { taskId, prUrl });
         return prUrl;
     }
-    async attachPullRequestToTask(taskId, prUrl) {
-        this.logger.info('Attaching PR to task', { taskId, prUrl });
+    async attachPullRequestToTask(taskId, prUrl, branchName) {
+        this.logger.info('Attaching PR to task', { taskId, prUrl, branchName });
         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 });
+        await this.posthogAPI.attachTaskPullRequest(taskId, prUrl, branchName);
         this.logger.debug('PR attached to task', { taskId, prUrl });
     }
     async updateTaskBranch(taskId, branchName) {
@@ -337,7 +387,7 @@ Generated by PostHog Agent`;
             this.logger.error('PostHog API not configured', error);
             throw error;
         }
-        await this.posthogAPI.updateTask(taskId, { github_branch: branchName });
+        await this.posthogAPI.setTaskBranch(taskId, branchName);
         this.logger.debug('Task branch updated', { taskId, branchName });
     }
     // Execution management
@@ -364,6 +414,10 @@ Generated by PostHog Agent`;
             // Log all events except tokens (too verbose)
             this.logger.debug('Emitting event', { type: event.type, ts: event.ts });
         }
+        const persistPromise = this.progressReporter.recordEvent(event);
+        if (persistPromise && typeof persistPromise.then === 'function') {
+            persistPromise.catch((error) => this.logger.debug('Failed to persist agent event', { message: error.message }));
+        }
         this.onEvent?.(event);
     }
 }