@posthog/agent 2.3.316 → 2.3.341

package/src/adapters/codex/codex-client.test.ts

@@ -0,0 +1,112 @@
+import type {
+  AgentSideConnection,
+  ReadTextFileRequest,
+  ReadTextFileResponse,
+} from "@agentclientprotocol/sdk";
+import { describe, expect, test, vi } from "vitest";
+import type { FileEnrichmentDeps } from "../../enrichment/file-enricher";
+import { Logger } from "../../utils/logger";
+
+const enrichFileMock = vi.hoisted(() => vi.fn());
+vi.mock("../../enrichment/file-enricher", () => ({
+  enrichFileForAgent: enrichFileMock,
+}));
+
+import { createCodexClient } from "./codex-client";
+import { createSessionState } from "./session-state";
+
+function makeUpstream(response: ReadTextFileResponse): AgentSideConnection & {
+  readTextFile: ReturnType<typeof vi.fn>;
+} {
+  const mock = {
+    readTextFile: vi.fn(async (_: ReadTextFileRequest) => response),
+    writeTextFile: vi.fn(),
+    requestPermission: vi.fn(),
+    sessionUpdate: vi.fn(),
+    createTerminal: vi.fn(),
+    terminalOutput: vi.fn(),
+    releaseTerminal: vi.fn(),
+    waitForTerminalExit: vi.fn(),
+    killTerminal: vi.fn(),
+    extMethod: vi.fn(),
+    extNotification: vi.fn(),
+  };
+  return mock as unknown as AgentSideConnection & {
+    readTextFile: ReturnType<typeof vi.fn>;
+  };
+}
+
+describe("createCodexClient readTextFile", () => {
+  const logger = new Logger({ debug: false, prefix: "[test]" });
+  const sessionState = createSessionState("", "/tmp");
+
+  test("returns upstream response unchanged when enrichmentDeps is absent", async () => {
+    enrichFileMock.mockReset();
+    const upstream = makeUpstream({ content: "const x = 1;" });
+    const client = createCodexClient(upstream, logger, sessionState);
+
+    const result = await client.readTextFile?.({
+      sessionId: "s",
+      path: "/tmp/a.ts",
+    });
+    expect(result?.content).toBe("const x = 1;");
+    expect(enrichFileMock).not.toHaveBeenCalled();
+  });
+
+  test("returns enriched content when helper returns a string", async () => {
+    enrichFileMock.mockReset();
+    enrichFileMock.mockResolvedValueOnce("const x = 1; // [PostHog] Flag ...");
+
+    const upstream = makeUpstream({ content: "const x = 1;" });
+    const deps = {} as FileEnrichmentDeps;
+    const client = createCodexClient(upstream, logger, sessionState, {
+      enrichmentDeps: deps,
+    });
+
+    const result = await client.readTextFile?.({
+      sessionId: "s",
+      path: "/tmp/a.ts",
+    });
+    expect(result?.content).toBe("const x = 1; // [PostHog] Flag ...");
+    expect(enrichFileMock).toHaveBeenCalledWith(
+      deps,
+      "/tmp/a.ts",
+      "const x = 1;",
+    );
+  });
+
+  test("falls back to upstream response when helper returns null", async () => {
+    enrichFileMock.mockReset();
+    enrichFileMock.mockResolvedValueOnce(null);
+
+    const upstream = makeUpstream({ content: "no posthog here" });
+    const client = createCodexClient(upstream, logger, sessionState, {
+      enrichmentDeps: {} as FileEnrichmentDeps,
+    });
+
+    const result = await client.readTextFile?.({
+      sessionId: "s",
+      path: "/tmp/a.ts",
+    });
+    expect(result?.content).toBe("no posthog here");
+  });
+
+  test("calls upstream.readTextFile with original params (UI sees original)", async () => {
+    enrichFileMock.mockReset();
+    enrichFileMock.mockResolvedValueOnce("enriched");
+
+    const upstream = makeUpstream({ content: "original" });
+    const client = createCodexClient(upstream, logger, sessionState, {
+      enrichmentDeps: {} as FileEnrichmentDeps,
+    });
+
+    const params = {
+      sessionId: "s",
+      path: "/tmp/a.ts",
+      line: 10,
+      limit: 5,
+    };
+    await client.readTextFile?.(params);
+    expect(upstream.readTextFile).toHaveBeenCalledWith(params);
+  });
+});

package/src/adapters/codex/codex-client.ts

@@ -29,6 +29,10 @@ import type {
   WriteTextFileRequest,
   WriteTextFileResponse,
 } from "@agentclientprotocol/sdk";
+import {
+  enrichFileForAgent,
+  type FileEnrichmentDeps,
+} from "../../enrichment/file-enricher";
 import type { PermissionMode } from "../../execution-mode";
 import type { Logger } from "../../utils/logger";
 import type { CodexSessionState } from "./session-state";
@@ -36,6 +40,8 @@ import type { CodexSessionState } from "./session-state";
 export interface CodexClientCallbacks {
   /** Called when a usage_update session notification is received */
   onUsageUpdate?: (update: Record<string, unknown>) => void;
+  /** When set, Read responses are annotated with PostHog enrichment before reaching codex-acp. */
+  enrichmentDeps?: FileEnrichmentDeps;
 }
 
 const AUTO_APPROVED_KINDS: Record<PermissionMode, Set<ToolKind>> = {
@@ -152,7 +158,14 @@ export function createCodexClient(
     async readTextFile(
       params: ReadTextFileRequest,
     ): Promise<ReadTextFileResponse> {
-      return upstreamClient.readTextFile(params);
+      const response = await upstreamClient.readTextFile(params);
+      if (!callbacks?.enrichmentDeps) return response;
+      const enriched = await enrichFileForAgent(
+        callbacks.enrichmentDeps,
+        params.path,
+        response.content,
+      );
+      return enriched ? { ...response, content: enriched } : response;
     },
 
     async writeTextFile(

package/src/adapters/reasoning-effort.ts

@@ -3,7 +3,12 @@ import { getReasoningEffortOptions as getCodexReasoningEffortOptions } from "./c
 
 export type RuntimeAdapter = "claude" | "codex";
 
-export type SupportedReasoningEffort = "low" | "medium" | "high" | "max";
+export type SupportedReasoningEffort =
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh"
+  | "max";
 
 export interface ReasoningEffortOption {
   value: SupportedReasoningEffort;

package/src/agent.ts

@@ -19,6 +19,8 @@ export class Agent {
   private acpConnection?: InProcessAcpConnection;
   private taskRunId?: string;
   private sessionLogWriter?: SessionLogWriter;
+  private posthogApiConfig?: AgentConfig["posthog"];
+  private enricherEnabled: boolean;
 
   constructor(config: AgentConfig) {
     this.logger = new Logger({
@@ -29,7 +31,9 @@ export class Agent {
 
     if (config.posthog) {
       this.posthogAPI = new PostHogAPIClient(config.posthog);
+      this.posthogApiConfig = config.posthog;
     }
+    this.enricherEnabled = config.enricher?.enabled !== false;
 
     if (config.posthog && !config.skipLogPersistence) {
       this.sessionLogWriter = new SessionLogWriter({
@@ -121,6 +125,8 @@ export class Agent {
       processCallbacks: options.processCallbacks,
       onStructuredOutput: options.onStructuredOutput,
       allowedModelIds,
+      posthogApiConfig: this.posthogApiConfig,
+      enricherEnabled: this.enricherEnabled,
       codexOptions:
         options.adapter === "codex" && gatewayConfig
           ? {

package/src/enrichment/file-enricher.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, test, vi } from "vitest";
+import { enrichFileForAgent, type FileEnrichmentDeps } from "./file-enricher";
+
+function makeDeps(overrides: {
+  toInlineCommentsReturn?: string;
+  callsCount?: number;
+  initCallsCount?: number;
+  parseRejects?: Error;
+  isSupported?: boolean;
+  getApiKey?: () => string | Promise<string>;
+}): {
+  deps: FileEnrichmentDeps;
+  parseSpy: ReturnType<typeof vi.fn>;
+  enrichFromApiSpy: ReturnType<typeof vi.fn>;
+  getApiKeySpy: ReturnType<typeof vi.fn>;
+} {
+  const enrichFromApiSpy = vi.fn(async () => ({
+    toInlineComments: () =>
+      overrides.toInlineCommentsReturn ?? "enriched content",
+  }));
+
+  const parseSpy = vi.fn(async () => {
+    if (overrides.parseRejects) throw overrides.parseRejects;
+    return {
+      calls: Array.from({ length: overrides.callsCount ?? 1 }),
+      initCalls: Array.from({ length: overrides.initCallsCount ?? 0 }),
+      enrichFromApi: enrichFromApiSpy,
+    };
+  });
+
+  const getApiKeySpy = vi.fn(overrides.getApiKey ?? (() => "phx_test"));
+
+  const deps: FileEnrichmentDeps = {
+    enricher: {
+      isSupported: vi.fn(() => overrides.isSupported ?? true),
+      parse: parseSpy,
+    } as unknown as FileEnrichmentDeps["enricher"],
+    apiConfig: {
+      apiUrl: "https://test.posthog.com",
+      projectId: 1,
+      getApiKey: getApiKeySpy,
+    },
+  };
+
+  return { deps, parseSpy, enrichFromApiSpy, getApiKeySpy };
+}
+
+describe("enrichFileForAgent", () => {
+  test("returns null for unsupported extension", async () => {
+    const { deps, parseSpy } = makeDeps({});
+    const result = await enrichFileForAgent(
+      deps,
+      "/tmp/notes.txt",
+      "some text",
+    );
+    expect(result).toBeNull();
+    expect(parseSpy).not.toHaveBeenCalled();
+  });
+
+  test("returns null for empty content", async () => {
+    const { deps, parseSpy } = makeDeps({});
+    const result = await enrichFileForAgent(deps, "/tmp/code.ts", "");
+    expect(result).toBeNull();
+    expect(parseSpy).not.toHaveBeenCalled();
+  });
+
+  test("returns null for content > 1MB", async () => {
+    const { deps, parseSpy } = makeDeps({});
+    const huge = "x".repeat(1_000_001);
+    const result = await enrichFileForAgent(deps, "/tmp/code.ts", huge);
+    expect(result).toBeNull();
+    expect(parseSpy).not.toHaveBeenCalled();
+  });
+
+  test("returns null when language not supported by enricher", async () => {
+    const { deps, parseSpy } = makeDeps({ isSupported: false });
+    const result = await enrichFileForAgent(
+      deps,
+      "/tmp/code.ts",
+      "posthog.capture('x');",
+    );
+    expect(result).toBeNull();
+    expect(parseSpy).not.toHaveBeenCalled();
+  });
+
+  test("returns null when no PostHog calls detected", async () => {
+    const { deps, enrichFromApiSpy } = makeDeps({
+      callsCount: 0,
+      initCallsCount: 0,
+    });
+    const result = await enrichFileForAgent(
+      deps,
+      "/tmp/code.ts",
+      "posthog.capture('x');",
+    );
+    expect(result).toBeNull();
+    expect(enrichFromApiSpy).not.toHaveBeenCalled();
+  });
+
+  test("returns null and skips parse when content has no posthog reference", async () => {
+    const { deps, parseSpy } = makeDeps({});
+    const result = await enrichFileForAgent(
+      deps,
+      "/tmp/code.ts",
+      "const x = 1;\nfunction foo() {}",
+    );
+    expect(result).toBeNull();
+    expect(parseSpy).not.toHaveBeenCalled();
+  });
+
+  test("returns null when getApiKey yields empty string", async () => {
+    const { deps, enrichFromApiSpy } = makeDeps({ getApiKey: () => "" });
+    const result = await enrichFileForAgent(
+      deps,
+      "/tmp/code.ts",
+      "posthog.capture('x');",
+    );
+    expect(result).toBeNull();
+    expect(enrichFromApiSpy).not.toHaveBeenCalled();
+  });
+
+  test("returns null when toInlineComments produces no change", async () => {
+    const original = "posthog.capture('x');";
+    const { deps } = makeDeps({ toInlineCommentsReturn: original });
+    const result = await enrichFileForAgent(deps, "/tmp/code.ts", original);
+    expect(result).toBeNull();
+  });
+
+  test("returns null and logs debug when enricher throws", async () => {
+    const logger = { debug: vi.fn() };
+    const { deps } = makeDeps({ parseRejects: new Error("boom") });
+    deps.logger = logger as unknown as FileEnrichmentDeps["logger"];
+    const result = await enrichFileForAgent(
+      deps,
+      "/tmp/code.ts",
+      "posthog.capture('x');",
+    );
+    expect(result).toBeNull();
+    expect(logger.debug).toHaveBeenCalledWith(
+      "File enrichment failed",
+      expect.objectContaining({ filePath: "/tmp/code.ts" }),
+    );
+  });
+
+  test("returns enriched string when happy path completes", async () => {
+    const { deps, enrichFromApiSpy } = makeDeps({
+      toInlineCommentsReturn: "posthog.capture('x'); // [PostHog] Event: \"x\"",
+    });
+    const result = await enrichFileForAgent(
+      deps,
+      "/tmp/code.ts",
+      "posthog.capture('x');",
+    );
+    expect(result).toBe("posthog.capture('x'); // [PostHog] Event: \"x\"");
+    expect(enrichFromApiSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        apiKey: "phx_test",
+        host: "https://test.posthog.com",
+        projectId: 1,
+      }),
+    );
+  });
+});

package/src/enrichment/file-enricher.ts

@@ -0,0 +1,82 @@
+import * as path from "node:path";
+import { EXT_TO_LANG_ID, PostHogEnricher } from "@posthog/enricher";
+import type { PostHogAPIConfig } from "../types";
+import type { Logger } from "../utils/logger";
+
+export interface FileEnrichmentDeps {
+  enricher: PostHogEnricher;
+  apiConfig: PostHogAPIConfig;
+  logger?: Logger;
+}
+
+export interface Enrichment {
+  deps: FileEnrichmentDeps;
+  dispose(): void;
+}
+
+export function createEnrichment(
+  apiConfig: PostHogAPIConfig | undefined,
+  logger?: Logger,
+): Enrichment | undefined {
+  if (!apiConfig) return undefined;
+  const enricher = new PostHogEnricher();
+  return {
+    deps: { enricher, apiConfig, logger },
+    dispose: () => enricher.dispose(),
+  };
+}
+
+const MAX_ENRICHMENT_BYTES = 1_000_000;
+
+export async function enrichFileForAgent(
+  deps: FileEnrichmentDeps,
+  filePath: string,
+  content: string,
+): Promise<string | null> {
+  if (!content || content.length > MAX_ENRICHMENT_BYTES) return null;
+
+  // Skip the tree-sitter parse for files with no PostHog references.
+  if (!/posthog/i.test(content)) return null;
+
+  const ext = path.extname(filePath).toLowerCase();
+  const langId = EXT_TO_LANG_ID[ext];
+  if (!langId || !deps.enricher.isSupported(langId)) return null;
+
+  try {
+    const parsed = await deps.enricher.parse(content, langId);
+    if (parsed.calls.length === 0 && parsed.initCalls.length === 0) {
+      return null;
+    }
+
+    const apiKey = await deps.apiConfig.getApiKey();
+    if (!apiKey) return null;
+
+    const enriched = await parsed.enrichFromApi({
+      apiKey,
+      host: deps.apiConfig.apiUrl,
+      projectId: deps.apiConfig.projectId,
+      timeoutMs: 5_000,
+    });
+
+    const annotated = enriched.toInlineComments();
+    if (annotated === content) {
+      deps.logger?.debug("File enrichment produced no changes", {
+        filePath,
+        calls: parsed.calls.length,
+      });
+      return null;
+    }
+    deps.logger?.debug("File enriched", {
+      filePath,
+      calls: parsed.calls.length,
+    });
+    return annotated;
+  } catch (err) {
+    const detail =
+      err instanceof Error
+        ? { message: err.message, name: err.name, stack: err.stack }
+        : { value: String(err) };
+    deps.logger?.debug("File enrichment failed", { filePath, ...detail });
+    return null;
+  }
+}

package/src/execution-mode.test.ts

@@ -8,6 +8,7 @@ describe("execution modes", () => {
       "acceptEdits",
       "plan",
       "bypassPermissions",
+      "auto",
     ]);
   });
 

package/src/execution-mode.ts

@@ -25,19 +25,21 @@ const availableModes: ModeInfo[] = [
     name: "Plan Mode",
     description: "Planning mode, no actual tool execution",
   },
-  // {
-  //   id: "dontAsk",
-  //   name: "Don't Ask",
-  //   description: "Don't prompt for permissions, deny if not pre-approved",
-  // },
 ];
 
 if (ALLOW_BYPASS) {
-  availableModes.push({
-    id: "bypassPermissions",
-    name: "Auto-accept Permissions",
-    description: "Auto-accept all permission requests",
-  });
+  availableModes.push(
+    {
+      id: "bypassPermissions",
+      name: "Bypass Permissions",
+      description: "Auto-accept all permission requests",
+    },
+    {
+      id: "auto",
+      name: "Auto Mode",
+      description: "Use a model classifier to approve/deny permission prompts",
+    },
+  );
 }
 
 // Expose execution mode IDs in type-safe order for type checks
@@ -45,8 +47,8 @@ export const CODE_EXECUTION_MODES = [
   "default",
   "acceptEdits",
   "plan",
-  // "dontAsk",
   "bypassPermissions",
+  "auto",
 ] as const;
 
 export type CodeExecutionMode = (typeof CODE_EXECUTION_MODES)[number];

package/src/server/agent-server.ts

@@ -12,7 +12,7 @@ import { type ServerType, serve } from "@hono/node-server";
 import { getCurrentBranch } from "@posthog/git/queries";
 import { Hono } from "hono";
 import packageJson from "../../package.json" with { type: "json" };
-import { POSTHOG_NOTIFICATIONS } from "../acp-extensions";
+import { POSTHOG_METHODS, POSTHOG_NOTIFICATIONS } from "../acp-extensions";
 import {
   createAcpConnection,
   type InProcessAcpConnection,
@@ -644,6 +644,23 @@ export class AgentServer {
         };
       }
 
+      case POSTHOG_METHODS.REFRESH_SESSION:
+      case "posthog/refresh_session":
+      case "refresh_session": {
+        const mcpServers = Array.isArray(params.mcpServers)
+          ? params.mcpServers
+          : [];
+
+        this.logger.info("Refresh session requested", {
+          serverCount: mcpServers.length,
+        });
+
+        return await this.session.clientConnection.extMethod(
+          POSTHOG_METHODS.REFRESH_SESSION,
+          { mcpServers },
+        );
+      }
+
       case POSTHOG_NOTIFICATIONS.PERMISSION_RESPONSE:
       case "permission_response": {
         const requestId = params.requestId as string;

package/src/server/bin.ts

@@ -30,7 +30,7 @@ const envSchema = z.object({
   POSTHOG_CODE_RUNTIME_ADAPTER: z.enum(["claude", "codex"]).optional(),
   POSTHOG_CODE_MODEL: z.string().optional(),
   POSTHOG_CODE_REASONING_EFFORT: z
-    .enum(["low", "medium", "high", "max"])
+    .enum(["low", "medium", "high", "xhigh", "max"])
     .optional(),
 });
 

package/src/server/schemas.test.ts

@@ -184,4 +184,44 @@ describe("validateCommandParams", () => {
 
     expect(result.success).toBe(false);
   });
+
+  it("accepts _posthog/refresh_session with mcpServers", () => {
+    const result = validateCommandParams("_posthog/refresh_session", {
+      mcpServers: [
+        { type: "http", name: "mcp", url: "https://mcp.example.com" },
+      ],
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts posthog/refresh_session with empty mcpServers", () => {
+    const result = validateCommandParams("posthog/refresh_session", {
+      mcpServers: [],
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts bare refresh_session", () => {
+    const result = validateCommandParams("refresh_session", {
+      mcpServers: [],
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects refresh_session without mcpServers", () => {
+    const result = validateCommandParams("_posthog/refresh_session", {});
+
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects refresh_session with invalid mcpServers entry", () => {
+    const result = validateCommandParams("_posthog/refresh_session", {
+      mcpServers: [{ type: "stdio", name: "bad", command: "/bin/x" }],
+    });
+
+    expect(result.success).toBe(false);
+  });
 });

package/src/server/schemas.ts

@@ -60,6 +60,10 @@ export const setConfigOptionParamsSchema = z.object({
   value: z.string().min(1, "value is required"),
 });
 
+export const refreshSessionParamsSchema = z.object({
+  mcpServers: mcpServersSchema,
+});
+
 export const commandParamsSchemas = {
   user_message: userMessageParamsSchema,
   "posthog/user_message": userMessageParamsSchema,
@@ -71,6 +75,9 @@ export const commandParamsSchemas = {
   "posthog/permission_response": permissionResponseParamsSchema,
   set_config_option: setConfigOptionParamsSchema,
   "posthog/set_config_option": setConfigOptionParamsSchema,
+  refresh_session: refreshSessionParamsSchema,
+  "posthog/refresh_session": refreshSessionParamsSchema,
+  "_posthog/refresh_session": refreshSessionParamsSchema,
 } as const;
 
 export type CommandMethod = keyof typeof commandParamsSchemas;
@@ -82,7 +89,7 @@ export function validateCommandParams(
   const schema =
     commandParamsSchemas[method as CommandMethod] ??
     commandParamsSchemas[
-      method.replace("posthog/", "") as keyof typeof commandParamsSchemas
+      method.replace(/^_?posthog\//, "") as keyof typeof commandParamsSchemas
     ];
 
   if (!schema) {

package/src/server/types.ts

@@ -26,5 +26,5 @@ export interface AgentServerConfig {
   allowedDomains?: string[];
   runtimeAdapter?: "claude" | "codex";
   model?: string;
-  reasoningEffort?: "low" | "medium" | "high" | "max";
+  reasoningEffort?: "low" | "medium" | "high" | "xhigh" | "max";
 }

package/src/types.ts

@@ -152,6 +152,12 @@ export interface AgentConfig {
   skipLogPersistence?: boolean;
   /** Local cache path for instant log loading (e.g., ~/.posthog-code) */
   localCachePath?: string;
+  /**
+   * Annotate files the agent reads with PostHog enrichment (event volume,
+   * flag rollout/staleness, experiment links). Defaults to enabled when
+   * `posthog` config is present; set `{ enabled: false }` to opt out.
+   */
+  enricher?: { enabled?: boolean };
   debug?: boolean;
   onLog?: OnLogCallback;
 }