@posthog/agent 1.19.0 → 1.21.0

package/src/todo-manager.ts

@@ -0,0 +1,169 @@
+import type { PostHogFileManager } from './file-manager.js';
+import { Logger } from './utils/logger.js';
+
+export interface TodoItem {
+  content: string;
+  status: 'pending' | 'in_progress' | 'completed';
+  activeForm: string;
+}
+
+export interface TodoList {
+  items: TodoItem[];
+  metadata: {
+    total: number;
+    pending: number;
+    in_progress: number;
+    completed: number;
+    last_updated: string;
+  };
+}
+
+export class TodoManager {
+  private fileManager: PostHogFileManager;
+  private logger: Logger;
+
+  constructor(fileManager: PostHogFileManager, logger?: Logger) {
+    this.fileManager = fileManager;
+    this.logger = logger || new Logger({ debug: false, prefix: '[TodoManager]' });
+  }
+
+  async readTodos(taskId: string): Promise<TodoList | null> {
+    try {
+      const content = await this.fileManager.readTaskFile(taskId, 'todos.json');
+      if (!content) {
+        return null;
+      }
+
+      const parsed = JSON.parse(content) as TodoList;
+      this.logger.debug('Loaded todos', {
+        taskId,
+        total: parsed.metadata.total,
+        pending: parsed.metadata.pending,
+        in_progress: parsed.metadata.in_progress,
+        completed: parsed.metadata.completed,
+      });
+
+      return parsed;
+    } catch (error) {
+      this.logger.debug('Failed to read todos.json', {
+        taskId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return null;
+    }
+  }
+
+  async writeTodos(taskId: string, todos: TodoList): Promise<void> {
+    this.logger.debug('Writing todos', {
+      taskId,
+      total: todos.metadata.total,
+      pending: todos.metadata.pending,
+      in_progress: todos.metadata.in_progress,
+      completed: todos.metadata.completed,
+    });
+
+    await this.fileManager.writeTaskFile(taskId, {
+      name: 'todos.json',
+      content: JSON.stringify(todos, null, 2),
+      type: 'artifact',
+    });
+
+    this.logger.info('Todos saved', {
+      taskId,
+      total: todos.metadata.total,
+      completed: todos.metadata.completed,
+    });
+  }
+
+  parseTodoWriteInput(toolInput: any): TodoList {
+    const items: TodoItem[] = [];
+
+    if (toolInput.todos && Array.isArray(toolInput.todos)) {
+      for (const todo of toolInput.todos) {
+        items.push({
+          content: todo.content || '',
+          status: todo.status || 'pending',
+          activeForm: todo.activeForm || todo.content || '',
+        });
+      }
+    }
+
+    const metadata = this.calculateMetadata(items);
+
+    return { items, metadata };
+  }
+
+  private calculateMetadata(items: TodoItem[]): TodoList['metadata'] {
+    const total = items.length;
+    const pending = items.filter((t) => t.status === 'pending').length;
+    const in_progress = items.filter((t) => t.status === 'in_progress').length;
+    const completed = items.filter((t) => t.status === 'completed').length;
+
+    return {
+      total,
+      pending,
+      in_progress,
+      completed,
+      last_updated: new Date().toISOString(),
+    };
+  }
+
+  async getTodoContext(taskId: string): Promise<string> {
+    const todos = await this.readTodos(taskId);
+    if (!todos || todos.items.length === 0) {
+      return '';
+    }
+
+    const lines: string[] = ['## Previous Todo List\n'];
+    lines.push('You previously created the following todo list:\n');
+
+    for (const item of todos.items) {
+      const statusIcon =
+        item.status === 'completed' ? '✓' : item.status === 'in_progress' ? '▶' : '○';
+      lines.push(`${statusIcon} [${item.status}] ${item.content}`);
+    }
+
+    lines.push(
+      `\nProgress: ${todos.metadata.completed}/${todos.metadata.total} completed\n`
+    );
+
+    return lines.join('\n');
+  }
+
+  // check for TodoWrite tool call and persist if found
+  async checkAndPersistFromMessage(
+    message: any,
+    taskId: string
+  ): Promise<TodoList | null> {
+    if (message.type !== 'assistant' || !message.message?.content) {
+      return null;
+    }
+
+    for (const block of message.message.content) {
+      if (block.type === 'tool_use' && block.name === 'TodoWrite') {
+        try {
+          this.logger.info('TodoWrite detected, persisting todos', { taskId });
+
+          const todoList = this.parseTodoWriteInput(block.input);
+          await this.writeTodos(taskId, todoList);
+
+          this.logger.info('Persisted todos successfully', {
+            taskId,
+            total: todoList.metadata.total,
+            completed: todoList.metadata.completed,
+          });
+
+          return todoList;
+        } catch (error) {
+          this.logger.error('Failed to persist todos', {
+            taskId,
+            error: error instanceof Error ? error.message : String(error),
+          });
+          return null;
+        }
+      }
+    }
+
+    return null;
+  }
+}

package/src/types.ts

@@ -32,6 +32,17 @@ export interface LogEntry {
   [key: string]: unknown; // Allow additional fields
 }
 
+export type ArtifactType = 'plan' | 'context' | 'reference' | 'output' | 'artifact';
+
+export interface TaskRunArtifact {
+  name: string;
+  type: ArtifactType;
+  size?: number;
+  content_type?: string;
+  storage_path?: string;
+  uploaded_at?: string;
+}
+
 // TaskRun model - represents individual execution runs of tasks
 export interface TaskRun {
   id: string;
@@ -43,6 +54,7 @@ export interface TaskRun {
   error_message: string | null;
   output: Record<string, unknown> | null; // Structured output (PR URL, commit SHA, etc.)
   state: Record<string, unknown>; // Intermediate run state (defaults to {}, never null)
+  artifacts?: TaskRunArtifact[];
   created_at: string;
   updated_at: string;
   completed_at: string | null;
@@ -51,10 +63,17 @@ export interface TaskRun {
 export interface SupportingFile {
   name: string;
   content: string;
-  type: 'plan' | 'context' | 'reference' | 'output';
+  type: ArtifactType;
   created_at: string;
 }
 
+export interface TaskArtifactUploadPayload {
+  name: string;
+  type: ArtifactType;
+  content: string;
+  content_type?: string;
+}
+
 export enum PermissionMode {
   PLAN = "plan",
   DEFAULT = "default",

package/src/workflow/config.ts

@@ -2,6 +2,7 @@ import type { WorkflowDefinition } from './types.js';
 import { researchStep } from './steps/research.js';
 import { planStep } from './steps/plan.js';
 import { buildStep } from './steps/build.js';
+import { finalizeStep } from './steps/finalize.js';
 
 const MODELS = {
     SONNET: "claude-sonnet-4-5",
@@ -39,4 +40,14 @@ export const TASK_WORKFLOW: WorkflowDefinition = [
         push: true,
         run: buildStep,
     },
+    {
+        id: 'finalize',
+        name: 'Finalize',
+        agent: 'system', // not used
+        model: MODELS.HAIKU, // not used
+        permissionMode: 'plan', // not used
+        commit: true,
+        push: true,
+        run: finalizeStep,
+    },
 ];

package/src/workflow/steps/build.ts

@@ -3,6 +3,7 @@ import { EXECUTION_SYSTEM_PROMPT } from '../../agents/execution.js';
 import { PermissionMode } from '../../types.js';
 import type { WorkflowStepRunner } from '../types.js';
 import { finalizeStepGitActions } from '../utils.js';
+import { TodoManager } from '../../todo-manager.js';
 
 export const buildStep: WorkflowStepRunner = async ({ step, context }) => {
     const {
@@ -82,11 +83,19 @@ export const buildStep: WorkflowStepRunner = async ({ step, context }) => {
     // Track commits made during Claude Code execution
     const commitTracker = await gitManager.trackCommitsDuring();
 
+    // Track todos from TodoWrite tool calls
+    const todoManager = new TodoManager(context.fileManager, stepLogger);
+
     for await (const message of response) {
         emitEvent(adapter.createRawSDKEvent(message));
-        const transformed = adapter.transform(message);
-        if (transformed) {
-            emitEvent(transformed);
+        const transformedEvents = adapter.transform(message);
+        for (const event of transformedEvents) {
+            emitEvent(event);
+        }
+
+        const todoList = await todoManager.checkAndPersistFromMessage(message, task.id);
+        if (todoList) {
+            emitEvent(adapter.createArtifactEvent('todos', todoList));
         }
     }
 

package/src/workflow/steps/finalize.ts

@@ -0,0 +1,207 @@
+import type { LocalArtifact } from '../../file-manager.js';
+import type { Task, TaskRunArtifact } from '../../types.js';
+import type { WorkflowStepRunner } from '../types.js';
+
+const MAX_SNIPPET_LENGTH = 1200;
+
+export const finalizeStep: WorkflowStepRunner = async ({ step, context }) => {
+    const {
+        task,
+        logger,
+        fileManager,
+        gitManager,
+        posthogAPI,
+        progressReporter,
+    } = context;
+
+    const stepLogger = logger.child('FinalizeStep');
+    const artifacts = await fileManager.collectTaskArtifacts(task.id);
+    let uploadedArtifacts: TaskRunArtifact[] | undefined;
+
+    if (artifacts.length && posthogAPI && progressReporter.runId) {
+        try {
+            const payload = artifacts.map((artifact) => ({
+                name: artifact.name,
+                type: artifact.type,
+                content: artifact.content,
+                content_type: artifact.contentType,
+            }));
+            uploadedArtifacts = await posthogAPI.uploadTaskArtifacts(task.id, progressReporter.runId, payload);
+            stepLogger.info('Uploaded task artifacts to PostHog', {
+                taskId: task.id,
+                uploadedCount: uploadedArtifacts.length,
+            });
+        } catch (error) {
+            stepLogger.warn('Failed to upload task artifacts', {
+                taskId: task.id,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    } else {
+        stepLogger.debug('Skipping artifact upload', {
+            hasArtifacts: artifacts.length > 0,
+            hasPostHogApi: Boolean(posthogAPI),
+            runId: progressReporter.runId,
+        });
+    }
+
+    const prBody = buildPullRequestBody(task, artifacts, uploadedArtifacts);
+    await fileManager.cleanupTaskDirectory(task.id);
+    await gitManager.addAllPostHogFiles();
+
+    context.stepResults[step.id] = {
+        prBody,
+        uploadedArtifacts,
+        artifactCount: artifacts.length,
+    };
+
+    return { status: 'completed' };
+};
+
+function buildPullRequestBody(task: Task, artifacts: LocalArtifact[], uploaded?: TaskRunArtifact[]): string {
+    const lines: string[] = [];
+    const taskSlug = (task as any).slug || task.id;
+
+    lines.push('## Task context');
+    lines.push(`- **Task**: ${taskSlug}`);
+    lines.push(`- **Title**: ${task.title}`);
+    lines.push(`- **Origin**: ${task.origin_product}`);
+
+    if (task.description) {
+        lines.push('');
+        lines.push('> ' + task.description.trim().split('\n').join('\n> '));
+    }
+
+    const usedFiles = new Set<string>();
+
+    const contextArtifact = artifacts.find((artifact) => artifact.name === 'context.md');
+    if (contextArtifact) {
+        lines.push('');
+        lines.push('### Task prompt');
+        lines.push(renderCodeFence(contextArtifact.content));
+        usedFiles.add(contextArtifact.name);
+    }
+
+    const researchArtifact = artifacts.find((artifact) => artifact.name === 'research.json');
+    if (researchArtifact) {
+        usedFiles.add(researchArtifact.name);
+        const researchSection = formatResearchSection(researchArtifact.content);
+        if (researchSection) {
+            lines.push('');
+            lines.push(researchSection);
+        }
+    }
+
+    const planArtifact = artifacts.find((artifact) => artifact.name === 'plan.md');
+    if (planArtifact) {
+        lines.push('');
+        lines.push('### Implementation plan');
+        lines.push(renderCodeFence(planArtifact.content));
+        usedFiles.add(planArtifact.name);
+    }
+
+    const todoArtifact = artifacts.find((artifact) => artifact.name === 'todos.json');
+    if (todoArtifact) {
+        const summary = summarizeTodos(todoArtifact.content);
+        if (summary) {
+            lines.push('');
+            lines.push('### Todo list');
+            lines.push(summary);
+        }
+        usedFiles.add(todoArtifact.name);
+    }
+
+    const remainingArtifacts = artifacts.filter((artifact) => !usedFiles.has(artifact.name));
+    if (remainingArtifacts.length) {
+        lines.push('');
+        lines.push('### Additional artifacts');
+        for (const artifact of remainingArtifacts) {
+            lines.push(`#### ${artifact.name}`);
+            lines.push(renderCodeFence(artifact.content));
+        }
+    }
+
+    const artifactList = uploaded ?? artifacts.map((artifact) => ({
+        name: artifact.name,
+        type: artifact.type,
+    }));
+
+    if (artifactList.length) {
+        lines.push('');
+        lines.push('### Uploaded artifacts');
+        for (const artifact of artifactList) {
+            const storage = 'storage_path' in artifact && artifact.storage_path ? ` – \`${artifact.storage_path}\`` : '';
+            lines.push(`- ${artifact.name} (${artifact.type})${storage}`);
+        }
+    }
+
+    return lines.join('\n\n');
+}
+
+function renderCodeFence(content: string): string {
+    const snippet = truncate(content, MAX_SNIPPET_LENGTH);
+    return ['```', snippet, '```'].join('\n');
+}
+
+function truncate(value: string, maxLength: number): string {
+    if (value.length <= maxLength) {
+        return value;
+    }
+    return `${value.slice(0, maxLength)}\n…`;
+}
+
+function formatResearchSection(content: string): string | null {
+    try {
+        const parsed = JSON.parse(content);
+        const sections: string[] = [];
+
+        if (parsed.context) {
+            sections.push('### Research summary');
+            sections.push(parsed.context);
+        }
+
+        if (parsed.questions && parsed.questions.length) {
+            sections.push('');
+            sections.push('### Questions needing answers');
+            for (const question of parsed.questions) {
+                sections.push(`- ${question.question ?? question}`);
+            }
+        }
+
+        if (parsed.answers && parsed.answers.length) {
+            sections.push('');
+            sections.push('### Answers provided');
+            for (const answer of parsed.answers) {
+                const questionId = answer.questionId ? ` (Q: ${answer.questionId})` : '';
+                sections.push(`- ${answer.selectedOption || answer.customInput || 'answer'}${questionId}`);
+            }
+        }
+
+        return sections.length ? sections.join('\n') : null;
+    } catch {
+        return null;
+    }
+}
+
+function summarizeTodos(content: string): string | null {
+    try {
+        const data = JSON.parse(content);
+        const total = data?.metadata?.total ?? data?.items?.length;
+        const completed = data?.metadata?.completed ?? data?.items?.filter((item: any) => item.status === 'completed').length;
+
+        const lines = [
+            `Progress: ${completed}/${total} completed`,
+        ];
+
+        if (data?.items?.length) {
+            for (const item of data.items) {
+                lines.push(`- [${item.status}] ${item.content}`);
+            }
+        }
+
+        return lines.join('\n');
+    } catch {
+        return null;
+    }
+}
+

package/src/workflow/steps/plan.ts

@@ -2,6 +2,7 @@ import { query } from '@anthropic-ai/claude-agent-sdk';
 import { PLANNING_SYSTEM_PROMPT } from '../../agents/planning.js';
 import type { WorkflowStepRunner } from '../types.js';
 import { finalizeStepGitActions } from '../utils.js';
+import { TodoManager } from '../../todo-manager.js';
 
 export const planStep: WorkflowStepRunner = async ({ step, context }) => {
     const {
@@ -96,17 +97,26 @@ export const planStep: WorkflowStepRunner = async ({ step, context }) => {
         options: { ...baseOptions, ...(options.queryOverrides || {}) },
     });
 
+    const todoManager = new TodoManager(fileManager, stepLogger);
+
     let planContent = '';
     for await (const message of response) {
         emitEvent(adapter.createRawSDKEvent(message));
-        const transformed = adapter.transform(message);
-        if (transformed) {
-            emitEvent(transformed);
+        const transformedEvents = adapter.transform(message);
+        for (const event of transformedEvents) {
+            emitEvent(event);
+        }
+
+        const todoList = await todoManager.checkAndPersistFromMessage(message, task.id);
+        if (todoList) {
+            emitEvent(adapter.createArtifactEvent('todos', todoList));
         }
+
+        // Extract text content for plan
         if (message.type === 'assistant' && message.message?.content) {
-            for (const c of message.message.content) {
-                if (c.type === 'text' && c.text) {
-                    planContent += `${c.text}\n`;
+            for (const block of message.message.content) {
+                if (block.type === 'text' && block.text) {
+                    planContent += `${block.text}\n`;
                 }
             }
         }

package/src/workflow/steps/research.ts

@@ -83,9 +83,9 @@ export const researchStep: WorkflowStepRunner = async ({ step, context }) => {
     let jsonContent = '';
     for await (const message of response) {
         emitEvent(adapter.createRawSDKEvent(message));
-        const transformed = adapter.transform(message);
-        if (transformed) {
-            emitEvent(transformed);
+        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) {