@posthog/agent 1.24.2 → 1.25.0

package/src/tools/types.ts

@@ -3,12 +3,12 @@
  * Makes it easier for UIs to filter and display tools by function.
  */
 export type ToolCategory =
-  | 'filesystem'  // File operations: Read, Write, Edit, Glob, NotebookEdit
-  | 'shell'       // Shell operations: Bash, BashOutput, KillShell
-  | 'web'         // Web operations: WebFetch, WebSearch
-  | 'assistant'   // Assistant operations: Task, TodoWrite, ExitPlanMode
-  | 'search'      // Search operations: Grep
-  | 'unknown';    // Unknown or unrecognized tools
+  | "filesystem" // File operations: Read, Write, Edit, Glob, NotebookEdit
+  | "shell" // Shell operations: Bash, BashOutput, KillShell
+  | "web" // Web operations: WebFetch, WebSearch
+  | "assistant" // Assistant operations: Task, TodoWrite, ExitPlanMode
+  | "search" // Search operations: Grep
+  | "unknown"; // Unknown or unrecognized tools
 
 /**
  * Base tool interface representing a tool that can be called by the agent.
@@ -23,86 +23,86 @@ export interface Tool {
 // Filesystem tools
 
 export interface ReadTool extends Tool {
-  name: 'Read';
-  category: 'filesystem';
+  name: "Read";
+  category: "filesystem";
 }
 
 export interface WriteTool extends Tool {
-  name: 'Write';
-  category: 'filesystem';
+  name: "Write";
+  category: "filesystem";
 }
 
 export interface EditTool extends Tool {
-  name: 'Edit';
-  category: 'filesystem';
+  name: "Edit";
+  category: "filesystem";
 }
 
 export interface GlobTool extends Tool {
-  name: 'Glob';
-  category: 'filesystem';
+  name: "Glob";
+  category: "filesystem";
 }
 
 export interface NotebookEditTool extends Tool {
-  name: 'NotebookEdit';
-  category: 'filesystem';
+  name: "NotebookEdit";
+  category: "filesystem";
 }
 
 // Shell tools
 
 export interface BashTool extends Tool {
-  name: 'Bash';
-  category: 'shell';
+  name: "Bash";
+  category: "shell";
 }
 
 export interface BashOutputTool extends Tool {
-  name: 'BashOutput';
-  category: 'shell';
+  name: "BashOutput";
+  category: "shell";
 }
 
 export interface KillShellTool extends Tool {
-  name: 'KillShell';
-  category: 'shell';
+  name: "KillShell";
+  category: "shell";
 }
 
 // Web tools
 
 export interface WebFetchTool extends Tool {
-  name: 'WebFetch';
-  category: 'web';
+  name: "WebFetch";
+  category: "web";
 }
 
 export interface WebSearchTool extends Tool {
-  name: 'WebSearch';
-  category: 'web';
+  name: "WebSearch";
+  category: "web";
 }
 
 // Search tools
 
 export interface GrepTool extends Tool {
-  name: 'Grep';
-  category: 'search';
+  name: "Grep";
+  category: "search";
 }
 
 // Assistant tools
 
 export interface TaskTool extends Tool {
-  name: 'Task';
-  category: 'assistant';
+  name: "Task";
+  category: "assistant";
 }
 
 export interface TodoWriteTool extends Tool {
-  name: 'TodoWrite';
-  category: 'assistant';
+  name: "TodoWrite";
+  category: "assistant";
 }
 
 export interface ExitPlanModeTool extends Tool {
-  name: 'ExitPlanMode';
-  category: 'assistant';
+  name: "ExitPlanMode";
+  category: "assistant";
 }
 
 export interface SlashCommandTool extends Tool {
-  name: 'SlashCommand';
-  category: 'assistant';
+  name: "SlashCommand";
+  category: "assistant";
 }
 
 /**

package/src/types.ts

@@ -1,38 +1,70 @@
-
 // import and export to keep a single type file
-import type { CanUseTool, PermissionResult } from '@anthropic-ai/claude-agent-sdk';
-export type { CanUseTool, PermissionResult };
+
+import type { SessionNotification } from "@agentclientprotocol/sdk";
+import type {
+  CanUseTool,
+  PermissionResult,
+} from "@anthropic-ai/claude-agent-sdk";
+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: 'error_tracking' | 'eval_clusters' | 'user_created' | 'support_queue' | 'session_summaries';
-  position?: number;
+  origin_product:
+    | "error_tracking"
+    | "eval_clusters"
+    | "user_created"
+    | "support_queue"
+    | "session_summaries";
   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' | 'context' | 'reference' | 'output' | 'artifact';
+export type ArtifactType =
+  | "plan"
+  | "context"
+  | "reference"
+  | "output"
+  | "artifact";
 
 export interface TaskRunArtifact {
   name: string;
@@ -43,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)
@@ -78,7 +122,7 @@ export enum PermissionMode {
   PLAN = "plan",
   DEFAULT = "default",
   ACCEPT_EDITS = "acceptEdits",
-  BYPASS = "bypassPermissions"
+  BYPASS = "bypassPermissions",
 }
 
 export interface ExecutionOptions {
@@ -92,196 +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[];
 }
 
@@ -296,38 +159,50 @@ export interface TaskExecutionResult {
 }
 
 // MCP Server configuration types (re-exported from Claude SDK for convenience)
-export type McpServerConfig = {
-  type?: 'stdio';
-  command: string;
-  args?: string[];
-  env?: Record<string, string>;
-} | {
-  type: 'sse';
-  url: string;
-  headers?: Record<string, string>;
-} | {
-  type: 'http';
-  url: string;
-  headers?: Record<string, string>;
-} | {
-  type: 'sdk';
-  name: string;
-  instance?: any; // McpServer instance
-};
+export type McpServerConfig =
+  | {
+      type?: "stdio";
+      command: string;
+      args?: string[];
+      env?: Record<string, string>;
+    }
+  | {
+      type: "sse";
+      url: string;
+      headers?: Record<string, string>;
+    }
+  | {
+      type: "http";
+      url: string;
+      headers?: Record<string, string>;
+    }
+  | {
+      type: "sdk";
+      name: string;
+      // 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;
 
-
   // MCP Server configuration
   // Additional MCP servers (PostHog MCP is always included by default)
   // You can override the PostHog MCP config by providing mcpServers.posthog
@@ -335,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
@@ -348,7 +224,12 @@ export interface PostHogAPIConfig {
 }
 
 // URL mention types
-export type ResourceType = 'error' | 'experiment' | 'insight' | 'feature_flag' | 'generic';
+export type ResourceType =
+  | "error"
+  | "experiment"
+  | "insight"
+  | "feature_flag"
+  | "generic";
 
 export interface PostHogResource {
   type: ResourceType;
@@ -356,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>;
 }
 
@@ -380,11 +262,20 @@ export interface ResearchAnswer {
 }
 
 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
+  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
-}
+  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;
+}