@posthog/agent 1.24.0 → 1.25.0

package/src/utils/logger.ts

@@ -1,5 +1,7 @@
+import type { LogLevel as LogLevelType, OnLogCallback } from "../types.js";
+
 /**
- * Simple logger utility with configurable debug mode
+ * Simple logger utility with configurable debug mode and external log forwarding
  */
 export enum LogLevel {
   ERROR = 0,
@@ -11,28 +13,38 @@ export enum LogLevel {
 export interface LoggerConfig {
   debug?: boolean;
   prefix?: string;
+  scope?: string;
+  onLog?: OnLogCallback;
 }
 
 export class Logger {
   private debugEnabled: boolean;
   private prefix: string;
+  private scope: string;
+  private onLog?: OnLogCallback;
 
   constructor(config: LoggerConfig = {}) {
     this.debugEnabled = config.debug ?? false;
     this.prefix = config.prefix ?? "[PostHog Agent]";
+    this.scope = config.scope ?? "agent";
+    this.onLog = config.onLog;
   }
 
   setDebug(enabled: boolean) {
     this.debugEnabled = enabled;
   }
 
+  setOnLog(onLog: OnLogCallback | undefined) {
+    this.onLog = onLog;
+  }
+
   private formatMessage(
     level: string,
     message: string,
     data?: unknown,
   ): string {
     const timestamp = new Date().toISOString();
-    const base = `${timestamp} ${this.prefix} ${level} ${message}`;
+    const base = `${timestamp} ${this.prefix} [${level}] ${message}`;
 
     if (data !== undefined) {
       return `${base} ${JSON.stringify(data, null, 2)}`;
@@ -41,45 +53,58 @@ export class Logger {
     return base;
   }
 
-  error(message: string, error?: Error | unknown) {
-    // Always log errors
-    if (error instanceof Error) {
-      console.error(
-        this.formatMessage("[ERROR]", message, {
-          message: error.message,
-          stack: error.stack,
-        }),
-      );
-    } else {
-      console.error(this.formatMessage("[ERROR]", message, error));
+  private emitLog(level: LogLevelType, message: string, data?: unknown) {
+    if (this.onLog) {
+      this.onLog(level, this.scope, message, data);
+      return;
+    }
+
+    const shouldLog = this.debugEnabled || level === "error";
+
+    if (shouldLog) {
+      console[level](this.formatMessage(level.toLowerCase(), message, data));
     }
   }
 
+  error(message: string, error?: Error | unknown) {
+    const data =
+      error instanceof Error
+        ? { message: error.message, stack: error.stack }
+        : error;
+
+    this.emitLog("error", message, data);
+  }
+
   warn(message: string, data?: unknown) {
-    if (this.debugEnabled) {
-      console.warn(this.formatMessage("[WARN]", message, data));
-    }
+    this.emitLog("warn", message, data);
   }
 
   info(message: string, data?: unknown) {
-    if (this.debugEnabled) {
-      console.log(this.formatMessage("[INFO]", message, data));
-    }
+    this.emitLog("info", message, data);
   }
 
   debug(message: string, data?: unknown) {
-    if (this.debugEnabled) {
-      console.log(this.formatMessage("[DEBUG]", message, data));
+    this.emitLog("debug", message, data);
+  }
+
+  log(level: LogLevelType, message: string, data?: unknown, scope?: string) {
+    const originalScope = this.scope;
+    if (scope) {
+      this.scope = scope;
     }
+    this.emitLog(level, message, data);
+    this.scope = originalScope;
   }
 
   /**
-   * Create a child logger with additional prefix
+   * Create a child logger with additional prefix and scope
    */
   child(childPrefix: string): Logger {
     return new Logger({
       debug: this.debugEnabled,
       prefix: `${this.prefix} [${childPrefix}]`,
+      scope: `${this.scope}:${childPrefix}`,
+      onLog: this.onLog,
     });
   }
 }

package/src/utils/tapped-stream.ts

@@ -0,0 +1,60 @@
+import type { Logger } from "./logger.js";
+
+type MessageCallback = (line: string) => void;
+
+export interface TappedStreamOptions {
+  onMessage: MessageCallback;
+  logger?: Logger;
+}
+
+/**
+ * Creates a WritableStream wrapper that taps all newline-delimited messages,
+ * forwarding each complete line for persistence.
+ *
+ * This aligns with ACP's transport model - all messages flow through
+ * newline-delimited JSON-RPC streams, so we intercept at the transport layer
+ * and persist everything.
+ */
+export function createTappedWritableStream(
+  underlying: WritableStream<Uint8Array>,
+  options: TappedStreamOptions,
+): WritableStream<Uint8Array> {
+  const { onMessage, logger } = options;
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let _messageCount = 0;
+
+  return new WritableStream({
+    async write(chunk: Uint8Array) {
+      // Decode and buffer
+      buffer += decoder.decode(chunk, { stream: true });
+
+      // Process complete lines (newline-delimited)
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        _messageCount++;
+
+        onMessage(line);
+      }
+
+      // Forward to underlying stream
+      const writer = underlying.getWriter();
+      await writer.write(chunk);
+      writer.releaseLock();
+    },
+    async close() {
+      const writer = underlying.getWriter();
+      await writer.close();
+      writer.releaseLock();
+    },
+    async abort(reason: unknown) {
+      logger?.warn("Tapped stream aborted", { reason });
+      const writer = underlying.getWriter();
+      await writer.abort(reason);
+      writer.releaseLock();
+    },
+  });
+}

package/src/workflow/steps/build.ts

@@ -1,4 +1,5 @@
 import { query } from "@anthropic-ai/claude-agent-sdk";
+import { POSTHOG_NOTIFICATIONS } from "../../acp-extensions.js";
 import { EXECUTION_SYSTEM_PROMPT } from "../../agents/execution.js";
 import { TodoManager } from "../../todo-manager.js";
 import { PermissionMode } from "../../types.js";
@@ -11,10 +12,10 @@ export const buildStep: WorkflowStepRunner = async ({ step, context }) => {
     options,
     logger,
     promptBuilder,
-    adapter,
+    sessionId,
     mcpServers,
     gitManager,
-    emitEvent,
+    sendNotification,
   } = context;
 
   const stepLogger = logger.child("BuildStep");
@@ -33,7 +34,10 @@ export const buildStep: WorkflowStepRunner = async ({ step, context }) => {
   }
 
   stepLogger.info("Starting build phase", { taskId: task.id });
-  emitEvent(adapter.createStatusEvent("phase_start", { phase: "build" }));
+  await sendNotification(POSTHOG_NOTIFICATIONS.PHASE_START, {
+    sessionId,
+    phase: "build",
+  });
 
   const executionPrompt = await promptBuilder.buildExecutionPrompt(task, cwd);
   const fullPrompt = `${EXECUTION_SYSTEM_PROMPT}\n\n${executionPrompt}`;
@@ -89,18 +93,16 @@ export const buildStep: WorkflowStepRunner = async ({ step, context }) => {
 
   try {
     for await (const message of response) {
-      emitEvent(adapter.createRawSDKEvent(message));
-      const transformedEvents = adapter.transform(message);
-      for (const event of transformedEvents) {
-        emitEvent(event);
-      }
-
       const todoList = await todoManager.checkAndPersistFromMessage(
         message,
         task.id,
       );
       if (todoList) {
-        emitEvent(adapter.createArtifactEvent("todos", todoList));
+        await sendNotification(POSTHOG_NOTIFICATIONS.ARTIFACT, {
+          sessionId,
+          kind: "todos",
+          content: todoList,
+        });
       }
     }
   } catch (error) {
@@ -125,6 +127,9 @@ export const buildStep: WorkflowStepRunner = async ({ step, context }) => {
     });
   }
 
-  emitEvent(adapter.createStatusEvent("phase_complete", { phase: "build" }));
+  await sendNotification(POSTHOG_NOTIFICATIONS.PHASE_COMPLETE, {
+    sessionId,
+    phase: "build",
+  });
   return { status: "completed" };
 };

package/src/workflow/steps/finalize.ts

@@ -6,20 +6,13 @@ import { finalizeStepGitActions } from "../utils.js";
 const MAX_SNIPPET_LENGTH = 1200;
 
 export const finalizeStep: WorkflowStepRunner = async ({ step, context }) => {
-  const {
-    task,
-    logger,
-    fileManager,
-    gitManager,
-    posthogAPI,
-    progressReporter,
-  } = context;
+  const { task, logger, fileManager, gitManager, posthogAPI, runId } = context;
 
   const stepLogger = logger.child("FinalizeStep");
   const artifacts = await fileManager.collectTaskArtifacts(task.id);
   let uploadedArtifacts: TaskRunArtifact[] | undefined;
 
-  if (artifacts.length && posthogAPI && progressReporter.runId) {
+  if (artifacts.length && posthogAPI && runId) {
     try {
       const payload = artifacts.map((artifact) => ({
         name: artifact.name,
@@ -29,7 +22,7 @@ export const finalizeStep: WorkflowStepRunner = async ({ step, context }) => {
       }));
       uploadedArtifacts = await posthogAPI.uploadTaskArtifacts(
         task.id,
-        progressReporter.runId,
+        runId,
         payload,
       );
       stepLogger.info("Uploaded task artifacts to PostHog", {
@@ -46,7 +39,7 @@ export const finalizeStep: WorkflowStepRunner = async ({ step, context }) => {
     stepLogger.debug("Skipping artifact upload", {
       hasArtifacts: artifacts.length > 0,
       hasPostHogApi: Boolean(posthogAPI),
-      runId: progressReporter.runId,
+      runId,
     });
   }
 

package/src/workflow/steps/plan.ts

@@ -1,4 +1,5 @@
 import { query } from "@anthropic-ai/claude-agent-sdk";
+import { POSTHOG_NOTIFICATIONS } from "../../acp-extensions.js";
 import { PLANNING_SYSTEM_PROMPT } from "../../agents/planning.js";
 import { TodoManager } from "../../todo-manager.js";
 import type { WorkflowStepRunner } from "../types.js";
@@ -14,9 +15,9 @@ export const planStep: WorkflowStepRunner = async ({ step, context }) => {
     fileManager,
     gitManager,
     promptBuilder,
-    adapter,
+    sessionId,
     mcpServers,
-    emitEvent,
+    sendNotification,
   } = context;
 
   const stepLogger = logger.child("PlanStep");
@@ -32,16 +33,18 @@ export const planStep: WorkflowStepRunner = async ({ step, context }) => {
     stepLogger.info("Waiting for answered research questions", {
       taskId: task.id,
     });
-    emitEvent(
-      adapter.createStatusEvent("phase_complete", {
-        phase: "research_questions",
-      }),
-    );
+    await sendNotification(POSTHOG_NOTIFICATIONS.PHASE_COMPLETE, {
+      sessionId,
+      phase: "research_questions",
+    });
     return { status: "skipped", halt: true };
   }
 
   stepLogger.info("Starting planning phase", { taskId: task.id });
-  emitEvent(adapter.createStatusEvent("phase_start", { phase: "planning" }));
+  await sendNotification(POSTHOG_NOTIFICATIONS.PHASE_START, {
+    sessionId,
+    phase: "planning",
+  });
   let researchContext = "";
   if (researchData) {
     researchContext += `## Research Context\n\n${researchData.context}\n\n`;
@@ -112,18 +115,16 @@ export const planStep: WorkflowStepRunner = async ({ step, context }) => {
   let planContent = "";
   try {
     for await (const message of response) {
-      emitEvent(adapter.createRawSDKEvent(message));
-      const transformedEvents = adapter.transform(message);
-      for (const event of transformedEvents) {
-        emitEvent(event);
-      }
-
       const todoList = await todoManager.checkAndPersistFromMessage(
         message,
         task.id,
       );
       if (todoList) {
-        emitEvent(adapter.createArtifactEvent("todos", todoList));
+        await sendNotification(POSTHOG_NOTIFICATIONS.ARTIFACT, {
+          sessionId,
+          kind: "todos",
+          content: todoList,
+        });
       }
 
       // Extract text content for plan
@@ -151,12 +152,16 @@ export const planStep: WorkflowStepRunner = async ({ step, context }) => {
   });
 
   if (!isCloudMode) {
-    emitEvent(
-      adapter.createStatusEvent("phase_complete", { phase: "planning" }),
-    );
+    await sendNotification(POSTHOG_NOTIFICATIONS.PHASE_COMPLETE, {
+      sessionId,
+      phase: "planning",
+    });
     return { status: "completed", halt: true };
   }
 
-  emitEvent(adapter.createStatusEvent("phase_complete", { phase: "planning" }));
+  await sendNotification(POSTHOG_NOTIFICATIONS.PHASE_COMPLETE, {
+    sessionId,
+    phase: "planning",
+  });
   return { status: "completed" };
 };

package/src/workflow/steps/research.ts

@@ -1,4 +1,5 @@
 import { query } from "@anthropic-ai/claude-agent-sdk";
+import { POSTHOG_NOTIFICATIONS } from "../../acp-extensions.js";
 import { RESEARCH_SYSTEM_PROMPT } from "../../agents/research.js";
 import type { ResearchEvaluation } from "../../types.js";
 import type { WorkflowStepRunner } from "../types.js";
@@ -14,9 +15,9 @@ export const researchStep: WorkflowStepRunner = async ({ step, context }) => {
     fileManager,
     gitManager,
     promptBuilder,
-    adapter,
+    sessionId,
     mcpServers,
-    emitEvent,
+    sendNotification,
   } = context;
 
   const stepLogger = logger.child("ResearchStep");
@@ -36,18 +37,18 @@ export const researchStep: WorkflowStepRunner = async ({ step, context }) => {
         questionCount: existingResearch.questions.length,
       });
 
-      emitEvent({
-        type: "artifact",
-        ts: Date.now(),
+      await sendNotification(POSTHOG_NOTIFICATIONS.ARTIFACT, {
+        sessionId,
         kind: "research_questions",
         content: existingResearch.questions,
       });
 
       // In local mode, halt to allow user to answer
       if (!isCloudMode) {
-        emitEvent(
-          adapter.createStatusEvent("phase_complete", { phase: "research" }),
-        );
+        await sendNotification(POSTHOG_NOTIFICATIONS.PHASE_COMPLETE, {
+          sessionId,
+          phase: "research",
+        });
         return { status: "skipped", halt: true };
       }
     }
@@ -56,7 +57,10 @@ export const researchStep: WorkflowStepRunner = async ({ step, context }) => {
   }
 
   stepLogger.info("Starting research phase", { taskId: task.id });
-  emitEvent(adapter.createStatusEvent("phase_start", { phase: "research" }));
+  await sendNotification(POSTHOG_NOTIFICATIONS.PHASE_START, {
+    sessionId,
+    phase: "research",
+  });
 
   const researchPrompt = await promptBuilder.buildResearchPrompt(task, cwd);
   const fullPrompt = `${RESEARCH_SYSTEM_PROMPT}\n\n${researchPrompt}`;
@@ -89,11 +93,7 @@ export const researchStep: WorkflowStepRunner = async ({ step, context }) => {
   let jsonContent = "";
   try {
     for await (const message of response) {
-      emitEvent(adapter.createRawSDKEvent(message));
-      const transformedEvents = adapter.transform(message);
-      for (const event of transformedEvents) {
-        emitEvent(event);
-      }
+      // Extract text content from assistant messages
       if (message.type === "assistant" && message.message?.content) {
         for (const c of message.message.content) {
           if (c.type === "text" && c.text) {
@@ -109,9 +109,8 @@ export const researchStep: WorkflowStepRunner = async ({ step, context }) => {
 
   if (!jsonContent.trim()) {
     stepLogger.error("No JSON output from research agent", { taskId: task.id });
-    emitEvent({
-      type: "error",
-      ts: Date.now(),
+    await sendNotification(POSTHOG_NOTIFICATIONS.ERROR, {
+      sessionId,
       message: "Research agent returned no output",
     });
     return { status: "completed", halt: true };
@@ -137,9 +136,8 @@ export const researchStep: WorkflowStepRunner = async ({ step, context }) => {
       error: error instanceof Error ? error.message : String(error),
       content: jsonContent.substring(0, 500),
     });
-    emitEvent({
-      type: "error",
-      ts: Date.now(),
+    await sendNotification(POSTHOG_NOTIFICATIONS.ERROR, {
+      sessionId,
       message: `Failed to parse research JSON: ${
         error instanceof Error ? error.message : String(error)
       }`,
@@ -161,9 +159,8 @@ export const researchStep: WorkflowStepRunner = async ({ step, context }) => {
     hasQuestions: !!evaluation.questions,
   });
 
-  emitEvent({
-    type: "artifact",
-    ts: Date.now(),
+  await sendNotification(POSTHOG_NOTIFICATIONS.ARTIFACT, {
+    sessionId,
     kind: "research_evaluation",
     content: evaluation,
   });
@@ -185,9 +182,8 @@ export const researchStep: WorkflowStepRunner = async ({ step, context }) => {
       questionCount: evaluation.questions.length,
     });
 
-    emitEvent({
-      type: "artifact",
-      ts: Date.now(),
+    await sendNotification(POSTHOG_NOTIFICATIONS.ARTIFACT, {
+      sessionId,
       kind: "research_questions",
       content: evaluation.questions,
     });
@@ -200,9 +196,10 @@ export const researchStep: WorkflowStepRunner = async ({ step, context }) => {
 
   // In local mode, always halt after research for user review
   if (!isCloudMode) {
-    emitEvent(
-      adapter.createStatusEvent("phase_complete", { phase: "research" }),
-    );
+    await sendNotification(POSTHOG_NOTIFICATIONS.PHASE_COMPLETE, {
+      sessionId,
+      phase: "research",
+    });
     return { status: "completed", halt: true };
   }
 
@@ -210,13 +207,17 @@ export const researchStep: WorkflowStepRunner = async ({ step, context }) => {
   const researchData = await fileManager.readResearch(task.id);
   if (researchData?.questions && !researchData.answered) {
     // Questions need answering - halt for user input in cloud mode too
-    emitEvent(
-      adapter.createStatusEvent("phase_complete", { phase: "research" }),
-    );
+    await sendNotification(POSTHOG_NOTIFICATIONS.PHASE_COMPLETE, {
+      sessionId,
+      phase: "research",
+    });
     return { status: "completed", halt: true };
   }
 
   // No questions or questions already answered - proceed to planning
-  emitEvent(adapter.createStatusEvent("phase_complete", { phase: "research" }));
+  await sendNotification(POSTHOG_NOTIFICATIONS.PHASE_COMPLETE, {
+    sessionId,
+    phase: "research",
+  });
   return { status: "completed" };
 };

package/src/workflow/types.ts

@@ -1,15 +1,24 @@
-import type { ProviderAdapter } from "../adapters/types.js";
+import type { AgentSideConnection } from "@agentclientprotocol/sdk";
 import type { PostHogFileManager } from "../file-manager.js";
 import type { GitManager } from "../git-manager.js";
 import type { PostHogAPIClient } from "../posthog-api.js";
 import type { PromptBuilder } from "../prompt-builder.js";
-import type { TaskProgressReporter } from "../task-progress-reporter.js";
 import type { PermissionMode, Task, TaskExecutionOptions } from "../types.js";
 import type { Logger } from "../utils/logger.js";
 
+/**
+ * Function type for sending custom PostHog notifications via ACP extNotification.
+ * Used by workflow steps to emit artifacts, phase updates, etc.
+ */
+export type SendNotification = (
+  method: string,
+  params: Record<string, unknown>,
+) => Promise<void>;
+
 export interface WorkflowRuntime {
   task: Task;
   taskSlug: string;
+  runId: string;
   cwd: string;
   isCloudMode: boolean;
   options: TaskExecutionOptions;
@@ -17,11 +26,11 @@ export interface WorkflowRuntime {
   fileManager: PostHogFileManager;
   gitManager: GitManager;
   promptBuilder: PromptBuilder;
-  progressReporter: TaskProgressReporter;
-  adapter: ProviderAdapter;
+  connection: AgentSideConnection;
+  sessionId: string;
   mcpServers?: Record<string, unknown>;
   posthogAPI?: PostHogAPIClient;
-  emitEvent: (event: unknown) => void;
+  sendNotification: SendNotification;
   stepResults: Record<string, unknown>;
 }