@posthog/agent 1.25.0 → 1.27.0

package/dist/index.d.ts

@@ -1,20 +1,1274 @@
-export type { ArtifactNotificationPayload, BranchCreatedPayload, ConsoleNotificationPayload, ErrorNotificationPayload, PhaseNotificationPayload, PostHogNotificationPayload, PostHogNotificationType, PrCreatedPayload, RunStartedPayload, SdkSessionPayload, TaskCompletePayload, } from "./src/acp-extensions.js";
-export { POSTHOG_NOTIFICATIONS } from "./src/acp-extensions.js";
-export type { AcpConnectionConfig, InProcessAcpConnection, } from "./src/adapters/claude/claude.js";
-export { createAcpConnection } from "./src/adapters/claude/claude.js";
-export { Agent } from "./src/agent.js";
-export type { AgentEvent, ConsoleEvent, ErrorEvent, StatusEvent, TokenEvent, } from "./src/schemas.js";
-export { parseAgentEvent, parseAgentEvents } from "./src/schemas.js";
-export type { SessionPersistenceConfig } from "./src/session-store.js";
-export { SessionStore } from "./src/session-store.js";
-export type { TodoItem, TodoList } from "./src/todo-manager.js";
-export { TodoManager } from "./src/todo-manager.js";
-export { ToolRegistry } from "./src/tools/registry.js";
-export type { BashOutputTool, BashTool, EditTool, ExitPlanModeTool, GlobTool, GrepTool, KillShellTool, KnownTool, NotebookEditTool, ReadTool, SlashCommandTool, TaskTool, TodoWriteTool, Tool, ToolCategory, WebFetchTool, WebSearchTool, WriteTool, } from "./src/tools/types.js";
-export type { AgentConfig, ExecutionResult, LogLevel as LogLevelType, McpServerConfig, OnLogCallback, ResearchEvaluation, SessionNotification, StoredEntry, StoredNotification, SupportingFile, Task, TaskRun, WorktreeInfo, } from "./src/types.js";
-export { PermissionMode } from "./src/types.js";
-export type { LoggerConfig } from "./src/utils/logger.js";
-export { Logger, LogLevel } from "./src/utils/logger.js";
-export type { WorktreeConfig } from "./src/worktree-manager.js";
-export { WorktreeManager } from "./src/worktree-manager.js";
-//# sourceMappingURL=index.d.ts.map
+import { AgentSideConnection } from '@agentclientprotocol/sdk';
+export { SessionNotification } from '@agentclientprotocol/sdk';
+import { CanUseTool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+
+/**
+ * PostHog-specific ACP extensions.
+ *
+ * These follow the ACP extensibility model:
+ * - Custom notification methods are prefixed with `_posthog/`
+ * - Custom data can be attached via `_meta` fields
+ *
+ * See: https://agentclientprotocol.com/docs/extensibility
+ */
+/**
+ * Custom notification methods for PostHog-specific events.
+ * Used with AgentSideConnection.extNotification() or Client.extNotification()
+ */
+declare const POSTHOG_NOTIFICATIONS: {
+    /** Artifact produced during task execution (research, plan, etc.) */
+    readonly ARTIFACT: "_posthog/artifact";
+    /** Phase has started (research, plan, build, etc.) */
+    readonly PHASE_START: "_posthog/phase_start";
+    /** Phase has completed */
+    readonly PHASE_COMPLETE: "_posthog/phase_complete";
+    /** Git branch was created */
+    readonly BRANCH_CREATED: "_posthog/branch_created";
+    /** Pull request was created */
+    readonly PR_CREATED: "_posthog/pr_created";
+    /** Task run has started */
+    readonly RUN_STARTED: "_posthog/run_started";
+    /** Task has completed */
+    readonly TASK_COMPLETE: "_posthog/task_complete";
+    /** Error occurred during task execution */
+    readonly ERROR: "_posthog/error";
+    /** Console/log output */
+    readonly CONSOLE: "_posthog/console";
+    /** SDK session ID notification (for resumption) */
+    readonly SDK_SESSION: "_posthog/sdk_session";
+};
+type PostHogNotificationType = (typeof POSTHOG_NOTIFICATIONS)[keyof typeof POSTHOG_NOTIFICATIONS];
+interface ArtifactNotificationPayload {
+    sessionId: string;
+    kind: "research_evaluation" | "research_questions" | "plan" | "pr_body" | string;
+    content: unknown;
+}
+interface PhaseNotificationPayload {
+    sessionId: string;
+    phase: "research" | "plan" | "build" | "finalize" | string;
+    [key: string]: unknown;
+}
+interface BranchCreatedPayload {
+    sessionId: string;
+    branch: string;
+}
+/**
+ * Payload for PR created notification
+ */
+interface PrCreatedPayload {
+    sessionId: string;
+    prUrl: string;
+}
+interface RunStartedPayload {
+    sessionId: string;
+    runId: string;
+    taskId?: string;
+}
+/**
+ * Payload for task complete notification
+ */
+interface TaskCompletePayload {
+    sessionId: string;
+    taskId: string;
+}
+interface ErrorNotificationPayload {
+    sessionId: string;
+    message: string;
+    error?: unknown;
+}
+/**
+ * Console output for a session
+ */
+interface ConsoleNotificationPayload {
+    sessionId: string;
+    level: "debug" | "info" | "warn" | "error";
+    message: string;
+}
+/**
+ * Maps a session ID to a SDKs session ID
+ */
+interface SdkSessionPayload {
+    sessionId: string;
+    sdkSessionId: string;
+}
+type PostHogNotificationPayload = ArtifactNotificationPayload | PhaseNotificationPayload | BranchCreatedPayload | PrCreatedPayload | RunStartedPayload | TaskCompletePayload | ErrorNotificationPayload | ConsoleNotificationPayload | SdkSessionPayload;
+
+/**
+ * Stored custom notification following ACP extensibility model.
+ * Custom notifications use underscore-prefixed methods (e.g., `_posthog/phase_start`).
+ * See: https://agentclientprotocol.com/docs/extensibility
+ */
+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.
+ */
+type StoredEntry = StoredNotification;
+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";
+    github_integration?: number | null;
+    repository: string;
+    json_schema?: Record<string, unknown> | null;
+    created_at: string;
+    updated_at: string;
+    created_by?: {
+        id: number;
+        uuid: string;
+        distinct_id: string;
+        first_name: string;
+        email: string;
+    };
+    latest_run?: TaskRun;
+}
+type ArtifactType = "plan" | "context" | "reference" | "output" | "artifact";
+interface TaskRunArtifact {
+    name: string;
+    type: ArtifactType;
+    size?: number;
+    content_type?: string;
+    storage_path?: string;
+    uploaded_at?: string;
+}
+type TaskRunStatus = "not_started" | "queued" | "in_progress" | "completed" | "failed" | "cancelled";
+type TaskRunEnvironment = "local" | "cloud";
+interface TaskRun {
+    id: string;
+    task: string;
+    team: number;
+    branch: string | null;
+    stage: string | null;
+    environment: TaskRunEnvironment;
+    status: TaskRunStatus;
+    log_url: string;
+    error_message: string | null;
+    output: Record<string, unknown> | null;
+    state: Record<string, unknown>;
+    artifacts?: TaskRunArtifact[];
+    created_at: string;
+    updated_at: string;
+    completed_at: string | null;
+}
+interface SupportingFile {
+    name: string;
+    content: string;
+    type: ArtifactType;
+    created_at: string;
+}
+interface TaskArtifactUploadPayload {
+    name: string;
+    type: ArtifactType;
+    content: string;
+    content_type?: string;
+}
+declare enum PermissionMode {
+    PLAN = "plan",
+    DEFAULT = "default",
+    ACCEPT_EDITS = "acceptEdits",
+    BYPASS = "bypassPermissions"
+}
+interface TaskExecutionOptions {
+    repositoryPath?: string;
+    permissionMode?: PermissionMode;
+    isCloudMode?: boolean;
+    createPR?: boolean;
+    autoProgress?: boolean;
+    queryOverrides?: Record<string, unknown>;
+    canUseTool?: CanUseTool;
+    skipGitBranch?: boolean;
+}
+interface ExecutionResult {
+    results: any[];
+}
+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;
+};
+type LogLevel$1 = "debug" | "info" | "warn" | "error";
+type OnLogCallback = (level: LogLevel$1, scope: string, message: string, data?: unknown) => void;
+interface AgentConfig {
+    workingDirectory?: string;
+    posthogApiUrl?: string;
+    posthogApiKey?: string;
+    posthogProjectId?: number;
+    posthogMcpUrl?: string;
+    mcpServers?: Record<string, McpServerConfig>;
+    debug?: boolean;
+    onLog?: OnLogCallback;
+    canUseTool?: CanUseTool;
+}
+interface PostHogAPIConfig {
+    apiUrl: string;
+    apiKey: string;
+    projectId: number;
+}
+type ResourceType = "error" | "experiment" | "insight" | "feature_flag" | "generic";
+interface PostHogResource {
+    type: ResourceType;
+    id: string;
+    url: string;
+    title?: string;
+    content: string;
+    metadata?: Record<string, any>;
+}
+interface UrlMention {
+    url: string;
+    type: ResourceType;
+    id?: string;
+    label?: string;
+}
+interface ResearchQuestion {
+    id: string;
+    question: string;
+    options: string[];
+}
+interface ResearchAnswer {
+    questionId: string;
+    selectedOption: string;
+    customInput?: string;
+}
+interface ResearchEvaluation {
+    actionabilityScore: number;
+    context: string;
+    keyFiles: string[];
+    blockers?: string[];
+    questions?: ResearchQuestion[];
+    answered?: boolean;
+    answers?: ResearchAnswer[];
+}
+interface WorktreeInfo {
+    worktreePath: string;
+    worktreeName: string;
+    branchName: string;
+    baseBranch: string;
+    createdAt: string;
+}
+
+type TaskRunUpdate = Partial<Pick<TaskRun, "status" | "branch" | "stage" | "error_message" | "output" | "state">>;
+type TaskCreatePayload = Pick<Task, "description"> & Partial<Pick<Task, "title" | "repository" | "origin_product">>;
+declare class PostHogAPIClient {
+    private config;
+    constructor(config: PostHogAPIConfig);
+    private get baseUrl();
+    private get headers();
+    private apiRequest;
+    getTeamId(): number;
+    getBaseUrl(): string;
+    getApiKey(): string;
+    getLlmGatewayUrl(): string;
+    fetchTask(taskId: string): Promise<Task>;
+    listTasks(filters?: {
+        repository?: string;
+        organization?: string;
+        origin_product?: string;
+    }): Promise<Task[]>;
+    updateTask(taskId: string, updates: Partial<Task>): Promise<Task>;
+    createTask(payload: TaskCreatePayload): Promise<Task>;
+    listTaskRuns(taskId: string): Promise<TaskRun[]>;
+    getTaskRun(taskId: string, runId: string): Promise<TaskRun>;
+    createTaskRun(taskId: string, payload?: Partial<Omit<TaskRun, "id" | "task" | "team" | "created_at" | "updated_at" | "completed_at" | "artifacts">>): Promise<TaskRun>;
+    updateTaskRun(taskId: string, runId: string, payload: TaskRunUpdate): Promise<TaskRun>;
+    setTaskRunOutput(taskId: string, runId: string, output: Record<string, unknown>): Promise<TaskRun>;
+    appendTaskRunLog(taskId: string, runId: string, entries: StoredEntry[]): Promise<TaskRun>;
+    uploadTaskArtifacts(taskId: string, runId: string, artifacts: TaskArtifactUploadPayload[]): Promise<TaskRunArtifact[]>;
+    /**
+     * Fetch logs from S3 using presigned URL from TaskRun
+     * @param taskRun - The task run containing the log_url
+     * @returns Array of stored entries, or empty array if no logs available
+     */
+    fetchTaskRunLogs(taskRun: TaskRun): Promise<StoredEntry[]>;
+    /**
+     * Fetch error details from PostHog error tracking
+     */
+    fetchErrorDetails(errorId: string, projectId?: string): Promise<PostHogResource>;
+    /**
+     * Generic resource fetcher by URL or ID
+     */
+    fetchResourceByUrl(urlMention: UrlMention): Promise<PostHogResource>;
+    /**
+     * Format error data for agent consumption
+     */
+    private formatErrorContent;
+}
+
+/**
+ * Simple logger utility with configurable debug mode and external log forwarding
+ */
+declare enum LogLevel {
+    ERROR = 0,
+    WARN = 1,
+    INFO = 2,
+    DEBUG = 3
+}
+interface LoggerConfig {
+    debug?: boolean;
+    prefix?: string;
+    scope?: string;
+    onLog?: OnLogCallback;
+}
+declare class Logger {
+    private debugEnabled;
+    private prefix;
+    private scope;
+    private onLog?;
+    constructor(config?: LoggerConfig);
+    setDebug(enabled: boolean): void;
+    setOnLog(onLog: OnLogCallback | undefined): void;
+    private formatMessage;
+    private emitLog;
+    error(message: string, error?: Error | unknown): void;
+    warn(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    debug(message: string, data?: unknown): void;
+    log(level: LogLevel$1, message: string, data?: unknown, scope?: string): void;
+    /**
+     * Create a child logger with additional prefix and scope
+     */
+    child(childPrefix: string): Logger;
+}
+
+interface SessionPersistenceConfig {
+    taskId: string;
+    runId: string;
+    logUrl: string;
+    sdkSessionId?: string;
+}
+declare class SessionStore {
+    private posthogAPI?;
+    private pendingEntries;
+    private flushTimeouts;
+    private configs;
+    private logger;
+    constructor(posthogAPI?: PostHogAPIClient, logger?: Logger);
+    /** Register a session for persistence */
+    register(sessionId: string, config: SessionPersistenceConfig): void;
+    /** Unregister and flush pending */
+    unregister(sessionId: string): Promise<void>;
+    /** Check if a session is registered for persistence */
+    isRegistered(sessionId: string): boolean;
+    /**
+     * Append a raw JSON-RPC line for persistence.
+     * Parses and wraps as StoredNotification for the API.
+     */
+    appendRawLine(sessionId: string, line: string): void;
+    /** Load raw JSON-RPC messages from S3 */
+    load(logUrl: string): Promise<StoredNotification[]>;
+    /**
+     * Poll S3 for new entries since last check.
+     * Used for interrupt handling in cloud mode.
+     */
+    pollForNewEntries(sessionId: string, lastKnownCount: number): Promise<StoredNotification[]>;
+    /** Force flush pending entries */
+    flush(sessionId: string): Promise<void>;
+    private scheduleFlush;
+    /** Get the persistence config for a session */
+    getConfig(sessionId: string): SessionPersistenceConfig | undefined;
+    /**
+     * Start a session for persistence.
+     * Loads the task run and updates status to "in_progress".
+     */
+    start(sessionId: string, taskId: string, runId: string): Promise<TaskRun | undefined>;
+    /**
+     * Mark a session as completed.
+     */
+    complete(sessionId: string): Promise<void>;
+    /**
+     * Mark a session as failed.
+     */
+    fail(sessionId: string, error: Error | string): Promise<void>;
+    /**
+     * Update the task run associated with a session.
+     */
+    updateTaskRun(sessionId: string, update: TaskRunUpdate): Promise<TaskRun | undefined>;
+}
+
+type StreamPair = {
+    readable: globalThis.ReadableStream<Uint8Array>;
+    writable: globalThis.WritableStream<Uint8Array>;
+};
+
+/**
+ * The claude adapter has been based on the original claude-code-acp adapter,
+ * and could use some cleanup.
+ *
+ * https://github.com/zed-industries/claude-code-acp
+ */
+
+type AcpConnectionConfig = {
+    sessionStore?: SessionStore;
+    sessionId?: string;
+    taskId?: string;
+};
+type InProcessAcpConnection = {
+    agentConnection: AgentSideConnection;
+    clientStreams: StreamPair;
+};
+declare function createAcpConnection(config?: AcpConnectionConfig): InProcessAcpConnection;
+
+declare class Agent {
+    private workingDirectory;
+    private taskManager;
+    private posthogAPI?;
+    private fileManager;
+    private gitManager;
+    private templateManager;
+    private logger;
+    private acpConnection?;
+    private promptBuilder;
+    private mcpServers?;
+    private canUseTool?;
+    private currentRunId?;
+    private sessionStore?;
+    debug: boolean;
+    constructor(config: AgentConfig);
+    /**
+     * Enable or disable debug logging
+     */
+    setDebug(enabled: boolean): void;
+    /**
+     * Configure LLM gateway environment variables for Claude Code CLI
+     */
+    private _configureLlmGateway;
+    private getOrCreateConnection;
+    runTask(taskId: string, taskRunId: string, options?: TaskExecutionOptions): Promise<void>;
+    /**
+     * Creates an in-process ACP connection for client communication.
+     * Sets up git branch for the task, configures LLM gateway.
+     * The client handles all prompting/querying via the returned streams.
+     *
+     * @returns InProcessAcpConnection with clientStreams for the client to use
+     */
+    runTaskV2(taskId: string, taskRunId: string, options?: TaskExecutionOptions): Promise<InProcessAcpConnection>;
+    fetchTask(taskId: string): Promise<Task>;
+    getPostHogClient(): PostHogAPIClient | undefined;
+    /**
+     * Send a notification to a cloud task run's S3 log.
+     * The cloud runner will pick up new notifications via interrupt polling.
+     */
+    sendNotification(taskId: string, runId: string, notification: StoredNotification): Promise<void>;
+    getTaskFiles(taskId: string): Promise<any[]>;
+    createPullRequest(taskId: string, branchName: string, taskTitle: string, taskDescription: string, customBody?: string): Promise<string>;
+    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;
+    private prepareTaskBranch;
+    private ensureOpenAIGatewayEnv;
+    runTaskCloud(taskId: string, taskRunId: string, options?: TaskExecutionOptions): Promise<void>;
+    private ensurePullRequest;
+}
+
+declare const TokenEventSchema: z.ZodObject<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"token">;
+    content: z.ZodString;
+    contentType: z.ZodOptional<z.ZodEnum<["text", "thinking", "tool_input"]>>;
+}, "strip", z.ZodTypeAny, {
+    type: "token";
+    content: string;
+    ts: number;
+    contentType?: "text" | "thinking" | "tool_input" | undefined;
+}, {
+    type: "token";
+    content: string;
+    ts: number;
+    contentType?: "text" | "thinking" | "tool_input" | undefined;
+}>;
+declare const StatusEventSchema: z.ZodObject<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"status">;
+    phase: z.ZodString;
+    kind: z.ZodOptional<z.ZodString>;
+    branch: z.ZodOptional<z.ZodString>;
+    prUrl: z.ZodOptional<z.ZodString>;
+    taskId: z.ZodOptional<z.ZodString>;
+    messageId: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"status">;
+    phase: z.ZodString;
+    kind: z.ZodOptional<z.ZodString>;
+    branch: z.ZodOptional<z.ZodString>;
+    prUrl: z.ZodOptional<z.ZodString>;
+    taskId: z.ZodOptional<z.ZodString>;
+    messageId: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"status">;
+    phase: z.ZodString;
+    kind: z.ZodOptional<z.ZodString>;
+    branch: z.ZodOptional<z.ZodString>;
+    prUrl: z.ZodOptional<z.ZodString>;
+    taskId: z.ZodOptional<z.ZodString>;
+    messageId: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>;
+declare const ConsoleEventSchema: z.ZodObject<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"console">;
+    level: z.ZodEnum<["debug", "info", "warn", "error"]>;
+    message: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "console";
+    message: string;
+    ts: number;
+    level: "debug" | "info" | "warn" | "error";
+}, {
+    type: "console";
+    message: string;
+    ts: number;
+    level: "debug" | "info" | "warn" | "error";
+}>;
+declare const ErrorEventSchema: z.ZodObject<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"error">;
+    message: z.ZodString;
+    error: z.ZodOptional<z.ZodUnknown>;
+    errorType: z.ZodOptional<z.ZodString>;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    sdkError: z.ZodOptional<z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    type: "error";
+    message: string;
+    ts: number;
+    error?: unknown;
+    context?: Record<string, unknown> | undefined;
+    errorType?: string | undefined;
+    sdkError?: unknown;
+}, {
+    type: "error";
+    message: string;
+    ts: number;
+    error?: unknown;
+    context?: Record<string, unknown> | undefined;
+    errorType?: string | undefined;
+    sdkError?: unknown;
+}>;
+declare const AgentEventSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"token">;
+    content: z.ZodString;
+    contentType: z.ZodOptional<z.ZodEnum<["text", "thinking", "tool_input"]>>;
+}, "strip", z.ZodTypeAny, {
+    type: "token";
+    content: string;
+    ts: number;
+    contentType?: "text" | "thinking" | "tool_input" | undefined;
+}, {
+    type: "token";
+    content: string;
+    ts: number;
+    contentType?: "text" | "thinking" | "tool_input" | undefined;
+}>, z.ZodObject<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"content_block_start">;
+    index: z.ZodNumber;
+    contentType: z.ZodEnum<["text", "tool_use", "thinking"]>;
+    toolName: z.ZodOptional<z.ZodString>;
+    toolId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "content_block_start";
+    ts: number;
+    contentType: "text" | "tool_use" | "thinking";
+    index: number;
+    toolName?: string | undefined;
+    toolId?: string | undefined;
+}, {
+    type: "content_block_start";
+    ts: number;
+    contentType: "text" | "tool_use" | "thinking";
+    index: number;
+    toolName?: string | undefined;
+    toolId?: string | undefined;
+}>, z.ZodObject<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"content_block_stop">;
+    index: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    type: "content_block_stop";
+    ts: number;
+    index: number;
+}, {
+    type: "content_block_stop";
+    ts: number;
+    index: number;
+}>, z.ZodObject<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"tool_call">;
+    toolName: z.ZodString;
+    callId: z.ZodString;
+    args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    parentToolUseId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    tool: z.ZodOptional<z.ZodUnknown>;
+    category: z.ZodOptional<z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    type: "tool_call";
+    args: Record<string, unknown>;
+    toolName: string;
+    ts: number;
+    callId: string;
+    parentToolUseId?: string | null | undefined;
+    tool?: unknown;
+    category?: unknown;
+}, {
+    type: "tool_call";
+    args: Record<string, unknown>;
+    toolName: string;
+    ts: number;
+    callId: string;
+    parentToolUseId?: string | null | undefined;
+    tool?: unknown;
+    category?: unknown;
+}>, z.ZodObject<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"tool_result">;
+    toolName: z.ZodString;
+    callId: z.ZodString;
+    result: z.ZodUnknown;
+    isError: z.ZodOptional<z.ZodBoolean>;
+    parentToolUseId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    tool: z.ZodOptional<z.ZodUnknown>;
+    category: z.ZodOptional<z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    type: "tool_result";
+    toolName: string;
+    ts: number;
+    callId: string;
+    isError?: boolean | undefined;
+    result?: unknown;
+    parentToolUseId?: string | null | undefined;
+    tool?: unknown;
+    category?: unknown;
+}, {
+    type: "tool_result";
+    toolName: string;
+    ts: number;
+    callId: string;
+    isError?: boolean | undefined;
+    result?: unknown;
+    parentToolUseId?: string | null | undefined;
+    tool?: unknown;
+    category?: unknown;
+}>, z.ZodObject<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"message_start">;
+    messageId: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "message_start";
+    ts: number;
+    model?: string | undefined;
+    messageId?: string | undefined;
+}, {
+    type: "message_start";
+    ts: number;
+    model?: string | undefined;
+    messageId?: string | undefined;
+}>, z.ZodObject<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"message_delta">;
+    stopReason: z.ZodOptional<z.ZodString>;
+    stopSequence: z.ZodOptional<z.ZodString>;
+    usage: z.ZodOptional<z.ZodObject<{
+        outputTokens: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        outputTokens: number;
+    }, {
+        outputTokens: number;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    type: "message_delta";
+    ts: number;
+    stopReason?: string | undefined;
+    usage?: {
+        outputTokens: number;
+    } | undefined;
+    stopSequence?: string | undefined;
+}, {
+    type: "message_delta";
+    ts: number;
+    stopReason?: string | undefined;
+    usage?: {
+        outputTokens: number;
+    } | undefined;
+    stopSequence?: string | undefined;
+}>, z.ZodObject<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"message_stop">;
+}, "strip", z.ZodTypeAny, {
+    type: "message_stop";
+    ts: number;
+}, {
+    type: "message_stop";
+    ts: number;
+}>, z.ZodObject<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"user_message">;
+    content: z.ZodString;
+    isSynthetic: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    type: "user_message";
+    content: string;
+    ts: number;
+    isSynthetic?: boolean | undefined;
+}, {
+    type: "user_message";
+    content: string;
+    ts: number;
+    isSynthetic?: boolean | undefined;
+}>, z.ZodObject<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"status">;
+    phase: z.ZodString;
+    kind: z.ZodOptional<z.ZodString>;
+    branch: z.ZodOptional<z.ZodString>;
+    prUrl: z.ZodOptional<z.ZodString>;
+    taskId: z.ZodOptional<z.ZodString>;
+    messageId: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"status">;
+    phase: z.ZodString;
+    kind: z.ZodOptional<z.ZodString>;
+    branch: z.ZodOptional<z.ZodString>;
+    prUrl: z.ZodOptional<z.ZodString>;
+    taskId: z.ZodOptional<z.ZodString>;
+    messageId: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"status">;
+    phase: z.ZodString;
+    kind: z.ZodOptional<z.ZodString>;
+    branch: z.ZodOptional<z.ZodString>;
+    prUrl: z.ZodOptional<z.ZodString>;
+    taskId: z.ZodOptional<z.ZodString>;
+    messageId: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>, z.ZodObject<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"init">;
+    model: z.ZodString;
+    tools: z.ZodArray<z.ZodString, "many">;
+    permissionMode: z.ZodString;
+    cwd: z.ZodString;
+    apiKeySource: z.ZodString;
+    agents: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    slashCommands: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    outputStyle: z.ZodOptional<z.ZodString>;
+    mcpServers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        status: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        status: string;
+        name: string;
+    }, {
+        status: string;
+        name: string;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    type: "init";
+    tools: string[];
+    cwd: string;
+    model: string;
+    permissionMode: string;
+    apiKeySource: string;
+    ts: number;
+    mcpServers?: {
+        status: string;
+        name: string;
+    }[] | undefined;
+    agents?: string[] | undefined;
+    slashCommands?: string[] | undefined;
+    outputStyle?: string | undefined;
+}, {
+    type: "init";
+    tools: string[];
+    cwd: string;
+    model: string;
+    permissionMode: string;
+    apiKeySource: string;
+    ts: number;
+    mcpServers?: {
+        status: string;
+        name: string;
+    }[] | undefined;
+    agents?: string[] | undefined;
+    slashCommands?: string[] | undefined;
+    outputStyle?: string | undefined;
+}>, z.ZodObject<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"console">;
+    level: z.ZodEnum<["debug", "info", "warn", "error"]>;
+    message: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "console";
+    message: string;
+    ts: number;
+    level: "debug" | "info" | "warn" | "error";
+}, {
+    type: "console";
+    message: string;
+    ts: number;
+    level: "debug" | "info" | "warn" | "error";
+}>, z.ZodObject<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"compact_boundary">;
+    trigger: z.ZodEnum<["manual", "auto"]>;
+    preTokens: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    type: "compact_boundary";
+    ts: number;
+    trigger: "manual" | "auto";
+    preTokens: number;
+}, {
+    type: "compact_boundary";
+    ts: number;
+    trigger: "manual" | "auto";
+    preTokens: number;
+}>, z.ZodObject<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"done">;
+    result: z.ZodOptional<z.ZodString>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    durationApiMs: z.ZodOptional<z.ZodNumber>;
+    numTurns: z.ZodOptional<z.ZodNumber>;
+    totalCostUsd: z.ZodOptional<z.ZodNumber>;
+    usage: z.ZodOptional<z.ZodUnknown>;
+    modelUsage: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        cacheReadInputTokens: z.ZodNumber;
+        cacheCreationInputTokens: z.ZodNumber;
+        webSearchRequests: z.ZodNumber;
+        costUSD: z.ZodNumber;
+        contextWindow: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        outputTokens: number;
+        inputTokens: number;
+        cacheReadInputTokens: number;
+        cacheCreationInputTokens: number;
+        webSearchRequests: number;
+        costUSD: number;
+        contextWindow: number;
+    }, {
+        outputTokens: number;
+        inputTokens: number;
+        cacheReadInputTokens: number;
+        cacheCreationInputTokens: number;
+        webSearchRequests: number;
+        costUSD: number;
+        contextWindow: number;
+    }>>>;
+    permissionDenials: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        tool_name: z.ZodString;
+        tool_use_id: z.ZodString;
+        tool_input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        tool_use_id: string;
+        tool_name: string;
+        tool_input: Record<string, unknown>;
+    }, {
+        tool_use_id: string;
+        tool_name: string;
+        tool_input: Record<string, unknown>;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    type: "done";
+    ts: number;
+    result?: string | undefined;
+    usage?: unknown;
+    modelUsage?: Record<string, {
+        outputTokens: number;
+        inputTokens: number;
+        cacheReadInputTokens: number;
+        cacheCreationInputTokens: number;
+        webSearchRequests: number;
+        costUSD: number;
+        contextWindow: number;
+    }> | undefined;
+    durationMs?: number | undefined;
+    durationApiMs?: number | undefined;
+    numTurns?: number | undefined;
+    totalCostUsd?: number | undefined;
+    permissionDenials?: {
+        tool_use_id: string;
+        tool_name: string;
+        tool_input: Record<string, unknown>;
+    }[] | undefined;
+}, {
+    type: "done";
+    ts: number;
+    result?: string | undefined;
+    usage?: unknown;
+    modelUsage?: Record<string, {
+        outputTokens: number;
+        inputTokens: number;
+        cacheReadInputTokens: number;
+        cacheCreationInputTokens: number;
+        webSearchRequests: number;
+        costUSD: number;
+        contextWindow: number;
+    }> | undefined;
+    durationMs?: number | undefined;
+    durationApiMs?: number | undefined;
+    numTurns?: number | undefined;
+    totalCostUsd?: number | undefined;
+    permissionDenials?: {
+        tool_use_id: string;
+        tool_name: string;
+        tool_input: Record<string, unknown>;
+    }[] | undefined;
+}>, z.ZodObject<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"error">;
+    message: z.ZodString;
+    error: z.ZodOptional<z.ZodUnknown>;
+    errorType: z.ZodOptional<z.ZodString>;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    sdkError: z.ZodOptional<z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    type: "error";
+    message: string;
+    ts: number;
+    error?: unknown;
+    context?: Record<string, unknown> | undefined;
+    errorType?: string | undefined;
+    sdkError?: unknown;
+}, {
+    type: "error";
+    message: string;
+    ts: number;
+    error?: unknown;
+    context?: Record<string, unknown> | undefined;
+    errorType?: string | undefined;
+    sdkError?: unknown;
+}>, z.ZodObject<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"metric">;
+    key: z.ZodString;
+    value: z.ZodNumber;
+    unit: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+    value: number;
+    type: "metric";
+    ts: number;
+    unit?: string | undefined;
+}, {
+    key: string;
+    value: number;
+    type: "metric";
+    ts: number;
+    unit?: string | undefined;
+}>, z.ZodObject<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"artifact">;
+    kind: z.ZodString;
+    content: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    type: "artifact";
+    kind: string;
+    ts: number;
+    content?: unknown;
+}, {
+    type: "artifact";
+    kind: string;
+    ts: number;
+    content?: unknown;
+}>, z.ZodObject<{
+    ts: z.ZodNumber;
+} & {
+    type: z.ZodLiteral<"raw_sdk_event">;
+    sdkMessage: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    type: "raw_sdk_event";
+    ts: number;
+    sdkMessage?: unknown;
+}, {
+    type: "raw_sdk_event";
+    ts: number;
+    sdkMessage?: unknown;
+}>]>;
+type TokenEvent = z.infer<typeof TokenEventSchema>;
+type StatusEvent = z.infer<typeof StatusEventSchema>;
+type ConsoleEvent = z.infer<typeof ConsoleEventSchema>;
+type ErrorEvent = z.infer<typeof ErrorEventSchema>;
+type AgentEvent = z.infer<typeof AgentEventSchema>;
+/**
+ * Parse and validate an AgentEvent from unknown input.
+ * Returns the parsed event if valid, or null if invalid.
+ */
+declare function parseAgentEvent(input: unknown): AgentEvent | null;
+/**
+ * Parse and validate multiple AgentEvents from an array of unknown inputs.
+ * Invalid entries are discarded.
+ */
+declare function parseAgentEvents(inputs: unknown[]): AgentEvent[];
+
+interface TaskFile {
+    name: string;
+    content: string;
+    type: "plan" | "context" | "reference" | "output" | "artifact";
+}
+interface LocalArtifact {
+    name: string;
+    content: string;
+    type: TaskFile["type"];
+    contentType: string;
+    size: number;
+}
+declare class PostHogFileManager {
+    private repositoryPath;
+    private logger;
+    constructor(repositoryPath: string, logger?: Logger);
+    private getTaskDirectory;
+    private getTaskFilePath;
+    ensureTaskDirectory(taskId: string): Promise<void>;
+    writeTaskFile(taskId: string, file: TaskFile): Promise<void>;
+    readTaskFile(taskId: string, fileName: string): Promise<string | null>;
+    listTaskFiles(taskId: string): Promise<string[]>;
+    deleteTaskFile(taskId: string, fileName: string): Promise<void>;
+    taskDirectoryExists(taskId: string): Promise<boolean>;
+    cleanupTaskDirectory(taskId: string): Promise<void>;
+    writePlan(taskId: string, plan: string): Promise<void>;
+    readPlan(taskId: string): Promise<string | null>;
+    writeContext(taskId: string, context: string): Promise<void>;
+    readContext(taskId: string): Promise<string | null>;
+    writeRequirements(taskId: string, requirements: string): Promise<void>;
+    readRequirements(taskId: string): Promise<string | null>;
+    writeResearch(taskId: string, data: ResearchEvaluation): Promise<void>;
+    readResearch(taskId: string): Promise<ResearchEvaluation | null>;
+    writeTodos(taskId: string, data: unknown): Promise<void>;
+    readTodos(taskId: string): Promise<unknown | null>;
+    getTaskFiles(taskId: string): Promise<SupportingFile[]>;
+    collectTaskArtifacts(taskId: string): Promise<LocalArtifact[]>;
+    private resolveFileType;
+    private inferContentType;
+}
+
+interface TodoItem {
+    content: string;
+    status: "pending" | "in_progress" | "completed";
+    activeForm: string;
+}
+interface TodoList {
+    items: TodoItem[];
+    metadata: {
+        total: number;
+        pending: number;
+        in_progress: number;
+        completed: number;
+        last_updated: string;
+    };
+}
+declare class TodoManager {
+    private fileManager;
+    private logger;
+    constructor(fileManager: PostHogFileManager, logger?: Logger);
+    readTodos(taskId: string): Promise<TodoList | null>;
+    writeTodos(taskId: string, todos: TodoList): Promise<void>;
+    parseTodoWriteInput(toolInput: Record<string, unknown>): TodoList;
+    private calculateMetadata;
+    getTodoContext(taskId: string): Promise<string>;
+    checkAndPersistFromMessage(message: Record<string, unknown>, taskId: string): Promise<TodoList | null>;
+}
+
+/**
+ * Tool category classification for grouping related tools.
+ * Makes it easier for UIs to filter and display tools by function.
+ */
+type ToolCategory = "filesystem" | "shell" | "web" | "assistant" | "search" | "unknown";
+/**
+ * Base tool interface representing a tool that can be called by the agent.
+ * Each tool has a name, category, and human-readable description.
+ */
+interface Tool {
+    name: string;
+    category: ToolCategory;
+    description: string;
+}
+interface ReadTool extends Tool {
+    name: "Read";
+    category: "filesystem";
+}
+interface WriteTool extends Tool {
+    name: "Write";
+    category: "filesystem";
+}
+interface EditTool extends Tool {
+    name: "Edit";
+    category: "filesystem";
+}
+interface GlobTool extends Tool {
+    name: "Glob";
+    category: "filesystem";
+}
+interface NotebookEditTool extends Tool {
+    name: "NotebookEdit";
+    category: "filesystem";
+}
+interface BashTool extends Tool {
+    name: "Bash";
+    category: "shell";
+}
+interface BashOutputTool extends Tool {
+    name: "BashOutput";
+    category: "shell";
+}
+interface KillShellTool extends Tool {
+    name: "KillShell";
+    category: "shell";
+}
+interface WebFetchTool extends Tool {
+    name: "WebFetch";
+    category: "web";
+}
+interface WebSearchTool extends Tool {
+    name: "WebSearch";
+    category: "web";
+}
+interface GrepTool extends Tool {
+    name: "Grep";
+    category: "search";
+}
+interface TaskTool extends Tool {
+    name: "Task";
+    category: "assistant";
+}
+interface TodoWriteTool extends Tool {
+    name: "TodoWrite";
+    category: "assistant";
+}
+interface ExitPlanModeTool extends Tool {
+    name: "ExitPlanMode";
+    category: "assistant";
+}
+interface SlashCommandTool extends Tool {
+    name: "SlashCommand";
+    category: "assistant";
+}
+/**
+ * Union type of all known tool types.
+ * Useful for discriminated unions and type narrowing.
+ */
+type KnownTool = ReadTool | WriteTool | EditTool | GlobTool | NotebookEditTool | BashTool | BashOutputTool | KillShellTool | WebFetchTool | WebSearchTool | GrepTool | TaskTool | TodoWriteTool | ExitPlanModeTool | SlashCommandTool;
+
+/**
+ * Tool registry for looking up tool definitions by name.
+ * Provides metadata about tools for UI consumption.
+ */
+declare class ToolRegistry {
+    /**
+     * Get tool definition by name.
+     * Returns undefined if tool is not recognized.
+     */
+    get(name: string): Tool | undefined;
+    /**
+     * Get all registered tools.
+     */
+    getAll(): Tool[];
+    /**
+     * Check if a tool name is registered.
+     */
+    has(name: string): boolean;
+    /**
+     * Get all tools in a specific category.
+     */
+    getByCategory(category: string): Tool[];
+}
+
+interface WorktreeConfig {
+    mainRepoPath: string;
+    worktreeBasePath?: string;
+    logger?: Logger;
+}
+declare class WorktreeManager {
+    private mainRepoPath;
+    private worktreeBasePath;
+    private repoName;
+    private logger;
+    constructor(config: WorktreeConfig);
+    private usesExternalPath;
+    private runGitCommand;
+    private randomElement;
+    generateWorktreeName(): string;
+    private getWorktreeFolderPath;
+    private getWorktreePath;
+    worktreeExists(name: string): Promise<boolean>;
+    ensureArrayDirIgnored(): Promise<void>;
+    private generateUniqueWorktreeName;
+    private getDefaultBranch;
+    createWorktree(): Promise<WorktreeInfo>;
+    deleteWorktree(worktreePath: string): Promise<void>;
+    getWorktreeInfo(worktreePath: string): Promise<WorktreeInfo | null>;
+    listWorktrees(): Promise<WorktreeInfo[]>;
+    private parseWorktreeList;
+    isWorktree(repoPath: string): Promise<boolean>;
+    getMainRepoPathFromWorktree(worktreePath: string): Promise<string | null>;
+    cleanupOrphanedWorktrees(associatedWorktreePaths: string[]): Promise<{
+        deleted: string[];
+        errors: Array<{
+            path: string;
+            error: string;
+        }>;
+    }>;
+}
+
+export { type AcpConnectionConfig, Agent, type AgentConfig, type AgentEvent, type ArtifactNotificationPayload, type BashOutputTool, type BashTool, type BranchCreatedPayload, type ConsoleEvent, type ConsoleNotificationPayload, type EditTool, type ErrorEvent, type ErrorNotificationPayload, type ExecutionResult, type ExitPlanModeTool, type GlobTool, type GrepTool, type InProcessAcpConnection, type KillShellTool, type KnownTool, LogLevel, type LogLevel$1 as LogLevelType, Logger, type LoggerConfig, type McpServerConfig, type NotebookEditTool, type OnLogCallback, POSTHOG_NOTIFICATIONS, PermissionMode, type PhaseNotificationPayload, type PostHogNotificationPayload, type PostHogNotificationType, type PrCreatedPayload, type ReadTool, type ResearchEvaluation, type RunStartedPayload, type SdkSessionPayload, type SessionPersistenceConfig, SessionStore, type SlashCommandTool, type StatusEvent, type StoredEntry, type StoredNotification, type SupportingFile, type Task, type TaskCompletePayload, type TaskRun, type TaskTool, type TodoItem, type TodoList, TodoManager, type TodoWriteTool, type TokenEvent, type Tool, type ToolCategory, ToolRegistry, type WebFetchTool, type WebSearchTool, type WorktreeConfig, type WorktreeInfo, WorktreeManager, type WriteTool, createAcpConnection, parseAgentEvent, parseAgentEvents };