@posthog/agent 2.0.0 → 2.0.2

package/src/posthog-api.ts

@@ -1,32 +1,35 @@
 import type {
+  ArtifactType,
   PostHogAPIConfig,
-  PostHogResource,
   StoredEntry,
   Task,
-  TaskArtifactUploadPayload,
   TaskRun,
   TaskRunArtifact,
-  UrlMention,
 } from "./types.js";
 import { getLlmGatewayUrl } from "./utils/gateway.js";
 
-interface PostHogApiResponse<T> {
-  results?: T[];
-  count?: number;
-  next?: string | null;
-  previous?: string | null;
+export { getLlmGatewayUrl };
+
+export interface TaskArtifactUploadPayload {
+  name: string;
+  type: ArtifactType;
+  content: string;
+  content_type?: string;
 }
 
 export type TaskRunUpdate = Partial<
   Pick<
     TaskRun,
-    "status" | "branch" | "stage" | "error_message" | "output" | "state"
+    | "status"
+    | "branch"
+    | "stage"
+    | "error_message"
+    | "output"
+    | "state"
+    | "environment"
   >
 >;
 
-export type TaskCreatePayload = Pick<Task, "description"> &
-  Partial<Pick<Task, "title" | "repository" | "origin_product">>;
-
 export class PostHogAPIClient {
   private config: PostHogAPIConfig;
 
@@ -76,14 +79,10 @@ export class PostHogAPIClient {
     return response.json();
   }
 
-  getTeamId(): number {
+  private getTeamId(): number {
     return this.config.projectId;
   }
 
-  getBaseUrl(): string {
-    return this.baseUrl;
-  }
-
   getApiKey(): string {
     return this.config.getApiKey();
   }
@@ -92,60 +91,11 @@ export class PostHogAPIClient {
     return getLlmGatewayUrl(this.baseUrl);
   }
 
-  async fetchTask(taskId: string): Promise<Task> {
+  async getTask(taskId: string): Promise<Task> {
     const teamId = this.getTeamId();
     return this.apiRequest<Task>(`/api/projects/${teamId}/tasks/${taskId}/`);
   }
 
-  async listTasks(filters?: {
-    repository?: string;
-    organization?: string;
-    origin_product?: string;
-  }): Promise<Task[]> {
-    const teamId = this.getTeamId();
-    const url = new URL(`${this.baseUrl}/api/projects/${teamId}/tasks/`);
-
-    if (filters) {
-      Object.entries(filters).forEach(([key, value]) => {
-        if (value) url.searchParams.append(key, value);
-      });
-    }
-
-    const response = await this.apiRequest<PostHogApiResponse<Task>>(
-      url.pathname + url.search,
-    );
-
-    return response.results || [];
-  }
-
-  async updateTask(taskId: string, updates: Partial<Task>): Promise<Task> {
-    const teamId = this.getTeamId();
-    return this.apiRequest<Task>(`/api/projects/${teamId}/tasks/${taskId}/`, {
-      method: "PATCH",
-      body: JSON.stringify(updates),
-    });
-  }
-
-  async createTask(payload: TaskCreatePayload): Promise<Task> {
-    const teamId = this.getTeamId();
-    return this.apiRequest<Task>(`/api/projects/${teamId}/tasks/`, {
-      method: "POST",
-      body: JSON.stringify({
-        origin_product: "user_created",
-        ...payload,
-      }),
-    });
-  }
-
-  // TaskRun methods
-  async listTaskRuns(taskId: string): Promise<TaskRun[]> {
-    const teamId = this.getTeamId();
-    const response = await this.apiRequest<PostHogApiResponse<TaskRun>>(
-      `/api/projects/${teamId}/tasks/${taskId}/runs/`,
-    );
-    return response.results || [];
-  }
-
   async getTaskRun(taskId: string, runId: string): Promise<TaskRun> {
     const teamId = this.getTeamId();
     return this.apiRequest<TaskRun>(
@@ -153,31 +103,6 @@ export class PostHogAPIClient {
     );
   }
 
-  async createTaskRun(
-    taskId: string,
-    payload?: Partial<
-      Omit<
-        TaskRun,
-        | "id"
-        | "task"
-        | "team"
-        | "created_at"
-        | "updated_at"
-        | "completed_at"
-        | "artifacts"
-      >
-    >,
-  ): Promise<TaskRun> {
-    const teamId = this.getTeamId();
-    return this.apiRequest<TaskRun>(
-      `/api/projects/${teamId}/tasks/${taskId}/runs/`,
-      {
-        method: "POST",
-        body: JSON.stringify(payload || {}),
-      },
-    );
-  }
-
   async updateTaskRun(
     taskId: string,
     runId: string,
@@ -193,21 +118,6 @@ export class PostHogAPIClient {
     );
   }
 
-  async setTaskRunOutput(
-    taskId: string,
-    runId: string,
-    output: Record<string, unknown>,
-  ): Promise<TaskRun> {
-    const teamId = this.getTeamId();
-    return this.apiRequest<TaskRun>(
-      `/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/set_output/`,
-      {
-        method: "PATCH",
-        body: JSON.stringify({ output }),
-      },
-    );
-  }
-
   async appendTaskRunLog(
     taskId: string,
     runId: string,
@@ -244,20 +154,72 @@ export class PostHogAPIClient {
     return response.artifacts ?? [];
   }
 
+  async getArtifactPresignedUrl(
+    taskId: string,
+    runId: string,
+    storagePath: string,
+  ): Promise<string | null> {
+    const teamId = this.getTeamId();
+    try {
+      const response = await this.apiRequest<{
+        url: string;
+        expires_in: number;
+      }>(
+        `/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/artifacts/presign/`,
+        {
+          method: "POST",
+          body: JSON.stringify({ storage_path: storagePath }),
+        },
+      );
+      return response.url;
+    } catch {
+      return null;
+    }
+  }
+
   /**
-   * Fetch logs from S3 using presigned URL from TaskRun
-   * @param taskRun - The task run containing the log_url
+   * Download artifact content by storage path
+   * Gets a presigned URL and fetches the content
+   */
+  async downloadArtifact(
+    taskId: string,
+    runId: string,
+    storagePath: string,
+  ): Promise<ArrayBuffer | null> {
+    const url = await this.getArtifactPresignedUrl(taskId, runId, storagePath);
+    if (!url) {
+      return null;
+    }
+
+    try {
+      const response = await fetch(url);
+      if (!response.ok) {
+        throw new Error(`Failed to download artifact: ${response.status}`);
+      }
+      return response.arrayBuffer();
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Fetch logs for a task run via the logs API endpoint
+   * @param taskRun - The task run to fetch logs for
    * @returns Array of stored entries, or empty array if no logs available
    */
   async fetchTaskRunLogs(taskRun: TaskRun): Promise<StoredEntry[]> {
-    if (!taskRun.log_url) {
-      return [];
-    }
+    const teamId = this.getTeamId();
 
     try {
-      const response = await fetch(taskRun.log_url);
+      const response = await fetch(
+        `${this.baseUrl}/api/projects/${teamId}/tasks/${taskRun.task}/runs/${taskRun.id}/logs`,
+        { headers: this.headers },
+      );
 
       if (!response.ok) {
+        if (response.status === 404) {
+          return [];
+        }
         throw new Error(
           `Failed to fetch logs: ${response.status} ${response.statusText}`,
         );
@@ -280,126 +242,4 @@ export class PostHogAPIClient {
       );
     }
   }
-
-  /**
-   * Fetch error details from PostHog error tracking
-   */
-  async fetchErrorDetails(
-    errorId: string,
-    projectId?: string,
-  ): Promise<PostHogResource> {
-    const teamId = projectId ? parseInt(projectId, 10) : this.getTeamId();
-
-    try {
-      const errorData = await this.apiRequest<Record<string, unknown>>(
-        `/api/projects/${teamId}/error_tracking/${errorId}/`,
-      );
-
-      // Format error details for agent consumption
-      const content = this.formatErrorContent(errorData);
-
-      return {
-        type: "error",
-        id: errorId,
-        url: `${this.baseUrl}/project/${teamId}/error_tracking/${errorId}`,
-        title:
-          (typeof errorData.exception_type === "string"
-            ? errorData.exception_type
-            : undefined) || "Unknown Error",
-        content,
-        metadata: {
-          exception_type: errorData.exception_type,
-          first_seen: errorData.first_seen,
-          last_seen: errorData.last_seen,
-          volume: errorData.volume,
-          users_affected: errorData.users_affected,
-        },
-      };
-    } catch (error) {
-      throw new Error(`Failed to fetch error details for ${errorId}: ${error}`);
-    }
-  }
-
-  /**
-   * Generic resource fetcher by URL or ID
-   */
-  async fetchResourceByUrl(urlMention: UrlMention): Promise<PostHogResource> {
-    switch (urlMention.type) {
-      case "error": {
-        if (!urlMention.id) {
-          throw new Error("Error ID is required for error resources");
-        }
-        // Extract project ID from URL if available, otherwise use default team
-        let projectId: string | undefined;
-        if (urlMention.url) {
-          const projectIdMatch = urlMention.url.match(/\/project\/(\d+)\//);
-          projectId = projectIdMatch ? projectIdMatch[1] : undefined;
-        }
-        return this.fetchErrorDetails(urlMention.id, projectId);
-      }
-
-      case "experiment":
-      case "insight":
-      case "feature_flag":
-        throw new Error(
-          `Resource type '${urlMention.type}' not yet implemented`,
-        );
-
-      case "generic":
-        // Return a minimal resource for generic URLs
-        return {
-          type: "generic",
-          id: "",
-          url: urlMention.url,
-          title: "Generic Resource",
-          content: `Generic resource: ${urlMention.url}`,
-          metadata: {},
-        };
-
-      default:
-        throw new Error(`Unknown resource type: ${urlMention.type}`);
-    }
-  }
-
-  /**
-   * Format error data for agent consumption
-   */
-  private formatErrorContent(errorData: Record<string, unknown>): string {
-    const sections = [];
-
-    if (errorData.exception_type) {
-      sections.push(`**Error Type**: ${errorData.exception_type}`);
-    }
-
-    if (errorData.exception_message) {
-      sections.push(`**Message**: ${errorData.exception_message}`);
-    }
-
-    if (errorData.stack_trace) {
-      sections.push(
-        `**Stack Trace**:\n\`\`\`\n${errorData.stack_trace}\n\`\`\``,
-      );
-    }
-
-    if (errorData.volume) {
-      sections.push(`**Volume**: ${errorData.volume} occurrences`);
-    }
-
-    if (errorData.users_affected) {
-      sections.push(`**Users Affected**: ${errorData.users_affected}`);
-    }
-
-    if (errorData.first_seen && errorData.last_seen) {
-      sections.push(`**First Seen**: ${errorData.first_seen}`);
-      sections.push(`**Last Seen**: ${errorData.last_seen}`);
-    }
-
-    if (errorData.properties && Object.keys(errorData.properties).length > 0) {
-      sections.push(
-        `**Properties**: ${JSON.stringify(errorData.properties, null, 2)}`,
-      );
-    }
-
-    return sections.join("\n\n");
-  }
 }

package/src/resume.ts

@@ -0,0 +1,115 @@
+/**
+ * Resume - Restore agent state from persisted log
+ *
+ * Handles resuming a task from any point:
+ * - Fetches log via the PostHog API
+ * - Finds latest tree_snapshot event
+ * - Rebuilds conversation from log events
+ * - Restores working tree from snapshot
+ *
+ * Uses Saga pattern for atomic operations with clear success/failure tracking.
+ *
+ * The log is the single source of truth for:
+ * - Conversation history (user_message, agent_message_chunk, tool_call, tool_result)
+ * - Working tree state (tree_snapshot events)
+ * - Session metadata (device info, mode changes)
+ */
+
+import type { ContentBlock } from "@agentclientprotocol/sdk";
+import type { PostHogAPIClient } from "./posthog-api.js";
+import { ResumeSaga } from "./sagas/resume-saga.js";
+import type { DeviceInfo, TreeSnapshotEvent } from "./types.js";
+import { Logger } from "./utils/logger.js";
+
+export interface ResumeState {
+  conversation: ConversationTurn[];
+  latestSnapshot: TreeSnapshotEvent | null;
+  /** Whether the tree snapshot was successfully applied (files restored) */
+  snapshotApplied: boolean;
+  interrupted: boolean;
+  lastDevice?: DeviceInfo;
+  logEntryCount: number;
+}
+
+export interface ConversationTurn {
+  role: "user" | "assistant";
+  content: ContentBlock[];
+  toolCalls?: ToolCallInfo[];
+}
+
+export interface ToolCallInfo {
+  toolCallId: string;
+  toolName: string;
+  input: unknown;
+  result?: unknown;
+}
+
+export interface ResumeConfig {
+  taskId: string;
+  runId: string;
+  repositoryPath: string;
+  apiClient: PostHogAPIClient;
+  logger?: Logger;
+}
+
+/**
+ * Resume a task from its persisted log.
+ * Returns the rebuilt state for the agent to continue from.
+ *
+ * Uses Saga pattern internally for atomic operations.
+ * Note: snapshotApplied field indicates if files were actually restored -
+ * even if latestSnapshot is non-null, files may not have been restored if
+ * the snapshot had no archive URL or download/extraction failed.
+ */
+export async function resumeFromLog(
+  config: ResumeConfig,
+): Promise<ResumeState> {
+  const logger =
+    config.logger || new Logger({ debug: false, prefix: "[Resume]" });
+
+  logger.info("Resuming from log", {
+    taskId: config.taskId,
+    runId: config.runId,
+  });
+
+  const saga = new ResumeSaga(logger);
+
+  const result = await saga.run({
+    taskId: config.taskId,
+    runId: config.runId,
+    repositoryPath: config.repositoryPath,
+    apiClient: config.apiClient,
+    logger,
+  });
+
+  if (!result.success) {
+    logger.error("Failed to resume from log", {
+      error: result.error,
+      failedStep: result.failedStep,
+    });
+    throw new Error(
+      `Failed to resume at step '${result.failedStep}': ${result.error}`,
+    );
+  }
+
+  return {
+    conversation: result.data.conversation as ConversationTurn[],
+    latestSnapshot: result.data.latestSnapshot,
+    snapshotApplied: result.data.snapshotApplied,
+    interrupted: result.data.interrupted,
+    lastDevice: result.data.lastDevice,
+    logEntryCount: result.data.logEntryCount,
+  };
+}
+
+/**
+ * Convert resumed conversation back to API format for continuation.
+ */
+export function conversationToPromptHistory(
+  conversation: ConversationTurn[],
+): Array<{ role: "user" | "assistant"; content: ContentBlock[] }> {
+  return conversation.map((turn) => ({
+    role: turn.role,
+    content: turn.content,
+  }));
+}