@posthog/agent 2.3.46 → 2.3.62

package/dist/types.d.ts

@@ -74,6 +74,7 @@ interface ProcessSpawnedCallback {
         sessionId?: string;
     }) => void;
     onProcessExited?: (pid: number) => void;
+    onMcpServersReady?: (serverNames: string[]) => void;
 }
 interface TaskExecutionOptions {
     repositoryPath?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/agent",
-  "version": "2.3.46",
+  "version": "2.3.62",
   "repository": "https://github.com/PostHog/code",
   "description": "TypeScript agent framework wrapping Claude Agent SDK with Git-based task execution for PostHog",
   "exports": {

package/src/adapters/claude/claude-agent.ts

@@ -55,7 +55,10 @@ import {
   handleSystemMessage,
   handleUserAssistantMessage,
 } from "./conversion/sdk-to-acp";
-import { fetchMcpToolMetadata } from "./mcp/tool-metadata";
+import {
+  fetchMcpToolMetadata,
+  getConnectedMcpServerNames,
+} from "./mcp/tool-metadata";
 import { canUseTool } from "./permissions/permission-handlers";
 import { getAvailableSlashCommands } from "./session/commands";
 import { parseMcpServers } from "./session/mcp-config";
@@ -101,6 +104,7 @@ function sanitizeTitle(text: string): string {
 export interface ClaudeAcpAgentOptions {
   onProcessSpawned?: (info: ProcessSpawnedInfo) => void;
   onProcessExited?: (pid: number) => void;
+  onMcpServersReady?: (serverNames: string[]) => void;
 }
 
 export class ClaudeAcpAgent extends BaseAcpAgent {
@@ -1020,11 +1024,17 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
    * Both populate caches used later — neither is needed to return configOptions.
    */
   private deferBackgroundFetches(q: Query): void {
+    this.logger.info("Starting background fetches (commands + MCP metadata)");
     Promise.all([
       new Promise<void>((resolve) => setTimeout(resolve, 10)).then(() =>
         this.sendAvailableCommandsUpdate(),
       ),
-      fetchMcpToolMetadata(q, this.logger),
+      fetchMcpToolMetadata(q, this.logger).then(() => {
+        const serverNames = getConnectedMcpServerNames();
+        if (serverNames.length > 0) {
+          this.options?.onMcpServersReady?.(serverNames);
+        }
+      }),
     ]).catch((err) =>
       this.logger.error("Background fetch failed", { error: err }),
     );

package/src/adapters/claude/conversion/sdk-to-acp.ts

@@ -56,6 +56,8 @@ type ChunkHandlerContext = {
   registerHooks?: boolean;
   supportsTerminalOutput?: boolean;
   cwd?: string;
+  /** Raw MCP tool result from SDKUserMessage.tool_use_result (contains content, structuredContent, _meta) */
+  mcpToolUseResult?: Record<string, unknown>;
 };
 
 export interface MessageHandlerContext {
@@ -348,7 +350,16 @@ function handleToolResultChunk(
     toolCallId: chunk.tool_use_id,
     sessionUpdate: "tool_call_update",
     status: chunk.is_error ? "failed" : "completed",
-    rawOutput: chunk.content,
+    rawOutput: ctx.mcpToolUseResult
+      ? { ...ctx.mcpToolUseResult, isError: chunk.is_error ?? false }
+      : {
+          content: Array.isArray(chunk.content)
+            ? chunk.content
+            : typeof chunk.content === "string"
+              ? [{ type: "text" as const, text: chunk.content }]
+              : [],
+          isError: chunk.is_error ?? false,
+        },
     ...toolUpdate,
   });
 
@@ -435,6 +446,7 @@ function toAcpNotifications(
   registerHooks?: boolean,
   supportsTerminalOutput?: boolean,
   cwd?: string,
+  mcpToolUseResult?: Record<string, unknown>,
 ): SessionNotification[] {
   if (typeof content === "string") {
     const update: SessionUpdate = {
@@ -461,6 +473,7 @@ function toAcpNotifications(
     registerHooks,
     supportsTerminalOutput,
     cwd,
+    mcpToolUseResult,
   };
   const output: SessionNotification[] = [];
 
@@ -829,6 +842,13 @@ export async function handleUserAssistantMessage(
       ? (message.parent_tool_use_id ?? undefined)
       : undefined;
 
+  // Pass the raw MCP tool result (contains content, structuredContent, _meta)
+  // so it can be forwarded as-is to the renderer for MCP Apps
+  const mcpToolUseResult =
+    message.type === "user" && message.tool_use_result != null
+      ? (message.tool_use_result as Record<string, unknown>)
+      : undefined;
+
   for (const notification of toAcpNotifications(
     contentToProcess as typeof content,
     message.message.role,
@@ -841,6 +861,7 @@ export async function handleUserAssistantMessage(
     context.registerHooks,
     context.supportsTerminalOutput,
     session.cwd,
+    mcpToolUseResult,
   )) {
     await client.sessionUpdate(notification);
     session.notificationHistory.push(notification);

package/src/adapters/claude/mcp/tool-metadata.ts

@@ -48,6 +48,7 @@ export async function fetchMcpToolMetadata(
       for (const tool of server.tools) {
         const toolKey = buildToolKey(server.name, tool.name);
         const readOnly = tool.annotations?.readOnly === true;
+
         mcpToolMetadataCache.set(toolKey, {
           readOnly,
           name: tool.name,
@@ -94,6 +95,15 @@ export function isMcpToolReadOnly(toolName: string): boolean {
   return metadata?.readOnly === true;
 }
 
+export function getConnectedMcpServerNames(): string[] {
+  const names = new Set<string>();
+  for (const key of mcpToolMetadataCache.keys()) {
+    const parts = key.split("__");
+    if (parts.length >= 3) names.add(parts[1]);
+  }
+  return [...names];
+}
+
 export function clearMcpToolMetadataCache(): void {
   mcpToolMetadataCache.clear();
 }

package/src/index.ts

@@ -1 +1,5 @@
-export { isMcpToolReadOnly } from "./adapters/claude/mcp/tool-metadata";
+export {
+  getMcpToolMetadata,
+  isMcpToolReadOnly,
+  type McpToolMetadata,
+} from "./adapters/claude/mcp/tool-metadata";

package/src/server/agent-server.ts

@@ -162,6 +162,12 @@ export class AgentServer {
   private questionRelayedToSlack = false;
   private detectedPrUrl: string | null = null;
   private resumeState: ResumeState | null = null;
+  // Guards against concurrent session initialization. autoInitializeSession() and
+  // the GET /events SSE handler can both call initializeSession() — the SSE connection
+  // often arrives while newSession() is still awaited (this.session is still null),
+  // causing a second session to be created and duplicate Slack messages to be sent.
+  private initializationPromise: Promise<void> | null = null;
+  private pendingEvents: Record<string, unknown>[] = [];
 
   private emitConsoleLog = (
     level: LogLevel,
@@ -264,6 +270,7 @@ export class AgentServer {
             await this.initializeSession(payload, sseController);
           } else {
             this.session.sseController = sseController;
+            this.replayPendingEvents();
           }
 
           this.sendSseEvent(sseController, {
@@ -483,6 +490,8 @@ export class AgentServer {
           `Processing user message (detectedPrUrl=${this.detectedPrUrl ?? "none"}): ${content.substring(0, 100)}...`,
         );
 
+        this.session.logWriter.resetTurnMessages(this.session.payload.run_id);
+
         const result = await this.session.clientConnection.prompt({
           sessionId: this.session.acpSessionId,
           prompt: [{ type: "text", text: content }],
@@ -501,7 +510,31 @@ export class AgentServer {
 
         this.broadcastTurnComplete(result.stopReason);
 
-        return { stopReason: result.stopReason };
+        if (result.stopReason === "end_turn") {
+          // Relay the response to Slack. For follow-ups this is the primary
+          // delivery path — the HTTP caller only handles reactions.
+          this.relayAgentResponse(this.session.payload).catch((err) =>
+            this.logger.warn("Failed to relay follow-up response", err),
+          );
+        }
+
+        // Flush logs and include the assistant's response text so callers
+        // (e.g. Slack follow-up forwarding) can extract it without racing
+        // against async log persistence to object storage.
+        let assistantMessage: string | undefined;
+        try {
+          await this.session.logWriter.flush(this.session.payload.run_id);
+          assistantMessage = this.session.logWriter.getFullAgentResponse(
+            this.session.payload.run_id,
+          );
+        } catch {
+          this.logger.warn("Failed to extract assistant message from logs");
+        }
+
+        return {
+          stopReason: result.stopReason,
+          ...(assistantMessage && { assistant_message: assistantMessage }),
+        };
       }
 
       case POSTHOG_NOTIFICATIONS.CANCEL:
@@ -530,6 +563,40 @@ export class AgentServer {
   private async initializeSession(
     payload: JwtPayload,
     sseController: SseController | null,
+  ): Promise<void> {
+    // Race condition guard: autoInitializeSession() starts first, but while it awaits
+    // newSession() (which takes ~1-2s for MCP metadata fetch), the Temporal relay connects
+    // to GET /events. That handler sees this.session === null and calls initializeSession()
+    // again, creating a duplicate session that sends the same prompt twice — resulting in
+    // duplicate Slack messages. This lock ensures the second caller waits for the first
+    // initialization to finish and reuses the session.
+    if (this.initializationPromise) {
+      this.logger.info("Waiting for in-progress initialization", {
+        runId: payload.run_id,
+      });
+      await this.initializationPromise;
+      // After waiting, just attach the SSE controller if needed
+      if (this.session && sseController) {
+        this.session.sseController = sseController;
+        this.replayPendingEvents();
+      }
+      return;
+    }
+
+    this.initializationPromise = this._doInitializeSession(
+      payload,
+      sseController,
+    );
+    try {
+      await this.initializationPromise;
+    } finally {
+      this.initializationPromise = null;
+    }
+  }
+
+  private async _doInitializeSession(
+    payload: JwtPayload,
+    sseController: SseController | null,
   ): Promise<void> {
     if (this.session) {
       await this.cleanupSession();
@@ -770,6 +837,8 @@ export class AgentServer {
         usedInitialPromptOverride: !!initialPromptOverride,
       });
 
+      this.session.logWriter.resetTurnMessages(payload.run_id);
+
       const result = await this.session.clientConnection.prompt({
         sessionId: this.session.acpSessionId,
         prompt: [{ type: "text", text: initialPrompt }],
@@ -809,8 +878,8 @@ export class AgentServer {
       const pendingUserMessage = this.getPendingUserMessage(taskRun);
 
       const sandboxContext = this.resumeState.snapshotApplied
-        ? `The sandbox environment (all files, packages, and code changes) has been fully restored from a snapshot.`
-        : `The sandbox could not be restored from a snapshot (it may have expired). You are starting with a fresh environment but have the full conversation history below.`;
+        ? `The workspace environment (all files, packages, and code changes) has been fully restored from where you left off.`
+        : `The workspace files from the previous session were not restored (the file snapshot may have expired), so you are starting with a fresh environment. Your conversation history is fully preserved below.`;
 
       let resumePrompt: string;
       if (pendingUserMessage) {
@@ -842,6 +911,8 @@ export class AgentServer {
       // Clear resume state so it's not reused
       this.resumeState = null;
 
+      this.session.logWriter.resetTurnMessages(payload.run_id);
+
       const result = await this.session.clientConnection.prompt({
         sessionId: this.session.acpSessionId,
         prompt: [{ type: "text", text: resumePrompt }],
@@ -852,6 +923,10 @@ export class AgentServer {
       });
 
       this.broadcastTurnComplete(result.stopReason);
+
+      if (result.stopReason === "end_turn") {
+        await this.relayAgentResponse(payload);
+      }
     } catch (error) {
       this.logger.error("Failed to send resume message", error);
       if (this.session) {
@@ -992,6 +1067,27 @@ Important:
 `;
     }
 
+    if (!this.config.repositoryPath) {
+      return `
+# Cloud Task Execution — No Repository Mode
+
+You are a helpful assistant with access to PostHog via MCP tools. You can help with both code tasks and data/analytics questions.
+
+When the user asks about analytics, data, metrics, events, funnels, dashboards, feature flags, experiments, or anything PostHog-related:
+- Use your PostHog MCP tools to query data, search insights, and provide real answers
+- Do NOT tell the user to check an external analytics platform — you ARE the analytics platform
+- Use tools like insight-query, query-run, event-definitions-list, and others to answer questions directly
+
+When the user asks for code changes or software engineering tasks:
+- Let them know you can help but don't have a repository connected for this session
+- Offer to write code snippets, scripts, or provide guidance
+
+Important:
+- Do NOT create branches, commits, or pull requests in this mode.
+- Prefer using MCP tools to answer questions with real data over giving generic advice.
+`;
+    }
+
     return `
 # Cloud Task Execution
 
@@ -1124,6 +1220,12 @@ Important:
           },
         };
       },
+      extNotification: async (
+        method: string,
+        params: Record<string, unknown>,
+      ) => {
+        this.logger.debug("Extension notification", { method, params });
+      },
       sessionUpdate: async (params: {
         sessionId: string;
         update?: Record<string, unknown>;
@@ -1176,7 +1278,7 @@ Important:
       });
     }
 
-    const message = this.session.logWriter.getLastAgentMessage(payload.run_id);
+    const message = this.session.logWriter.getFullAgentResponse(payload.run_id);
     if (!message) {
       this.logger.warn("No agent message found for Slack relay", {
         taskId: payload.task_id,
@@ -1385,6 +1487,7 @@ Important:
       this.session.sseController.close();
     }
 
+    this.pendingEvents = [];
     this.session = null;
   }
 
@@ -1444,6 +1547,18 @@ Important:
   private broadcastEvent(event: Record<string, unknown>): void {
     if (this.session?.sseController) {
       this.sendSseEvent(this.session.sseController, event);
+    } else if (this.session) {
+      // Buffer events during initialization (sseController not yet attached)
+      this.pendingEvents.push(event);
+    }
+  }
+
+  private replayPendingEvents(): void {
+    if (!this.session?.sseController || this.pendingEvents.length === 0) return;
+    const events = this.pendingEvents;
+    this.pendingEvents = [];
+    for (const event of events) {
+      this.sendSseEvent(this.session.sseController, event);
     }
   }
 

package/src/server/question-relay.test.ts

@@ -248,7 +248,7 @@ describe("Question relay", () => {
         payload: TEST_PAYLOAD,
         logWriter: {
           flush: vi.fn().mockResolvedValue(undefined),
-          getLastAgentMessage: vi.fn().mockReturnValue("agent response"),
+          getFullAgentResponse: vi.fn().mockReturnValue("agent response"),
           isRegistered: vi.fn().mockReturnValue(true),
         },
       };
@@ -269,7 +269,7 @@ describe("Question relay", () => {
         payload: TEST_PAYLOAD,
         logWriter: {
           flush: vi.fn().mockResolvedValue(undefined),
-          getLastAgentMessage: vi.fn().mockReturnValue("agent response"),
+          getFullAgentResponse: vi.fn().mockReturnValue("agent response"),
           isRegistered: vi.fn().mockReturnValue(true),
         },
       };
@@ -293,7 +293,7 @@ describe("Question relay", () => {
         payload: TEST_PAYLOAD,
         logWriter: {
           flush: vi.fn().mockResolvedValue(undefined),
-          getLastAgentMessage: vi.fn().mockReturnValue(null),
+          getFullAgentResponse: vi.fn().mockReturnValue(null),
           isRegistered: vi.fn().mockReturnValue(true),
         },
       };
@@ -323,6 +323,13 @@ describe("Question relay", () => {
         payload: TEST_PAYLOAD,
         acpSessionId: "acp-session",
         clientConnection: { prompt: promptSpy },
+        logWriter: {
+          flushAll: vi.fn().mockResolvedValue(undefined),
+          getFullAgentResponse: vi.fn().mockReturnValue(null),
+          resetTurnMessages: vi.fn(),
+          flush: vi.fn().mockResolvedValue(undefined),
+          isRegistered: vi.fn().mockReturnValue(true),
+        },
       };
 
       await server.sendInitialTaskMessage(TEST_PAYLOAD);
@@ -350,6 +357,13 @@ describe("Question relay", () => {
         payload: TEST_PAYLOAD,
         acpSessionId: "acp-session",
         clientConnection: { prompt: promptSpy },
+        logWriter: {
+          flushAll: vi.fn().mockResolvedValue(undefined),
+          getFullAgentResponse: vi.fn().mockReturnValue(null),
+          resetTurnMessages: vi.fn(),
+          flush: vi.fn().mockResolvedValue(undefined),
+          isRegistered: vi.fn().mockReturnValue(true),
+        },
       };
 
       await server.sendInitialTaskMessage(TEST_PAYLOAD);

package/src/session-log-writer.ts

@@ -24,6 +24,7 @@ interface SessionState {
   context: SessionContext;
   chunkBuffer?: ChunkBuffer;
   lastAgentMessage?: string;
+  currentTurnMessages: string[];
 }
 
 export class SessionLogWriter {
@@ -69,7 +70,7 @@ export class SessionLogWriter {
       taskId: context.taskId,
       runId: context.runId,
     });
-    this.sessions.set(sessionId, { context });
+    this.sessions.set(sessionId, { context, currentTurnMessages: [] });
 
     this.lastFlushAttemptTime.set(sessionId, Date.now());
 
@@ -127,6 +128,7 @@ export class SessionLogWriter {
       const nonChunkAgentText = this.extractAgentMessageText(message);
       if (nonChunkAgentText) {
         session.lastAgentMessage = nonChunkAgentText;
+        session.currentTurnMessages.push(nonChunkAgentText);
       }
 
       const entry: StoredNotification = {
@@ -240,6 +242,7 @@ export class SessionLogWriter {
     const { text, firstTimestamp } = session.chunkBuffer;
     session.chunkBuffer = undefined;
     session.lastAgentMessage = text;
+    session.currentTurnMessages.push(text);
 
     const entry: StoredNotification = {
       type: "notification",
@@ -270,6 +273,19 @@ export class SessionLogWriter {
     return this.sessions.get(sessionId)?.lastAgentMessage;
   }
 
+  getFullAgentResponse(sessionId: string): string | undefined {
+    const session = this.sessions.get(sessionId);
+    if (!session || session.currentTurnMessages.length === 0) return undefined;
+    return session.currentTurnMessages.join("\n\n");
+  }
+
+  resetTurnMessages(sessionId: string): void {
+    const session = this.sessions.get(sessionId);
+    if (session) {
+      session.currentTurnMessages = [];
+    }
+  }
+
   private extractAgentMessageText(
     message: Record<string, unknown>,
   ): string | null {

package/src/types.ts

@@ -103,6 +103,7 @@ export interface ProcessSpawnedCallback {
     sessionId?: string;
   }) => void;
   onProcessExited?: (pid: number) => void;
+  onMcpServersReady?: (serverNames: string[]) => void;
 }
 
 export interface TaskExecutionOptions {