feat(phai): add refresh_session ACP method for sandboxes (#1717)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: skoob13

packages/agent/src/acp-extensions.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+import {
+  isMethod,
+  isNotification,
+  POSTHOG_METHODS,
+  POSTHOG_NOTIFICATIONS,
+} from "./acp-extensions";
+
+describe("isNotification", () => {
+  it("matches the exact notification name", () => {
+    expect(
+      isNotification(
+        POSTHOG_NOTIFICATIONS.TURN_COMPLETE,
+        POSTHOG_NOTIFICATIONS.TURN_COMPLETE,
+      ),
+    ).toBe(true);
+  });
+
+  it("matches the double-underscore prefix variant", () => {
+    expect(
+      isNotification(
+        `_${POSTHOG_NOTIFICATIONS.TURN_COMPLETE}`,
+        POSTHOG_NOTIFICATIONS.TURN_COMPLETE,
+      ),
+    ).toBe(true);
+  });
+
+  it("returns false for a different notification", () => {
+    expect(
+      isNotification(
+        POSTHOG_NOTIFICATIONS.USAGE_UPDATE,
+        POSTHOG_NOTIFICATIONS.TURN_COMPLETE,
+      ),
+    ).toBe(false);
+  });
+
+  it("returns false for undefined", () => {
+    expect(isNotification(undefined, POSTHOG_NOTIFICATIONS.TURN_COMPLETE)).toBe(
+      false,
+    );
+  });
+});
+
+describe("isMethod", () => {
+  it("matches the exact method name", () => {
+    expect(
+      isMethod(
+        POSTHOG_METHODS.REFRESH_SESSION,
+        POSTHOG_METHODS.REFRESH_SESSION,
+      ),
+    ).toBe(true);
+  });
+
+  it("matches the double-underscore prefix variant", () => {
+    expect(
+      isMethod(
+        `_${POSTHOG_METHODS.REFRESH_SESSION}`,
+        POSTHOG_METHODS.REFRESH_SESSION,
+      ),
+    ).toBe(true);
+  });
+
+  it("returns false for unrelated method strings", () => {
+    expect(isMethod("session/prompt", POSTHOG_METHODS.REFRESH_SESSION)).toBe(
+      false,
+    );
+  });
+
+  it("returns false for undefined", () => {
+    expect(isMethod(undefined, POSTHOG_METHODS.REFRESH_SESSION)).toBe(false);
+  });
+});

packages/agent/src/acp-extensions.ts

@@ -68,17 +68,48 @@ export const POSTHOG_NOTIFICATIONS = {
   PERMISSION_RESPONSE: "_posthog/permission_response",
 } as const;
 
-type NotificationMethod =
+/**
+ * Custom request methods for PostHog-specific operations that need a response
+ * (request/response, not fire-and-forget). Used with
+ * ClientSideConnection.extMethod() on the sender and Agent.extMethod() on the
+ * receiver.
+ */
+export const POSTHOG_METHODS = {
+  /**
+   * Client requests a session refresh between turns. Payload may include
+   * `mcpServers` to trigger a resume-with-new-options reinit; future fields
+   * can extend this without adding new methods. Returns once the refresh has
+   * completed so the caller can safely send the next prompt.
+   */
+  REFRESH_SESSION: "_posthog/refresh_session",
+} as const;
+
+type PosthogNotification =
   (typeof POSTHOG_NOTIFICATIONS)[keyof typeof POSTHOG_NOTIFICATIONS];
 
+type PosthogMethod = (typeof POSTHOG_METHODS)[keyof typeof POSTHOG_METHODS];
+
 /**
- * Check if an ACP method matches a PostHog notification, handling the
- * possible `__posthog/` double-prefix from extNotification().
+ * Does `method` match `expected`? Shared by notification and method matchers.
+ * Handles the `__posthog/` double-prefix that extNotification() can produce.
  */
+function matchesExt(method: string | undefined, expected: string): boolean {
+  if (!method) return false;
+  return method === expected || method === `_${expected}`;
+}
+
+/** Dispatcher check for incoming `extNotification` calls on the agent side. */
 export function isNotification(
   method: string | undefined,
-  notification: NotificationMethod,
+  expected: PosthogNotification,
 ): boolean {
-  if (!method) return false;
-  return method === notification || method === `_${notification}`;
+  return matchesExt(method, expected);
+}
+
+/** Dispatcher check for incoming `extMethod` calls on the agent side. */
+export function isMethod(
+  method: string | undefined,
+  expected: PosthogMethod,
+): boolean {
+  return matchesExt(method, expected);
 }