@posthog/agent 1.30.0 → 2.0.0

package/src/agent.ts

@@ -9,14 +9,12 @@ import { POSTHOG_NOTIFICATIONS } from "./acp-extensions.js";
 import {
   createAcpConnection,
   type InProcessAcpConnection,
-} from "./adapters/claude/claude.js";
+} from "./adapters/connection.js";
 import { PostHogFileManager } from "./file-manager.js";
 import { GitManager } from "./git-manager.js";
 import { PostHogAPIClient } from "./posthog-api.js";
-import { PromptBuilder } from "./prompt-builder.js";
 import { SessionStore } from "./session-store.js";
 import { TaskManager } from "./task-manager.js";
-import { TemplateManager } from "./template-manager.js";
 import type {
   AgentConfig,
   CanUseTool,
@@ -25,8 +23,14 @@ import type {
   TaskExecutionOptions,
 } from "./types.js";
 import { Logger } from "./utils/logger.js";
-import { TASK_WORKFLOW } from "./workflow/config.js";
-import type { SendNotification, WorkflowRuntime } from "./workflow/types.js";
+
+/**
+ * Type for sending ACP notifications
+ */
+type SendNotification = (
+  method: string,
+  params: Record<string, unknown>,
+) => Promise<void>;
 
 export class Agent {
   private workingDirectory: string;
@@ -34,10 +38,8 @@ export class Agent {
   private posthogAPI?: PostHogAPIClient;
   private fileManager: PostHogFileManager;
   private gitManager: GitManager;
-  private templateManager: TemplateManager;
   private logger: Logger;
   private acpConnection?: InProcessAcpConnection;
-  private promptBuilder: PromptBuilder;
   private mcpServers?: Record<string, any>;
   private canUseTool?: CanUseTool;
   private currentRunId?: string;
@@ -89,7 +91,6 @@ export class Agent {
       repositoryPath: this.workingDirectory,
       logger: this.logger.child("GitManager"),
     });
-    this.templateManager = new TemplateManager();
 
     if (
       config.posthogApiUrl &&
@@ -108,13 +109,6 @@ export class Agent {
         this.logger.child("SessionStore"),
       );
     }
-
-    this.promptBuilder = new PromptBuilder({
-      getTaskFiles: (taskId: string) => this.getTaskFiles(taskId),
-      generatePlanTemplate: (vars) => this.templateManager.generatePlan(vars),
-      posthogClient: this.posthogAPI,
-      logger: this.logger.child("PromptBuilder"),
-    });
   }
 
   /**
@@ -146,107 +140,18 @@ export class Agent {
     }
   }
 
-  private getOrCreateConnection(): InProcessAcpConnection {
-    if (!this.acpConnection) {
-      this.acpConnection = createAcpConnection({
-        sessionStore: this.sessionStore,
-      });
-    }
-    return this.acpConnection;
-  }
-
-  // Adaptive task execution orchestrated via workflow steps
+  /**
+   * @deprecated Use runTaskV2() for local execution or runTaskCloud() for cloud execution.
+   * This method used the old workflow system which has been removed.
+   */
   async runTask(
-    taskId: string,
-    taskRunId: string,
-    options: import("./types.js").TaskExecutionOptions = {},
+    _taskId: string,
+    _taskRunId: string,
+    _options: import("./types.js").TaskExecutionOptions = {},
   ): Promise<void> {
-    // await this._configureLlmGateway();
-
-    const task = await this.fetchTask(taskId);
-    const cwd = options.repositoryPath || this.workingDirectory;
-    const isCloudMode = options.isCloudMode ?? false;
-    const taskSlug = (task as any).slug || task.id;
-
-    // Use taskRunId as sessionId - they are the same identifier
-    this.currentRunId = taskRunId;
-
-    this.logger.info("Starting adaptive task execution", {
-      taskId: task.id,
-      taskSlug,
-      taskRunId,
-      isCloudMode,
-    });
-
-    const connection = this.getOrCreateConnection();
-
-    // Create sendNotification using ACP connection's extNotification
-    const sendNotification: SendNotification = async (method, params) => {
-      this.logger.debug(`Notification: ${method}`, params);
-      await connection.agentConnection.extNotification?.(method, params);
-    };
-
-    await sendNotification(POSTHOG_NOTIFICATIONS.RUN_STARTED, {
-      sessionId: taskRunId,
-      runId: taskRunId,
-    });
-
-    await this.prepareTaskBranch(taskSlug, isCloudMode, sendNotification);
-
-    let taskError: Error | undefined;
-    try {
-      const workflowContext: WorkflowRuntime = {
-        task,
-        taskSlug,
-        runId: taskRunId,
-        cwd,
-        isCloudMode,
-        options,
-        logger: this.logger,
-        fileManager: this.fileManager,
-        gitManager: this.gitManager,
-        promptBuilder: this.promptBuilder,
-        connection: connection.agentConnection,
-        sessionId: taskRunId,
-        sendNotification,
-        mcpServers: this.mcpServers,
-        posthogAPI: this.posthogAPI,
-        stepResults: {},
-      };
-
-      for (const step of TASK_WORKFLOW) {
-        const result = await step.run({ step, context: workflowContext });
-        if (result.halt) {
-          return;
-        }
-      }
-
-      const shouldCreatePR = options.createPR ?? isCloudMode;
-      if (shouldCreatePR) {
-        await this.ensurePullRequest(
-          task,
-          workflowContext.stepResults,
-          sendNotification,
-        );
-      }
-
-      this.logger.info("Task execution complete", { taskId: task.id });
-      await sendNotification(POSTHOG_NOTIFICATIONS.TASK_COMPLETE, {
-        sessionId: taskRunId,
-        taskId: task.id,
-      });
-    } catch (error) {
-      taskError = error instanceof Error ? error : new Error(String(error));
-      this.logger.error("Task execution failed", {
-        taskId: task.id,
-        error: taskError.message,
-      });
-      await sendNotification(POSTHOG_NOTIFICATIONS.ERROR, {
-        sessionId: taskRunId,
-        message: taskError.message,
-      });
-      throw taskError;
-    }
+    throw new Error(
+      "runTask() is deprecated. Use runTaskV2() for local execution or runTaskCloud() for cloud execution.",
+    );
   }
 
   /**
@@ -263,8 +168,6 @@ export class Agent {
   ): Promise<InProcessAcpConnection> {
     await this._configureLlmGateway();
 
-    const task = await this.fetchTask(taskId);
-    const taskSlug = (task as any).slug || task.id;
     const isCloudMode = options.isCloudMode ?? false;
     const _cwd = options.repositoryPath || this.workingDirectory;
 
@@ -272,9 +175,10 @@ export class Agent {
     this.currentRunId = taskRunId;
 
     this.acpConnection = createAcpConnection({
+      framework: options.framework,
       sessionStore: this.sessionStore,
       sessionId: taskRunId,
-      taskId: task.id,
+      taskId,
     });
 
     const sendNotification: SendNotification = async (method, params) => {
@@ -285,12 +189,17 @@ export class Agent {
       );
     };
 
-    await sendNotification(POSTHOG_NOTIFICATIONS.RUN_STARTED, {
-      sessionId: taskRunId,
-      runId: taskRunId,
-    });
+    if (!options.isReconnect) {
+      await sendNotification(POSTHOG_NOTIFICATIONS.RUN_STARTED, {
+        sessionId: taskRunId,
+        runId: taskRunId,
+      });
+    }
 
+    // Only fetch task when we need the slug for git branch creation
     if (!options.skipGitBranch) {
+      const task = options.task ?? (await this.fetchTask(taskId));
+      const taskSlug = (task as any).slug || task.id;
       try {
         await this.prepareTaskBranch(taskSlug, isCloudMode, sendNotification);
       } catch (error) {
@@ -753,61 +662,6 @@ This PR implements the changes described in the task.`;
       throw error;
     }
   }
-
-  private async ensurePullRequest(
-    task: Task,
-    stepResults: Record<string, any>,
-    sendNotification: SendNotification,
-  ): Promise<void> {
-    const latestRun = task.latest_run;
-    const existingPr =
-      latestRun?.output && typeof latestRun.output === "object"
-        ? (latestRun.output as any).pr_url
-        : null;
-
-    if (existingPr) {
-      this.logger.info("PR already exists, skipping creation", {
-        taskId: task.id,
-        prUrl: existingPr,
-      });
-      return;
-    }
-
-    const buildResult = stepResults.build;
-    if (!buildResult?.commitCreated) {
-      this.logger.warn(
-        "Build step did not produce a commit; skipping PR creation",
-        { taskId: task.id },
-      );
-      return;
-    }
-
-    const branchName = await this.gitManager.getCurrentBranch();
-    const finalizeResult = stepResults.finalize;
-    const prBody = finalizeResult?.prBody;
-
-    const prUrl = await this.createPullRequest(
-      task.id,
-      branchName,
-      task.title,
-      task.description ?? "",
-      prBody,
-    );
-
-    await sendNotification(POSTHOG_NOTIFICATIONS.PR_CREATED, { prUrl });
-
-    try {
-      await this.attachPullRequestToTask(task.id, prUrl, branchName);
-      this.logger.info("PR attached to task successfully", {
-        taskId: task.id,
-        prUrl,
-      });
-    } catch (error) {
-      this.logger.warn("Could not attach PR to task", {
-        error: error instanceof Error ? error.message : String(error),
-      });
-    }
-  }
 }
 
 export type {

package/src/file-manager.ts

@@ -1,7 +1,7 @@
 import { promises as fs } from "node:fs";
 import { extname, join } from "node:path";
 import z from "zod";
-import type { ResearchEvaluation, SupportingFile } from "./types.js";
+import type { SupportingFile } from "./types.js";
 import { Logger } from "./utils/logger.js";
 
 export interface TaskFile {
@@ -162,39 +162,6 @@ export class PostHogFileManager {
     return await this.readTaskFile(taskId, "requirements.md");
   }
 
-  async writeResearch(taskId: string, data: ResearchEvaluation): Promise<void> {
-    this.logger.debug("Writing research", {
-      taskId,
-      score: data.actionabilityScore,
-      hasQuestions: !!data.questions,
-      questionCount: data.questions?.length ?? 0,
-      answered: data.answered ?? false,
-    });
-
-    await this.writeTaskFile(taskId, {
-      name: "research.json",
-      content: JSON.stringify(data, null, 2),
-      type: "artifact",
-    });
-
-    this.logger.info("Research file written", {
-      taskId,
-      score: data.actionabilityScore,
-      hasQuestions: !!data.questions,
-      answered: data.answered ?? false,
-    });
-  }
-
-  async readResearch(taskId: string): Promise<ResearchEvaluation | null> {
-    try {
-      const content = await this.readTaskFile(taskId, "research.json");
-      return content ? (JSON.parse(content) as ResearchEvaluation) : null;
-    } catch (error) {
-      this.logger.debug("Failed to parse research.json", { error });
-      return null;
-    }
-  }
-
   async writeTodos(taskId: string, data: unknown): Promise<void> {
     const todos = z.object({
       metadata: z.object({

package/src/tools/registry.ts

@@ -84,6 +84,11 @@ const TOOL_DEFINITIONS: Record<string, Tool> = {
     category: "assistant",
     description: "Exit plan mode and present plan to user",
   },
+  AskUserQuestion: {
+    name: "AskUserQuestion",
+    category: "assistant",
+    description: "Ask the user a clarifying question with options",
+  },
   SlashCommand: {
     name: "SlashCommand",
     category: "assistant",

package/src/tools/types.ts

@@ -100,6 +100,11 @@ export interface ExitPlanModeTool extends Tool {
   category: "assistant";
 }
 
+export interface AskUserQuestionTool extends Tool {
+  name: "AskUserQuestion";
+  category: "assistant";
+}
+
 export interface SlashCommandTool extends Tool {
   name: "SlashCommand";
   category: "assistant";
@@ -124,4 +129,5 @@ export type KnownTool =
   | TaskTool
   | TodoWriteTool
   | ExitPlanModeTool
+  | AskUserQuestionTool
   | SlashCommandTool;

package/src/types.ts

@@ -141,6 +141,9 @@ export interface TaskExecutionOptions {
   // See: https://docs.claude.com/en/api/agent-sdk/permissions
   canUseTool?: CanUseTool;
   skipGitBranch?: boolean; // Skip creating a task-specific git branch
+  framework?: "claude"; // Agent framework to use (defaults to "claude")
+  task?: Task; // Pre-fetched task to avoid redundant API call
+  isReconnect?: boolean; // Session recreation - skip RUN_STARTED notification
 }
 
 export interface ExecutionResult {
@@ -248,29 +251,6 @@ export interface UrlMention {
   label?: string;
 }
 
-// Research evaluation types
-export interface ResearchQuestion {
-  id: string;
-  question: string;
-  options: string[];
-}
-
-export interface ResearchAnswer {
-  questionId: string;
-  selectedOption: string;
-  customInput?: string;
-}
-
-export interface ResearchEvaluation {
-  actionabilityScore: number; // 0-1 confidence score
-  context: string; // brief summary for planning
-  keyFiles: string[]; // files needing modification
-  blockers?: string[]; // what's preventing full confidence
-  questions?: ResearchQuestion[]; // only if score < 0.7
-  answered?: boolean; // whether questions have been answered
-  answers?: ResearchAnswer[]; // user's answers to questions
-}
-
 // Worktree types for parallel task development
 export interface WorktreeInfo {
   worktreePath: string;

package/src/worktree-manager.ts

@@ -1,4 +1,4 @@
-import { exec, execFile } from "node:child_process";
+import { execFile } from "node:child_process";
 import * as crypto from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
@@ -6,7 +6,6 @@ import { promisify } from "node:util";
 import type { WorktreeInfo } from "./types.js";
 import { Logger } from "./utils/logger.js";
 
-const execAsync = promisify(exec);
 const execFileAsync = promisify(execFile);
 
 export interface WorktreeConfig {
@@ -512,14 +511,14 @@ export class WorktreeManager {
     return this.worktreeBasePath !== null;
   }
 
-  private async runGitCommand(command: string): Promise<string> {
+  private async runGitCommand(args: string[]): Promise<string> {
     try {
-      const { stdout } = await execAsync(`git ${command}`, {
+      const { stdout } = await execFileAsync("git", args, {
         cwd: this.mainRepoPath,
       });
       return stdout.trim();
     } catch (error) {
-      throw new Error(`Git command failed: ${command}\n${error}`);
+      throw new Error(`Git command failed: git ${args.join(" ")}\n${error}`);
     }
   }
 
@@ -605,48 +604,68 @@ export class WorktreeManager {
   }
 
   private async getDefaultBranch(): Promise<string> {
-    try {
-      const remoteBranch = await this.runGitCommand(
-        "symbolic-ref refs/remotes/origin/HEAD",
-      );
-      return remoteBranch.replace("refs/remotes/origin/", "");
-    } catch {
-      // Fallback: check if main exists, otherwise use master
-      try {
-        await this.runGitCommand("rev-parse --verify main");
-        return "main";
-      } catch {
-        try {
-          await this.runGitCommand("rev-parse --verify master");
-          return "master";
-        } catch {
-          throw new Error(
-            "Cannot determine default branch. No main or master branch found.",
-          );
-        }
-      }
+    // Try all methods in parallel for speed
+    const [symbolicRef, mainExists, masterExists] = await Promise.allSettled([
+      this.runGitCommand(["symbolic-ref", "refs/remotes/origin/HEAD"]),
+      this.runGitCommand(["rev-parse", "--verify", "main"]),
+      this.runGitCommand(["rev-parse", "--verify", "master"]),
+    ]);
+
+    // Prefer symbolic ref (most accurate)
+    if (symbolicRef.status === "fulfilled") {
+      return symbolicRef.value.replace("refs/remotes/origin/", "");
     }
+
+    // Fallback to main if it exists
+    if (mainExists.status === "fulfilled") {
+      return "main";
+    }
+
+    // Fallback to master if it exists
+    if (masterExists.status === "fulfilled") {
+      return "master";
+    }
+
+    throw new Error(
+      "Cannot determine default branch. No main or master branch found.",
+    );
   }
 
   async createWorktree(options?: {
     baseBranch?: string;
   }): Promise<WorktreeInfo> {
+    const totalStart = Date.now();
+
+    // Run setup tasks in parallel for speed
+    const setupPromises: Promise<unknown>[] = [];
+
     // Only modify .git/info/exclude when using in-repo storage
     if (!this.usesExternalPath()) {
-      await this.ensureArrayDirIgnored();
-    }
-
-    // Ensure the worktree folder exists when using external path
-    if (this.usesExternalPath()) {
+      setupPromises.push(this.ensureArrayDirIgnored());
+    } else {
+      // Ensure the worktree folder exists when using external path
       const folderPath = this.getWorktreeFolderPath();
-      await fs.mkdir(folderPath, { recursive: true });
+      setupPromises.push(fs.mkdir(folderPath, { recursive: true }));
     }
 
-    // Generate unique worktree name
-    const worktreeName = await this.generateUniqueWorktreeName();
+    // Generate unique worktree name (in parallel with above)
+    const worktreeNamePromise = this.generateUniqueWorktreeName();
+    setupPromises.push(worktreeNamePromise);
+
+    // Get default branch in parallel if not provided
+    const baseBranchPromise = options?.baseBranch
+      ? Promise.resolve(options.baseBranch)
+      : this.getDefaultBranch();
+    setupPromises.push(baseBranchPromise);
+
+    // Wait for all setup to complete
+    await Promise.all(setupPromises);
+    const setupTime = Date.now() - totalStart;
+
+    const worktreeName = await worktreeNamePromise;
+    const baseBranch = await baseBranchPromise;
     const worktreePath = this.getWorktreePath(worktreeName);
     const branchName = `array/${worktreeName}`;
-    const baseBranch = options?.baseBranch ?? (await this.getDefaultBranch());
 
     this.logger.info("Creating worktree", {
       worktreeName,
@@ -654,21 +673,36 @@ export class WorktreeManager {
       branchName,
       baseBranch,
       external: this.usesExternalPath(),
+      setupTimeMs: setupTime,
     });
 
     // Create the worktree with a new branch
+    const gitStart = Date.now();
     if (this.usesExternalPath()) {
       // Use absolute path for external worktrees
-      await this.runGitCommand(
-        `worktree add -b "${branchName}" "${worktreePath}" "${baseBranch}"`,
-      );
+      await this.runGitCommand([
+        "worktree",
+        "add",
+        "--quiet",
+        "-b",
+        branchName,
+        worktreePath,
+        baseBranch,
+      ]);
     } else {
       // Use relative path from repo root for in-repo worktrees
-      const relativePath = `${WORKTREE_FOLDER_NAME}/${worktreeName}`;
-      await this.runGitCommand(
-        `worktree add -b "${branchName}" "./${relativePath}" "${baseBranch}"`,
-      );
+      const relativePath = `./${WORKTREE_FOLDER_NAME}/${worktreeName}`;
+      await this.runGitCommand([
+        "worktree",
+        "add",
+        "--quiet",
+        "-b",
+        branchName,
+        relativePath,
+        baseBranch,
+      ]);
     }
+    const gitTime = Date.now() - gitStart;
 
     const createdAt = new Date().toISOString();
 
@@ -676,6 +710,9 @@ export class WorktreeManager {
       worktreeName,
       worktreePath,
       branchName,
+      setupTimeMs: setupTime,
+      gitWorktreeAddMs: gitTime,
+      totalMs: Date.now() - totalStart,
     });
 
     return {
@@ -758,7 +795,7 @@ export class WorktreeManager {
       try {
         await fs.rm(worktreePath, { recursive: true, force: true });
         // Also prune the worktree list
-        await this.runGitCommand("worktree prune");
+        await this.runGitCommand(["worktree", "prune"]);
         this.logger.info("Worktree cleaned up manually", { worktreePath });
       } catch (cleanupError) {
         this.logger.error("Failed to cleanup worktree", {
@@ -773,7 +810,11 @@ export class WorktreeManager {
   async getWorktreeInfo(worktreePath: string): Promise<WorktreeInfo | null> {
     try {
       // Parse the worktree list to find info about this worktree
-      const output = await this.runGitCommand("worktree list --porcelain");
+      const output = await this.runGitCommand([
+        "worktree",
+        "list",
+        "--porcelain",
+      ]);
       const worktrees = this.parseWorktreeList(output);
 
       const worktree = worktrees.find((w) => w.worktreePath === worktreePath);
@@ -786,7 +827,11 @@ export class WorktreeManager {
 
   async listWorktrees(): Promise<WorktreeInfo[]> {
     try {
-      const output = await this.runGitCommand("worktree list --porcelain");
+      const output = await this.runGitCommand([
+        "worktree",
+        "list",
+        "--porcelain",
+      ]);
       return this.parseWorktreeList(output);
     } catch (error) {
       this.logger.debug("Failed to list worktrees", { error });
@@ -836,8 +881,9 @@ export class WorktreeManager {
 
   async isWorktree(repoPath: string): Promise<boolean> {
     try {
-      const { stdout } = await execAsync(
-        "git rev-parse --is-inside-work-tree",
+      const { stdout } = await execFileAsync(
+        "git",
+        ["rev-parse", "--is-inside-work-tree"],
         { cwd: repoPath },
       );
       if (stdout.trim() !== "true") {

package/dist/templates/plan-template.md

@@ -1,41 +0,0 @@
-# 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