@posthog/agent 1.24.0 → 1.25.0

package/src/posthog-api.ts

@@ -1,7 +1,7 @@
 import type {
-  LogEntry,
   PostHogAPIConfig,
   PostHogResource,
+  StoredEntry,
   Task,
   TaskArtifactUploadPayload,
   TaskRun,
@@ -16,14 +16,15 @@ interface PostHogApiResponse<T> {
   previous?: string | null;
 }
 
-export interface TaskRunUpdate {
-  status?: TaskRun["status"];
-  branch?: string | null;
-  current_stage?: string | null;
-  error_message?: string | null;
-  output?: Record<string, unknown> | null;
-  state?: Record<string, unknown>;
-}
+export type TaskRunUpdate = Partial<
+  Pick<
+    TaskRun,
+    "status" | "branch" | "stage" | "error_message" | "output" | "state"
+  >
+>;
+
+export type TaskCreatePayload = Pick<Task, "description"> &
+  Partial<Pick<Task, "title" | "repository" | "origin_product">>;
 
 export class PostHogAPIClient {
   private config: PostHogAPIConfig;
@@ -125,6 +126,17 @@ export class PostHogAPIClient {
     });
   }
 
+  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();
@@ -146,7 +158,13 @@ export class PostHogAPIClient {
     payload?: Partial<
       Omit<
         TaskRun,
-        "id" | "task" | "team" | "created_at" | "updated_at" | "completed_at"
+        | "id"
+        | "task"
+        | "team"
+        | "created_at"
+        | "updated_at"
+        | "completed_at"
+        | "artifacts"
       >
     >,
   ): Promise<TaskRun> {
@@ -193,7 +211,7 @@ export class PostHogAPIClient {
   async appendTaskRunLog(
     taskId: string,
     runId: string,
-    entries: LogEntry[],
+    entries: StoredEntry[],
   ): Promise<TaskRun> {
     const teamId = this.getTeamId();
     return this.apiRequest<TaskRun>(
@@ -229,9 +247,9 @@ export class PostHogAPIClient {
   /**
    * Fetch logs from S3 using presigned URL from TaskRun
    * @param taskRun - The task run containing the log_url
-   * @returns Array of log entries, or empty array if no logs available
+   * @returns Array of stored entries, or empty array if no logs available
    */
-  async fetchTaskRunLogs(taskRun: TaskRun): Promise<LogEntry[]> {
+  async fetchTaskRunLogs(taskRun: TaskRun): Promise<StoredEntry[]> {
     if (!taskRun.log_url) {
       return [];
     }
@@ -255,7 +273,7 @@ export class PostHogAPIClient {
       return content
         .trim()
         .split("\n")
-        .map((line) => JSON.parse(line) as LogEntry);
+        .map((line) => JSON.parse(line) as StoredEntry);
     } catch (error) {
       throw new Error(
         `Failed to fetch task run logs: ${error instanceof Error ? error.message : String(error)}`,
@@ -273,7 +291,7 @@ export class PostHogAPIClient {
     const teamId = projectId ? parseInt(projectId, 10) : this.getTeamId();
 
     try {
-      const errorData = await this.apiRequest<any>(
+      const errorData = await this.apiRequest<Record<string, unknown>>(
         `/api/projects/${teamId}/error_tracking/${errorId}/`,
       );
 
@@ -284,7 +302,10 @@ export class PostHogAPIClient {
         type: "error",
         id: errorId,
         url: `${this.baseUrl}/project/${teamId}/error_tracking/${errorId}`,
-        title: errorData.exception_type || "Unknown Error",
+        title:
+          (typeof errorData.exception_type === "string"
+            ? errorData.exception_type
+            : undefined) || "Unknown Error",
         content,
         metadata: {
           exception_type: errorData.exception_type,
@@ -343,7 +364,7 @@ export class PostHogAPIClient {
   /**
    * Format error data for agent consumption
    */
-  private formatErrorContent(errorData: any): string {
+  private formatErrorContent(errorData: Record<string, unknown>): string {
     const sections = [];
 
     if (errorData.exception_type) {

package/src/prompt-builder.ts

@@ -1,11 +1,17 @@
 import { promises as fs } from "node:fs";
 import { join } from "node:path";
 import type { TemplateVariables } from "./template-manager.js";
-import type { PostHogResource, Task, UrlMention } from "./types.js";
+import type {
+  PostHogResource,
+  ResourceType,
+  SupportingFile,
+  Task,
+  UrlMention,
+} from "./types.js";
 import { Logger } from "./utils/logger.js";
 
 export interface PromptBuilderDeps {
-  getTaskFiles: (taskId: string) => Promise<any[]>;
+  getTaskFiles: (taskId: string) => Promise<SupportingFile[]>;
   generatePlanTemplate: (vars: TemplateVariables) => Promise<string>;
   posthogClient?: {
     fetchResourceByUrl: (mention: UrlMention) => Promise<PostHogResource>;
@@ -81,9 +87,9 @@ export class PromptBuilder {
       const [, type, id] = match;
       mentions.push({
         url: "", // Will be reconstructed if needed
-        type: type as any,
+        type: type as ResourceType,
         id,
-        label: this.generateUrlLabel("", type as any),
+        label: this.generateUrlLabel("", type as ResourceType),
       });
       match = resourceRegex.exec(description);
     }
@@ -249,8 +255,8 @@ export class PromptBuilder {
     prompt += `<title>${task.title}</title>\n`;
     prompt += `<description>${processedDescription}</description>\n`;
 
-    if ((task as any).primary_repository) {
-      prompt += `<repository>${(task as any).primary_repository}</repository>\n`;
+    if (task.repository) {
+      prompt += `<repository>${task.repository}</repository>\n`;
     }
     prompt += "</task>\n";
 
@@ -278,7 +284,7 @@ export class PromptBuilder {
     try {
       const taskFiles = await this.getTaskFiles(task.id);
       const contextFiles = taskFiles.filter(
-        (f: any) => f.type === "context" || f.type === "reference",
+        (f: SupportingFile) => f.type === "context" || f.type === "reference",
       );
       if (contextFiles.length > 0) {
         prompt += "\n<supporting_files>\n";
@@ -312,8 +318,8 @@ export class PromptBuilder {
     prompt += `<title>${task.title}</title>\n`;
     prompt += `<description>${processedDescription}</description>\n`;
 
-    if ((task as any).primary_repository) {
-      prompt += `<repository>${(task as any).primary_repository}</repository>\n`;
+    if (task.repository) {
+      prompt += `<repository>${task.repository}</repository>\n`;
     }
     prompt += "</task>\n";
 
@@ -341,7 +347,7 @@ export class PromptBuilder {
     try {
       const taskFiles = await this.getTaskFiles(task.id);
       const contextFiles = taskFiles.filter(
-        (f: any) => f.type === "context" || f.type === "reference",
+        (f: SupportingFile) => f.type === "context" || f.type === "reference",
       );
       if (contextFiles.length > 0) {
         prompt += "\n<supporting_files>\n";
@@ -361,7 +367,7 @@ export class PromptBuilder {
       task_title: task.title,
       task_description: processedDescription,
       date: new Date().toISOString().split("T")[0],
-      repository: ((task as any).primary_repository || "") as string,
+      repository: task.repository || "",
     };
 
     const planTemplate = await this.generatePlanTemplate(templateVariables);
@@ -393,8 +399,8 @@ export class PromptBuilder {
     prompt += `<title>${task.title}</title>\n`;
     prompt += `<description>${processedDescription}</description>\n`;
 
-    if ((task as any).primary_repository) {
-      prompt += `<repository>${(task as any).primary_repository}</repository>\n`;
+    if (task.repository) {
+      prompt += `<repository>${task.repository}</repository>\n`;
     }
     prompt += "</task>\n";
 
@@ -421,8 +427,10 @@ export class PromptBuilder {
 
     try {
       const taskFiles = await this.getTaskFiles(task.id);
-      const hasPlan = taskFiles.some((f: any) => f.type === "plan");
-      const todosFile = taskFiles.find((f: any) => f.name === "todos.json");
+      const hasPlan = taskFiles.some((f: SupportingFile) => f.type === "plan");
+      const todosFile = taskFiles.find(
+        (f: SupportingFile) => f.name === "todos.json",
+      );
 
       if (taskFiles.length > 0) {
         prompt += "\n<context>\n";

package/src/schemas.ts

@@ -0,0 +1,241 @@
+import { z } from "zod";
+
+// Base event schema with timestamp
+const BaseEventSchema = z.object({
+  ts: z.number(),
+});
+
+// Streaming content events
+export const TokenEventSchema = BaseEventSchema.extend({
+  type: z.literal("token"),
+  content: z.string(),
+  contentType: z.enum(["text", "thinking", "tool_input"]).optional(),
+});
+
+export const ContentBlockStartEventSchema = BaseEventSchema.extend({
+  type: z.literal("content_block_start"),
+  index: z.number(),
+  contentType: z.enum(["text", "tool_use", "thinking"]),
+  toolName: z.string().optional(),
+  toolId: z.string().optional(),
+});
+
+export const ContentBlockStopEventSchema = BaseEventSchema.extend({
+  type: z.literal("content_block_stop"),
+  index: z.number(),
+});
+
+// Tool events
+export const ToolCallEventSchema = BaseEventSchema.extend({
+  type: z.literal("tool_call"),
+  toolName: z.string(),
+  callId: z.string(),
+  args: z.record(z.string(), z.unknown()),
+  parentToolUseId: z.string().nullable().optional(),
+  tool: z.unknown().optional(),
+  category: z.unknown().optional(),
+});
+
+export const ToolResultEventSchema = BaseEventSchema.extend({
+  type: z.literal("tool_result"),
+  toolName: z.string(),
+  callId: z.string(),
+  result: z.unknown(),
+  isError: z.boolean().optional(),
+  parentToolUseId: z.string().nullable().optional(),
+  tool: z.unknown().optional(),
+  category: z.unknown().optional(),
+});
+
+// Message lifecycle events
+export const MessageStartEventSchema = BaseEventSchema.extend({
+  type: z.literal("message_start"),
+  messageId: z.string().optional(),
+  model: z.string().optional(),
+});
+
+export const MessageDeltaEventSchema = BaseEventSchema.extend({
+  type: z.literal("message_delta"),
+  stopReason: z.string().optional(),
+  stopSequence: z.string().optional(),
+  usage: z
+    .object({
+      outputTokens: z.number(),
+    })
+    .optional(),
+});
+
+export const MessageStopEventSchema = BaseEventSchema.extend({
+  type: z.literal("message_stop"),
+});
+
+// User message events
+export const UserMessageEventSchema = BaseEventSchema.extend({
+  type: z.literal("user_message"),
+  content: z.string(),
+  isSynthetic: z.boolean().optional(),
+});
+
+// System events
+export const StatusEventSchema = BaseEventSchema.extend({
+  type: z.literal("status"),
+  phase: z.string(),
+  kind: z.string().optional(),
+  branch: z.string().optional(),
+  prUrl: z.string().optional(),
+  taskId: z.string().optional(),
+  messageId: z.string().optional(),
+  model: z.string().optional(),
+}).passthrough(); // Allow additional fields
+
+export const InitEventSchema = BaseEventSchema.extend({
+  type: z.literal("init"),
+  model: z.string(),
+  tools: z.array(z.string()),
+  permissionMode: z.string(),
+  cwd: z.string(),
+  apiKeySource: z.string(),
+  agents: z.array(z.string()).optional(),
+  slashCommands: z.array(z.string()).optional(),
+  outputStyle: z.string().optional(),
+  mcpServers: z
+    .array(z.object({ name: z.string(), status: z.string() }))
+    .optional(),
+});
+
+// Console event for log-style output
+export const ConsoleEventSchema = BaseEventSchema.extend({
+  type: z.literal("console"),
+  level: z.enum(["debug", "info", "warn", "error"]),
+  message: z.string(),
+});
+
+export const CompactBoundaryEventSchema = BaseEventSchema.extend({
+  type: z.literal("compact_boundary"),
+  trigger: z.enum(["manual", "auto"]),
+  preTokens: z.number(),
+});
+
+// Result events
+export const DoneEventSchema = BaseEventSchema.extend({
+  type: z.literal("done"),
+  result: z.string().optional(),
+  durationMs: z.number().optional(),
+  durationApiMs: z.number().optional(),
+  numTurns: z.number().optional(),
+  totalCostUsd: z.number().optional(),
+  usage: z.unknown().optional(),
+  modelUsage: z
+    .record(
+      z.string(),
+      z.object({
+        inputTokens: z.number(),
+        outputTokens: z.number(),
+        cacheReadInputTokens: z.number(),
+        cacheCreationInputTokens: z.number(),
+        webSearchRequests: z.number(),
+        costUSD: z.number(),
+        contextWindow: z.number(),
+      }),
+    )
+    .optional(),
+  permissionDenials: z
+    .array(
+      z.object({
+        tool_name: z.string(),
+        tool_use_id: z.string(),
+        tool_input: z.record(z.string(), z.unknown()),
+      }),
+    )
+    .optional(),
+});
+
+export const ErrorEventSchema = BaseEventSchema.extend({
+  type: z.literal("error"),
+  message: z.string(),
+  error: z.unknown().optional(),
+  errorType: z.string().optional(),
+  context: z.record(z.string(), z.unknown()).optional(),
+  sdkError: z.unknown().optional(),
+});
+
+// Metric and artifact events
+export const MetricEventSchema = BaseEventSchema.extend({
+  type: z.literal("metric"),
+  key: z.string(),
+  value: z.number(),
+  unit: z.string().optional(),
+});
+
+export const ArtifactEventSchema = BaseEventSchema.extend({
+  type: z.literal("artifact"),
+  kind: z.string(),
+  content: z.unknown(),
+});
+
+export const RawSDKEventSchema = BaseEventSchema.extend({
+  type: z.literal("raw_sdk_event"),
+  sdkMessage: z.unknown(),
+});
+
+export const AgentEventSchema = z.discriminatedUnion("type", [
+  TokenEventSchema,
+  ContentBlockStartEventSchema,
+  ContentBlockStopEventSchema,
+  ToolCallEventSchema,
+  ToolResultEventSchema,
+  MessageStartEventSchema,
+  MessageDeltaEventSchema,
+  MessageStopEventSchema,
+  UserMessageEventSchema,
+  StatusEventSchema,
+  InitEventSchema,
+  ConsoleEventSchema,
+  CompactBoundaryEventSchema,
+  DoneEventSchema,
+  ErrorEventSchema,
+  MetricEventSchema,
+  ArtifactEventSchema,
+  RawSDKEventSchema,
+]);
+
+export type TokenEvent = z.infer<typeof TokenEventSchema>;
+export type ContentBlockStartEvent = z.infer<
+  typeof ContentBlockStartEventSchema
+>;
+export type ContentBlockStopEvent = z.infer<typeof ContentBlockStopEventSchema>;
+export type ToolCallEvent = z.infer<typeof ToolCallEventSchema>;
+export type ToolResultEvent = z.infer<typeof ToolResultEventSchema>;
+export type MessageStartEvent = z.infer<typeof MessageStartEventSchema>;
+export type MessageDeltaEvent = z.infer<typeof MessageDeltaEventSchema>;
+export type MessageStopEvent = z.infer<typeof MessageStopEventSchema>;
+export type UserMessageEvent = z.infer<typeof UserMessageEventSchema>;
+export type StatusEvent = z.infer<typeof StatusEventSchema>;
+export type InitEvent = z.infer<typeof InitEventSchema>;
+export type ConsoleEvent = z.infer<typeof ConsoleEventSchema>;
+export type CompactBoundaryEvent = z.infer<typeof CompactBoundaryEventSchema>;
+export type DoneEvent = z.infer<typeof DoneEventSchema>;
+export type ErrorEvent = z.infer<typeof ErrorEventSchema>;
+export type MetricEvent = z.infer<typeof MetricEventSchema>;
+export type ArtifactEvent = z.infer<typeof ArtifactEventSchema>;
+export type RawSDKEvent = z.infer<typeof RawSDKEventSchema>;
+export type AgentEvent = z.infer<typeof AgentEventSchema>;
+
+/**
+ * Parse and validate an AgentEvent from unknown input.
+ * Returns the parsed event if valid, or null if invalid.
+ */
+export function parseAgentEvent(input: unknown): AgentEvent | null {
+  const result = AgentEventSchema.safeParse(input);
+  return result.success ? result.data : null;
+}
+
+/**
+ * Parse and validate multiple AgentEvents from an array of unknown inputs.
+ * Invalid entries are discarded.
+ */
+export function parseAgentEvents(inputs: unknown[]): AgentEvent[] {
+  return inputs
+    .map((input) => parseAgentEvent(input))
+    .filter((event): event is AgentEvent => event !== null);
+}