@posthog/agent 1.24.0 → 1.25.0

package/src/session-store.ts

@@ -0,0 +1,244 @@
+import type { PostHogAPIClient, TaskRunUpdate } from "./posthog-api.js";
+import type { StoredNotification, TaskRun } from "./types.js";
+import { Logger } from "./utils/logger.js";
+
+export interface SessionPersistenceConfig {
+  taskId: string;
+  runId: string;
+  logUrl: string;
+  sdkSessionId?: string;
+}
+
+export class SessionStore {
+  private posthogAPI?: PostHogAPIClient;
+  private pendingEntries: Map<string, StoredNotification[]> = new Map();
+  private flushTimeouts: Map<string, NodeJS.Timeout> = new Map();
+  private configs: Map<string, SessionPersistenceConfig> = new Map();
+  private logger: Logger;
+
+  constructor(posthogAPI?: PostHogAPIClient, logger?: Logger) {
+    this.posthogAPI = posthogAPI;
+    this.logger =
+      logger ?? new Logger({ debug: false, prefix: "[SessionStore]" });
+
+    // Flush all pending on process exit
+    const flushAllAndExit = async () => {
+      const flushPromises: Promise<void>[] = [];
+      for (const sessionId of this.configs.keys()) {
+        flushPromises.push(this.flush(sessionId));
+      }
+      await Promise.all(flushPromises);
+      process.exit(0);
+    };
+
+    process.on("beforeExit", () => {
+      flushAllAndExit().catch((e) => this.logger.error("Flush failed:", e));
+    });
+    process.on("SIGINT", () => {
+      flushAllAndExit().catch((e) => this.logger.error("Flush failed:", e));
+    });
+    process.on("SIGTERM", () => {
+      flushAllAndExit().catch((e) => this.logger.error("Flush failed:", e));
+    });
+  }
+
+  /** Register a session for persistence */
+  register(sessionId: string, config: SessionPersistenceConfig): void {
+    this.configs.set(sessionId, config);
+  }
+
+  /** Unregister and flush pending */
+  async unregister(sessionId: string): Promise<void> {
+    await this.flush(sessionId);
+    this.configs.delete(sessionId);
+  }
+
+  /** Check if a session is registered for persistence */
+  isRegistered(sessionId: string): boolean {
+    return this.configs.has(sessionId);
+  }
+
+  /**
+   * Append a raw JSON-RPC line for persistence.
+   * Parses and wraps as StoredNotification for the API.
+   */
+  appendRawLine(sessionId: string, line: string): void {
+    const config = this.configs.get(sessionId);
+    if (!config) {
+      return;
+    }
+
+    try {
+      const message = JSON.parse(line);
+      const entry: StoredNotification = {
+        type: "notification",
+        timestamp: new Date().toISOString(),
+        notification: message,
+      };
+
+      const pending = this.pendingEntries.get(sessionId) ?? [];
+      pending.push(entry);
+      this.pendingEntries.set(sessionId, pending);
+
+      this.scheduleFlush(sessionId);
+    } catch {
+      this.logger.warn("Failed to parse raw line for persistence", {
+        sessionId,
+        lineLength: line.length,
+      });
+    }
+  }
+
+  /** Load raw JSON-RPC messages from S3 */
+  async load(logUrl: string): Promise<unknown[]> {
+    const response = await fetch(logUrl);
+
+    if (!response.ok) {
+      return [];
+    }
+
+    const content = await response.text();
+    if (!content.trim()) return [];
+
+    return content
+      .trim()
+      .split("\n")
+      .map((line) => {
+        try {
+          return JSON.parse(line);
+        } catch {
+          return null;
+        }
+      })
+      .filter((entry): entry is unknown => entry !== null);
+  }
+
+  /** Force flush pending entries */
+  async flush(sessionId: string): Promise<void> {
+    const config = this.configs.get(sessionId);
+    const pending = this.pendingEntries.get(sessionId);
+
+    if (!config || !pending?.length) return;
+
+    this.pendingEntries.delete(sessionId);
+    const timeout = this.flushTimeouts.get(sessionId);
+    if (timeout) {
+      clearTimeout(timeout);
+      this.flushTimeouts.delete(sessionId);
+    }
+
+    if (!this.posthogAPI) {
+      this.logger.debug("No PostHog API configured, skipping flush");
+      return;
+    }
+
+    try {
+      await this.posthogAPI.appendTaskRunLog(
+        config.taskId,
+        config.runId,
+        pending,
+      );
+    } catch (error) {
+      this.logger.error("Failed to persist session logs:", error);
+    }
+  }
+
+  private scheduleFlush(sessionId: string): void {
+    const existing = this.flushTimeouts.get(sessionId);
+    if (existing) clearTimeout(existing);
+    const timeout = setTimeout(() => this.flush(sessionId), 500);
+    this.flushTimeouts.set(sessionId, timeout);
+  }
+
+  /** Get the persistence config for a session */
+  getConfig(sessionId: string): SessionPersistenceConfig | undefined {
+    return this.configs.get(sessionId);
+  }
+
+  /**
+   * Start a session for persistence.
+   * Loads the task run and updates status to "in_progress".
+   */
+  async start(
+    sessionId: string,
+    taskId: string,
+    runId: string,
+  ): Promise<TaskRun | undefined> {
+    if (!this.posthogAPI) {
+      this.logger.debug(
+        "No PostHog API configured, registering session without persistence",
+      );
+      this.register(sessionId, {
+        taskId,
+        runId,
+        logUrl: "",
+      });
+      return undefined;
+    }
+
+    const taskRun = await this.posthogAPI.getTaskRun(taskId, runId);
+
+    this.register(sessionId, {
+      taskId,
+      runId,
+      logUrl: taskRun.log_url,
+    });
+
+    await this.updateTaskRun(sessionId, { status: "in_progress" });
+
+    return taskRun;
+  }
+
+  /**
+   * Mark a session as completed.
+   */
+  async complete(sessionId: string): Promise<void> {
+    await this.flush(sessionId);
+    await this.updateTaskRun(sessionId, { status: "completed" });
+  }
+
+  /**
+   * Mark a session as failed.
+   */
+  async fail(sessionId: string, error: Error | string): Promise<void> {
+    await this.flush(sessionId);
+    const message = typeof error === "string" ? error : error.message;
+    await this.updateTaskRun(sessionId, {
+      status: "failed",
+      error_message: message,
+    });
+    this.logger.error("Session failed", { sessionId, error: message });
+  }
+
+  /**
+   * Update the task run associated with a session.
+   */
+  async updateTaskRun(
+    sessionId: string,
+    update: TaskRunUpdate,
+  ): Promise<TaskRun | undefined> {
+    const config = this.configs.get(sessionId);
+    if (!config) {
+      this.logger.error(
+        `Cannot update task run: session ${sessionId} not registered`,
+      );
+      return undefined;
+    }
+
+    if (!this.posthogAPI) {
+      this.logger.debug("No PostHog API configured, skipping task run update");
+      return undefined;
+    }
+
+    try {
+      return await this.posthogAPI.updateTaskRun(
+        config.taskId,
+        config.runId,
+        update,
+      );
+    } catch (error) {
+      this.logger.error("Failed to update task run:", error);
+      return undefined;
+    }
+  }
+}

package/src/task-manager.ts

@@ -4,7 +4,7 @@ export interface TaskExecutionState {
   taskId: string;
   status: "running" | "completed" | "failed" | "canceled" | "timeout";
   mode: "plan_only" | "plan_and_build" | "build_only";
-  result?: any;
+  result?: unknown;
   startedAt: number;
   completedAt?: number;
   abortController?: AbortController;
@@ -37,7 +37,7 @@ export class TaskManager {
     return executionState;
   }
 
-  async waitForCompletion(executionId: string): Promise<any> {
+  async waitForCompletion(executionId: string): Promise<unknown> {
     const execution = this.executionStates.get(executionId);
     if (!execution) {
       throw new Error(`Execution ${executionId} not found`);
@@ -76,7 +76,7 @@ export class TaskManager {
     });
   }
 
-  completeExecution(executionId: string, result: any): void {
+  completeExecution(executionId: string, result: unknown): void {
     const execution = this.executionStates.get(executionId);
     if (!execution) {
       throw new Error(`Execution ${executionId} not found`);

package/src/template-manager.ts

@@ -1,6 +1,9 @@
 import { existsSync, promises as fs } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { Logger } from "./utils/logger";
+
+const logger = new Logger({ prefix: "[TemplateManager]" });
 
 export interface TemplateVariables {
   task_id: string;
@@ -77,14 +80,11 @@ export class TemplateManager {
     const resolvedDir = candidateDirs.find((dir) => existsSync(dir));
 
     if (!resolvedDir) {
-      console.error("[TemplateManager] Could not find templates directory.");
-      console.error("[TemplateManager] Current file:", __filename);
-      console.error("[TemplateManager] Current dir:", __dirname);
-      console.error(
-        "[TemplateManager] Tried:",
-        candidateDirs
-          .map((d) => `\n  - ${d} (exists: ${existsSync(d)})`)
-          .join(""),
+      logger.error("Could not find templates directory.");
+      logger.error(`Current file: ${__filename}`);
+      logger.error(`Current dir: ${__dirname}`);
+      logger.error(
+        `Tried: ${candidateDirs.map((d) => `\n  - ${d} (exists: ${existsSync(d)})`).join("")}`,
       );
     }
 

package/src/todo-manager.ts

@@ -76,7 +76,7 @@ export class TodoManager {
     });
   }
 
-  parseTodoWriteInput(toolInput: any): TodoList {
+  parseTodoWriteInput(toolInput: Record<string, unknown>): TodoList {
     const items: TodoItem[] = [];
 
     if (toolInput.todos && Array.isArray(toolInput.todos)) {
@@ -137,10 +137,16 @@ export class TodoManager {
 
   // check for TodoWrite tool call and persist if found
   async checkAndPersistFromMessage(
-    message: any,
+    message: Record<string, unknown>,
     taskId: string,
   ): Promise<TodoList | null> {
-    if (message.type !== "assistant" || !message.message?.content) {
+    if (
+      message.type !== "assistant" ||
+      typeof message.message !== "object" ||
+      !message.message ||
+      !("content" in message.message) ||
+      !Array.isArray(message.message.content)
+    ) {
       return null;
     }
 

package/src/types.ts

@@ -1,13 +1,39 @@
 // import and export to keep a single type file
+
+import type { SessionNotification } from "@agentclientprotocol/sdk";
 import type {
   CanUseTool,
   PermissionResult,
 } from "@anthropic-ai/claude-agent-sdk";
-export type { CanUseTool, PermissionResult };
+export type { CanUseTool, PermissionResult, SessionNotification };
+
+/**
+ * Stored custom notification following ACP extensibility model.
+ * Custom notifications use underscore-prefixed methods (e.g., `_posthog/phase_start`).
+ * See: https://agentclientprotocol.com/docs/extensibility
+ */
+export interface StoredNotification {
+  type: "notification";
+  /** When this notification was stored */
+  timestamp: string;
+  /** JSON-RPC 2.0 notification (no id field = notification, not request) */
+  notification: {
+    jsonrpc: "2.0";
+    method: string;
+    params?: Record<string, unknown>;
+  };
+}
+
+/**
+ * Type alias for stored log entries.
+ */
+export type StoredEntry = StoredNotification;
 
 // PostHog Task model (matches Array's OpenAPI schema)
 export interface Task {
   id: string;
+  task_number?: number;
+  slug?: string;
   title: string;
   description: string;
   origin_product:
@@ -16,28 +42,22 @@ export interface Task {
     | "user_created"
     | "support_queue"
     | "session_summaries";
-  position?: number;
   github_integration?: number | null;
-  repository_config?: unknown; // JSONField
-  repository_list: string;
-  primary_repository: string;
+  repository: string; // Format: "organization/repository" (e.g., "posthog/posthog-js")
+  json_schema?: Record<string, unknown> | null; // JSON schema for task output validation
   created_at: string;
   updated_at: string;
-
-  // DEPRECATED: These fields have been moved to TaskRun
-  // Use task.latest_run instead
-  current_stage?: string | null;
-  github_branch?: string | null;
-  github_pr_url?: string | null;
+  created_by?: {
+    id: number;
+    uuid: string;
+    distinct_id: string;
+    first_name: string;
+    email: string;
+  };
   latest_run?: TaskRun;
 }
 
 // Log entry structure for TaskRun.log
-export interface LogEntry {
-  type: string; // e.g., "info", "warning", "error", "success", "debug"
-  message: string;
-  [key: string]: unknown; // Allow additional fields
-}
 
 export type ArtifactType =
   | "plan"
@@ -55,14 +75,26 @@ export interface TaskRunArtifact {
   uploaded_at?: string;
 }
 
+export type TaskRunStatus =
+  | "not_started"
+  | "queued"
+  | "in_progress"
+  | "completed"
+  | "failed"
+  | "cancelled";
+
+export type TaskRunEnvironment = "local" | "cloud";
+
 // TaskRun model - represents individual execution runs of tasks
 export interface TaskRun {
   id: string;
   task: string; // Task ID
   team: number;
   branch: string | null;
-  status: "started" | "in_progress" | "completed" | "failed";
-  log_url?: string; // Presigned S3 URL for log access (valid for 1 hour)
+  stage: string | null; // Current stage (e.g., 'research', 'plan', 'build')
+  environment: TaskRunEnvironment;
+  status: TaskRunStatus;
+  log_url: string;
   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)
@@ -104,198 +136,15 @@ export interface TaskExecutionOptions {
   isCloudMode?: boolean; // Determines local vs cloud behavior (local pauses after each phase)
   createPR?: boolean; // Whether to create PR after build (defaults to false if local. This setting has no effect if isCloudMode is true.)
   autoProgress?: boolean;
-  queryOverrides?: Record<string, any>;
+  queryOverrides?: Record<string, unknown>;
   // Fine-grained permission control (only applied to build phase)
   // See: https://docs.claude.com/en/api/agent-sdk/permissions
   canUseTool?: CanUseTool;
+  skipGitBranch?: boolean; // Skip creating a task-specific git branch
 }
 
-// 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>;
-  parentToolUseId?: string | null; // For nested tool calls (subagents)
-  // Tool metadata (enriched by adapter for UI consumption)
-  tool?: import("./tools/types.js").Tool;
-  category?: import("./tools/types.js").ToolCategory;
-}
-
-export interface ToolResultEvent extends BaseEvent {
-  type: "tool_result";
-  toolName: string;
-  callId: string;
-  result: any;
-  isError?: boolean; // Whether the tool execution failed
-  parentToolUseId?: string | null; // For nested tool calls (subagents)
-  // Tool metadata (enriched by adapter for UI consumption)
-  tool?: import("./tools/types.js").Tool;
-  category?: import("./tools/types.js").ToolCategory;
-}
-
-// 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;
-  // Common optional fields (varies by phase):
-  kind?: string; // Kind of status (plan, implementation)
-  branch?: string; // Git branch name
-  prUrl?: string; // Pull request URL
-  taskId?: string; // Task identifier
-  messageId?: string; // Claude message ID
-  model?: string; // Model name
-  [key: string]: any; // Allow additional fields
-}
-
-export interface InitEvent extends BaseEvent {
-  type: "init";
-  model: string;
-  tools: string[];
-  permissionMode: string;
-  cwd: string;
-  apiKeySource: string;
-  agents?: string[];
-  slashCommands?: string[];
-  outputStyle?: string;
-  mcpServers?: Array<{ name: string; status: string }>;
-}
-
-export interface CompactBoundaryEvent extends BaseEvent {
-  type: "compact_boundary";
-  trigger: "manual" | "auto";
-  preTokens: number;
-}
-
-// Result events
-export interface DoneEvent extends BaseEvent {
-  type: "done";
-  result?: string; // Final summary text from Claude
-  durationMs?: number;
-  durationApiMs?: number; // API-only duration (excluding local processing)
-  numTurns?: number;
-  totalCostUsd?: number;
-  usage?: any;
-  modelUsage?: {
-    // Per-model usage breakdown
-    [modelName: string]: {
-      inputTokens: number;
-      outputTokens: number;
-      cacheReadInputTokens: number;
-      cacheCreationInputTokens: number;
-      webSearchRequests: number;
-      costUSD: number;
-      contextWindow: number;
-    };
-  };
-  permissionDenials?: Array<{
-    // Tools that were denied by permissions
-    tool_name: string;
-    tool_use_id: string;
-    tool_input: Record<string, unknown>;
-  }>;
-}
-
-export interface ErrorEvent extends BaseEvent {
-  type: "error";
-  message: string;
-  error?: any;
-  errorType?: string;
-  context?: Record<string, any>; // Partial error context for debugging
-  sdkError?: any; // Original SDK error object
-}
-
-// Metric and artifact events (general purpose, not tool-specific)
-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 interface RawSDKEvent extends BaseEvent {
-  type: "raw_sdk_event";
-  sdkMessage: any; // Full SDK message for debugging
-}
-
-export type AgentEvent =
-  | TokenEvent
-  | ContentBlockStartEvent
-  | ContentBlockStopEvent
-  | ToolCallEvent
-  | ToolResultEvent
-  | MessageStartEvent
-  | MessageDeltaEvent
-  | MessageStopEvent
-  | UserMessageEvent
-  | StatusEvent
-  | InitEvent
-  | CompactBoundaryEvent
-  | DoneEvent
-  | ErrorEvent
-  | MetricEvent
-  | ArtifactEvent
-  | RawSDKEvent;
-
 export interface ExecutionResult {
+  // biome-ignore lint/suspicious/noExplicitAny: Results array contains varying SDK response types
   results: any[];
 }
 
@@ -330,17 +179,26 @@ export type McpServerConfig =
   | {
       type: "sdk";
       name: string;
-      instance?: any; // McpServer instance
+      // biome-ignore lint/suspicious/noExplicitAny: McpServer instance type from external SDK
+      instance?: any;
     };
 
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export type OnLogCallback = (
+  level: LogLevel,
+  scope: string,
+  message: string,
+  data?: unknown,
+) => void;
+
 export interface AgentConfig {
   workingDirectory?: string;
-  onEvent?: (event: AgentEvent) => void;
 
-  // PostHog API configuration
-  posthogApiUrl: string;
-  posthogApiKey: string;
-  posthogProjectId: number;
+  // PostHog API configuration (optional - enables PostHog integration when provided)
+  posthogApiUrl?: string;
+  posthogApiKey?: string;
+  posthogProjectId?: number;
 
   // PostHog MCP configuration
   posthogMcpUrl?: string;
@@ -352,6 +210,7 @@ export interface AgentConfig {
 
   // Logging configuration
   debug?: boolean;
+  onLog?: OnLogCallback;
 
   // Fine-grained permission control for direct run() calls
   // See: https://docs.claude.com/en/api/agent-sdk/permissions
@@ -378,6 +237,7 @@ export interface PostHogResource {
   url: string;
   title?: string;
   content: string;
+  // biome-ignore lint/suspicious/noExplicitAny: Metadata contains varying resource-specific fields
   metadata?: Record<string, any>;
 }
 
@@ -410,3 +270,12 @@ export interface ResearchEvaluation {
   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;
+  worktreeName: string;
+  branchName: string;
+  baseBranch: string;
+  createdAt: string;
+}