@posthog/agent 2.3.696 → 2.3.709

package/dist/types.d.ts

@@ -27,6 +27,7 @@ interface Task {
     title: string;
     description: string;
     origin_product: "error_tracking" | "eval_clusters" | "user_created" | "support_queue" | "session_summaries" | "signal_report";
+    signal_report?: string | null;
     github_integration?: number | null;
     repository: string;
     json_schema?: Record<string, unknown> | null;

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts"],"sourcesContent":["import type {\n  GitHandoffCheckpoint,\n  HandoffLocalGitState as GitHandoffLocalGitState,\n} from \"@posthog/git/handoff\";\n\n/**\n * Stored custom notification following ACP extensibility model.\n * Custom notifications use underscore-prefixed methods (e.g., `_posthog/phase_start`).\n * See: https://agentclientprotocol.com/docs/extensibility\n */\nexport interface StoredNotification {\n  type: \"notification\";\n  /** When this notification was stored */\n  timestamp: string;\n  /** JSON-RPC 2.0 notification (no id field = notification, not request) */\n  notification: {\n    jsonrpc: \"2.0\";\n    method: string;\n    params?: Record<string, unknown>;\n  };\n}\n\n/**\n * Type alias for stored log entries.\n */\nexport type StoredEntry = StoredNotification;\n\n// PostHog Task model (matches PostHog Code's OpenAPI schema)\nexport interface Task {\n  id: string;\n  task_number?: number;\n  slug?: string;\n  title: string;\n  description: string;\n  origin_product:\n    | \"error_tracking\"\n    | \"eval_clusters\"\n    | \"user_created\"\n    | \"support_queue\"\n    | \"session_summaries\"\n    | \"signal_report\";\n  github_integration?: number | null;\n  repository: string; // Format: \"organization/repository\" (e.g., \"posthog/posthog-js\")\n  json_schema?: Record<string, unknown> | null; // JSON schema for task output validation\n  internal?: boolean;\n  created_at: string;\n  updated_at: string;\n  created_by?: {\n    id: number;\n    uuid: string;\n    distinct_id: string;\n    first_name: string;\n    email: string;\n  };\n  latest_run?: TaskRun;\n}\n\n// Log entry structure for TaskRun.log\n\nexport type ArtifactType =\n  | \"plan\"\n  | \"context\"\n  | \"reference\"\n  | \"output\"\n  | \"artifact\"\n  | \"user_attachment\";\n\nexport interface TaskRunArtifact {\n  id?: string;\n  name: string;\n  type: ArtifactType;\n  source?: string;\n  size?: number;\n  content_type?: string;\n  storage_path?: string;\n  uploaded_at?: string;\n}\n\nexport type TaskRunStatus =\n  | \"not_started\"\n  | \"queued\"\n  | \"in_progress\"\n  | \"completed\"\n  | \"failed\"\n  | \"cancelled\";\n\nexport type TaskRunEnvironment = \"local\" | \"cloud\";\n\n// TaskRun model - represents individual execution runs of tasks\nexport interface TaskRun {\n  id: string;\n  task: string; // Task ID\n  team: number;\n  branch: string | null;\n  stage: string | null; // Current stage (e.g., 'research', 'plan', 'build')\n  environment: TaskRunEnvironment;\n  status: TaskRunStatus;\n  log_url: string;\n  error_message: string | null;\n  output: Record<string, unknown> | null; // Structured output (PR URL, commit SHA, etc.)\n  state: Record<string, unknown>; // Intermediate run state (defaults to {}, never null)\n  artifacts?: TaskRunArtifact[];\n  created_at: string;\n  updated_at: string;\n  completed_at: string | null;\n}\n\nexport interface ProcessSpawnedCallback {\n  onProcessSpawned?: (info: {\n    pid: number;\n    command: string;\n    sessionId?: string;\n  }) => void;\n  onProcessExited?: (pid: number) => void;\n  onMcpServersReady?: (serverNames: string[]) => void;\n}\n\nexport interface TaskExecutionOptions {\n  repositoryPath?: string;\n  adapter?: \"claude\" | \"codex\";\n  model?: string;\n  gatewayUrl?: string;\n  codexBinaryPath?: string;\n  instructions?: string;\n  processCallbacks?: ProcessSpawnedCallback;\n  /** Callback invoked when the agent calls the create_output tool for structured output */\n  onStructuredOutput?: (output: Record<string, unknown>) => Promise<void>;\n  /** Additional directories the agent process can access beyond cwd. */\n  additionalDirectories?: string[];\n}\n\nexport type LogLevel = \"debug\" | \"info\" | \"warn\" | \"error\";\n\nexport type OnLogCallback = (\n  level: LogLevel,\n  scope: string,\n  message: string,\n  data?: unknown,\n) => void;\n\nexport interface PostHogAPIConfig {\n  apiUrl: string;\n  getApiKey: () => string | Promise<string>;\n  refreshApiKey?: () => string | Promise<string>;\n  projectId: number;\n  userAgent?: string;\n}\n\nexport interface OtelTransportConfig {\n  /** PostHog ingest host, e.g., \"https://us.i.posthog.com\" */\n  host: string;\n  /** Project API key */\n  apiKey: string;\n  /** Override the logs endpoint path (default: /i/v1/logs) */\n  logsPath?: string;\n}\n\nexport interface AgentConfig {\n  posthog?: PostHogAPIConfig;\n  /** OTEL transport config for shipping logs to PostHog Logs */\n  otelTransport?: OtelTransportConfig;\n  /** Skip session log persistence (e.g. for preview sessions with no real task) */\n  skipLogPersistence?: boolean;\n  /** Local cache path for instant log loading (e.g., ~/.posthog-code) */\n  localCachePath?: string;\n  /**\n   * Annotate files the agent reads with PostHog enrichment (event volume,\n   * flag rollout/staleness, experiment links). Defaults to enabled when\n   * `posthog` config is present; set `{ enabled: false }` to opt out.\n   */\n  enricher?: { enabled?: boolean };\n  debug?: boolean;\n  onLog?: OnLogCallback;\n}\n\n// Device info for tracking where work happens\nexport interface DeviceInfo {\n  type: \"local\" | \"cloud\";\n  name?: string;\n}\n\n// Agent execution mode - for tracking interactive vs background runs, when backgrounded an agent will continue working without asking questions\nexport type AgentMode = \"interactive\" | \"background\";\n\n// Git file status codes\nexport type FileStatus = \"A\" | \"M\" | \"D\";\n\nexport interface FileChange {\n  path: string;\n  status: FileStatus;\n}\n\nexport type HandoffLocalGitState = GitHandoffLocalGitState;\n\nexport interface GitCheckpoint extends GitHandoffCheckpoint {\n  artifactPath?: string;\n  indexArtifactPath?: string;\n}\n\nexport interface GitCheckpointEvent extends GitCheckpoint {\n  device?: DeviceInfo;\n}\n\n/**\n * Keeps the emitted `@posthog/agent/types` entrypoint as a runtime ESM module.\n *\n * `export {}` is stripped by tsup in this package, which leaves `dist/types.js`\n * empty and breaks downstream type resolution for the exported subpath.\n */\nexport const AGENT_TYPES_MODULE = true;\n"],"mappings":";AAiNO,IAAM,qBAAqB;","names":[]}
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["import type {\n  GitHandoffCheckpoint,\n  HandoffLocalGitState as GitHandoffLocalGitState,\n} from \"@posthog/git/handoff\";\n\n/**\n * Stored custom notification following ACP extensibility model.\n * Custom notifications use underscore-prefixed methods (e.g., `_posthog/phase_start`).\n * See: https://agentclientprotocol.com/docs/extensibility\n */\nexport interface StoredNotification {\n  type: \"notification\";\n  /** When this notification was stored */\n  timestamp: string;\n  /** JSON-RPC 2.0 notification (no id field = notification, not request) */\n  notification: {\n    jsonrpc: \"2.0\";\n    method: string;\n    params?: Record<string, unknown>;\n  };\n}\n\n/**\n * Type alias for stored log entries.\n */\nexport type StoredEntry = StoredNotification;\n\n// PostHog Task model (matches PostHog Code's OpenAPI schema)\nexport interface Task {\n  id: string;\n  task_number?: number;\n  slug?: string;\n  title: string;\n  description: string;\n  origin_product:\n    | \"error_tracking\"\n    | \"eval_clusters\"\n    | \"user_created\"\n    | \"support_queue\"\n    | \"session_summaries\"\n    | \"signal_report\";\n  signal_report?: string | null; // Inbox report UUID when origin_product is \"signal_report\"\n  github_integration?: number | null;\n  repository: string; // Format: \"organization/repository\" (e.g., \"posthog/posthog-js\")\n  json_schema?: Record<string, unknown> | null; // JSON schema for task output validation\n  internal?: boolean;\n  created_at: string;\n  updated_at: string;\n  created_by?: {\n    id: number;\n    uuid: string;\n    distinct_id: string;\n    first_name: string;\n    email: string;\n  };\n  latest_run?: TaskRun;\n}\n\n// Log entry structure for TaskRun.log\n\nexport type ArtifactType =\n  | \"plan\"\n  | \"context\"\n  | \"reference\"\n  | \"output\"\n  | \"artifact\"\n  | \"user_attachment\";\n\nexport interface TaskRunArtifact {\n  id?: string;\n  name: string;\n  type: ArtifactType;\n  source?: string;\n  size?: number;\n  content_type?: string;\n  storage_path?: string;\n  uploaded_at?: string;\n}\n\nexport type TaskRunStatus =\n  | \"not_started\"\n  | \"queued\"\n  | \"in_progress\"\n  | \"completed\"\n  | \"failed\"\n  | \"cancelled\";\n\nexport type TaskRunEnvironment = \"local\" | \"cloud\";\n\n// TaskRun model - represents individual execution runs of tasks\nexport interface TaskRun {\n  id: string;\n  task: string; // Task ID\n  team: number;\n  branch: string | null;\n  stage: string | null; // Current stage (e.g., 'research', 'plan', 'build')\n  environment: TaskRunEnvironment;\n  status: TaskRunStatus;\n  log_url: string;\n  error_message: string | null;\n  output: Record<string, unknown> | null; // Structured output (PR URL, commit SHA, etc.)\n  state: Record<string, unknown>; // Intermediate run state (defaults to {}, never null)\n  artifacts?: TaskRunArtifact[];\n  created_at: string;\n  updated_at: string;\n  completed_at: string | null;\n}\n\nexport interface ProcessSpawnedCallback {\n  onProcessSpawned?: (info: {\n    pid: number;\n    command: string;\n    sessionId?: string;\n  }) => void;\n  onProcessExited?: (pid: number) => void;\n  onMcpServersReady?: (serverNames: string[]) => void;\n}\n\nexport interface TaskExecutionOptions {\n  repositoryPath?: string;\n  adapter?: \"claude\" | \"codex\";\n  model?: string;\n  gatewayUrl?: string;\n  codexBinaryPath?: string;\n  instructions?: string;\n  processCallbacks?: ProcessSpawnedCallback;\n  /** Callback invoked when the agent calls the create_output tool for structured output */\n  onStructuredOutput?: (output: Record<string, unknown>) => Promise<void>;\n  /** Additional directories the agent process can access beyond cwd. */\n  additionalDirectories?: string[];\n}\n\nexport type LogLevel = \"debug\" | \"info\" | \"warn\" | \"error\";\n\nexport type OnLogCallback = (\n  level: LogLevel,\n  scope: string,\n  message: string,\n  data?: unknown,\n) => void;\n\nexport interface PostHogAPIConfig {\n  apiUrl: string;\n  getApiKey: () => string | Promise<string>;\n  refreshApiKey?: () => string | Promise<string>;\n  projectId: number;\n  userAgent?: string;\n}\n\nexport interface OtelTransportConfig {\n  /** PostHog ingest host, e.g., \"https://us.i.posthog.com\" */\n  host: string;\n  /** Project API key */\n  apiKey: string;\n  /** Override the logs endpoint path (default: /i/v1/logs) */\n  logsPath?: string;\n}\n\nexport interface AgentConfig {\n  posthog?: PostHogAPIConfig;\n  /** OTEL transport config for shipping logs to PostHog Logs */\n  otelTransport?: OtelTransportConfig;\n  /** Skip session log persistence (e.g. for preview sessions with no real task) */\n  skipLogPersistence?: boolean;\n  /** Local cache path for instant log loading (e.g., ~/.posthog-code) */\n  localCachePath?: string;\n  /**\n   * Annotate files the agent reads with PostHog enrichment (event volume,\n   * flag rollout/staleness, experiment links). Defaults to enabled when\n   * `posthog` config is present; set `{ enabled: false }` to opt out.\n   */\n  enricher?: { enabled?: boolean };\n  debug?: boolean;\n  onLog?: OnLogCallback;\n}\n\n// Device info for tracking where work happens\nexport interface DeviceInfo {\n  type: \"local\" | \"cloud\";\n  name?: string;\n}\n\n// Agent execution mode - for tracking interactive vs background runs, when backgrounded an agent will continue working without asking questions\nexport type AgentMode = \"interactive\" | \"background\";\n\n// Git file status codes\nexport type FileStatus = \"A\" | \"M\" | \"D\";\n\nexport interface FileChange {\n  path: string;\n  status: FileStatus;\n}\n\nexport type HandoffLocalGitState = GitHandoffLocalGitState;\n\nexport interface GitCheckpoint extends GitHandoffCheckpoint {\n  artifactPath?: string;\n  indexArtifactPath?: string;\n}\n\nexport interface GitCheckpointEvent extends GitCheckpoint {\n  device?: DeviceInfo;\n}\n\n/**\n * Keeps the emitted `@posthog/agent/types` entrypoint as a runtime ESM module.\n *\n * `export {}` is stripped by tsup in this package, which leaves `dist/types.js`\n * empty and breaks downstream type resolution for the exported subpath.\n */\nexport const AGENT_TYPES_MODULE = true;\n"],"mappings":";AAkNO,IAAM,qBAAqB;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/agent",
-  "version": "2.3.696",
+  "version": "2.3.709",
   "repository": "https://github.com/PostHog/code",
   "description": "TypeScript agent framework wrapping Claude Agent SDK with Git-based task execution for PostHog",
   "exports": {
@@ -106,9 +106,9 @@
     "tsx": "^4.20.6",
     "typescript": "^5.5.0",
     "vitest": "^2.1.8",
-    "@posthog/enricher": "1.0.0",
     "@posthog/shared": "1.0.0",
-    "@posthog/git": "1.0.0"
+    "@posthog/git": "1.0.0",
+    "@posthog/enricher": "1.0.0"
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "0.19.0",

package/src/adapters/claude/claude-agent.slash-command.test.ts

@@ -0,0 +1,153 @@
+import type { AgentSideConnection } from "@agentclientprotocol/sdk";
+import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createMockQuery, type MockQuery } from "../../test/mocks/claude-sdk";
+import { Pushable } from "../../utils/streams";
+
+vi.mock("@anthropic-ai/claude-agent-sdk", () => ({
+  query: vi.fn(),
+}));
+
+vi.mock("./mcp/tool-metadata", () => ({
+  fetchMcpToolMetadata: vi.fn().mockResolvedValue(undefined),
+  getConnectedMcpServerNames: vi.fn().mockReturnValue([]),
+  setMcpToolApprovalStates: vi.fn(),
+  isMcpToolReadOnly: vi.fn().mockReturnValue(false),
+  getMcpToolMetadata: vi.fn().mockReturnValue(undefined),
+  getMcpToolApprovalState: vi.fn().mockReturnValue(undefined),
+}));
+
+const { ClaudeAcpAgent } = await import("./claude-agent");
+type Agent = InstanceType<typeof ClaudeAcpAgent>;
+
+interface ClientMocks {
+  sessionUpdate: ReturnType<typeof vi.fn>;
+  extNotification: ReturnType<typeof vi.fn>;
+}
+
+function makeAgent(): { agent: Agent; client: ClientMocks } {
+  const client: ClientMocks = {
+    sessionUpdate: vi.fn().mockResolvedValue(undefined),
+    extNotification: vi.fn().mockResolvedValue(undefined),
+  };
+  const agent = new ClaudeAcpAgent(client as unknown as AgentSideConnection);
+  return { agent, client };
+}
+
+function installFakeSession(agent: Agent, sessionId: string): MockQuery {
+  const query = createMockQuery();
+  const input = new Pushable();
+  const abortController = new AbortController();
+
+  const session = {
+    query,
+    queryOptions: { sessionId, cwd: "/tmp/repo", abortController },
+    input,
+    cancelled: false,
+    interruptReason: undefined,
+    settingsManager: { dispose: vi.fn(), getRepoRoot: () => "/tmp/repo" },
+    permissionMode: "default" as const,
+    abortController,
+    accumulatedUsage: {
+      inputTokens: 0,
+      outputTokens: 0,
+      cachedReadTokens: 0,
+      cachedWriteTokens: 0,
+    },
+    configOptions: [],
+    promptRunning: false,
+    pendingMessages: new Map(),
+    nextPendingOrder: 0,
+    cwd: "/tmp/repo",
+    notificationHistory: [] as unknown[],
+    taskRunId: "run-1",
+    lastContextWindowSize: 200_000,
+    modelId: "claude-sonnet-4-6",
+  };
+
+  (agent as unknown as { session: typeof session }).session = session;
+  (agent as unknown as { sessionId: string }).sessionId = sessionId;
+
+  return query;
+}
+
+function findUnsupportedChunkText(
+  calls: ClientMocks["sessionUpdate"]["mock"]["calls"],
+): string | undefined {
+  const match = calls.find(([call]) => {
+    const update = (
+      call as {
+        update?: { sessionUpdate?: string; content?: { text?: string } };
+      }
+    ).update;
+    return (
+      update?.sessionUpdate === "agent_message_chunk" &&
+      update?.content?.text?.toLowerCase().includes("unsupported")
+    );
+  });
+  return (match?.[0] as { update: { content: { text: string } } } | undefined)
+    ?.update.content.text;
+}
+
+describe("ClaudeAcpAgent.prompt — early idle handling", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  const cases = [
+    {
+      label: "unsupported slash command surfaces error and ends turn",
+      sessionId: "s-slash",
+      prompt: "/plugin install slack",
+      expectsUnsupportedChunk: true,
+      commandInMessage: "/plugin",
+    },
+    {
+      label: "non-slash prompt with early idle is silently skipped",
+      sessionId: "s-regular",
+      prompt: "hello",
+      expectsUnsupportedChunk: false,
+      commandInMessage: null,
+    },
+  ] as const;
+
+  it.each(cases)("$label", async (tc) => {
+    const { agent, client } = makeAgent();
+    const query = installFakeSession(agent, tc.sessionId);
+
+    const promptPromise = agent.prompt({
+      sessionId: tc.sessionId,
+      prompt: [{ type: "text", text: tc.prompt }],
+    });
+
+    // Let the prompt loop start awaiting the first SDK message.
+    await new Promise((resolve) => setImmediate(resolve));
+
+    query._mockHelpers.sendMessage({
+      type: "system",
+      subtype: "session_state_changed",
+      state: "idle",
+    } as unknown as SDKMessage);
+    query._mockHelpers.complete();
+
+    if (tc.expectsUnsupportedChunk) {
+      const result = await promptPromise;
+      expect(result.stopReason).toBe("end_turn");
+
+      const text = findUnsupportedChunkText(client.sessionUpdate.mock.calls);
+      expect(text).toBeDefined();
+      if (tc.commandInMessage) {
+        expect(text).toContain(tc.commandInMessage);
+      }
+    } else {
+      // No unsupported chunk; loop falls through to the existing
+      // "Session did not end in result" failure path.
+      await expect(promptPromise).rejects.toThrow(
+        /Session did not end in result/,
+      );
+      expect(
+        findUnsupportedChunkText(client.sessionUpdate.mock.calls),
+      ).toBeUndefined();
+    }
+  });
+});

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

@@ -496,6 +496,28 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
               (message as Record<string, unknown>).state === "idle"
             ) {
               if (!promptReplayed) {
+                // The SDK consumed a slash command we do not handle locally
+                // and produced no output (e.g. /plugin in a non-interactive
+                // context). Without this branch we would loop forever waiting
+                // for an echo that never comes; surface a clear error instead.
+                if (commandMatch) {
+                  const cmd = commandMatch[1];
+                  this.logger.warn(
+                    "Slash command produced no output; treating as unsupported",
+                    { sessionId: params.sessionId, command: cmd },
+                  );
+                  await this.client.sessionUpdate({
+                    sessionId: params.sessionId,
+                    update: {
+                      sessionUpdate: "agent_message_chunk",
+                      content: {
+                        type: "text",
+                        text: `Unsupported slash command: \`${cmd}\`. PostHog Code does not implement this command.`,
+                      },
+                    },
+                  });
+                  return { stopReason: "end_turn" };
+                }
                 this.logger.debug("Skipping idle state before prompt replay", {
                   sessionId: params.sessionId,
                 });

package/src/server/agent-server.configure-environment.test.ts

@@ -5,6 +5,7 @@ interface TestableServer {
   configureEnvironment(args?: {
     isInternal?: boolean;
     originProduct?: string | null;
+    signalReportId?: string | null;
     taskId?: string | null;
     taskRunId?: string | null;
     taskUserId?: number | null;
@@ -124,6 +125,7 @@ describe("AgentServer.configureEnvironment", () => {
     buildServer("background").configureEnvironment({
       isInternal: true,
       originProduct: "signal_report",
+      signalReportId: "report-123",
       taskId: "task-abc",
       taskRunId: "run-xyz",
       taskUserId: 42,
@@ -133,6 +135,7 @@ describe("AgentServer.configureEnvironment", () => {
       [
         "x-posthog-property-task_origin_product: signal_report",
         "x-posthog-property-task_internal: true",
+        "x-posthog-property-signal_report_id: report-123",
         "x-posthog-property-task_id: task-abc",
         "x-posthog-property-task_run_id: run-xyz",
         "x-posthog-property-task_user_id: 42",
@@ -140,6 +143,17 @@ describe("AgentServer.configureEnvironment", () => {
     );
   });
 
+  it("omits signal_report_id from ANTHROPIC_CUSTOM_HEADERS for non-report tasks", () => {
+    buildServer("background").configureEnvironment({
+      isInternal: false,
+      taskId: "task-abc",
+    });
+
+    expect(process.env.ANTHROPIC_CUSTOM_HEADERS).not.toContain(
+      "signal_report_id",
+    );
+  });
+
   it("omits optional task metadata from ANTHROPIC_CUSTOM_HEADERS when not provided", () => {
     buildServer("background").configureEnvironment({ isInternal: false });
 

package/src/server/agent-server.ts

@@ -867,6 +867,7 @@ export class AgentServer {
     this.configureEnvironment({
       isInternal: preTask?.internal === true,
       originProduct: preTask?.origin_product,
+      signalReportId: preTask?.signal_report,
       taskId: payload.task_id,
       taskRunId: payload.run_id,
       taskUserId: payload.user_id,
@@ -1853,12 +1854,14 @@ ${signedCommitInstructions}
   private configureEnvironment({
     isInternal = false,
     originProduct,
+    signalReportId,
     taskId,
     taskRunId,
     taskUserId,
   }: {
     isInternal?: boolean;
     originProduct?: string | null;
+    signalReportId?: string | null;
     taskId?: string | null;
     taskRunId?: string | null;
     taskUserId?: number | null;
@@ -1877,6 +1880,7 @@ ${signedCommitInstructions}
     const customHeaders = buildGatewayPropertyHeaders({
       task_origin_product: originProduct,
       task_internal: isInternal,
+      signal_report_id: signalReportId,
       task_id: taskId,
       task_run_id: taskRunId,
       task_user_id: taskUserId,

package/src/types.ts

@@ -39,6 +39,7 @@ export interface Task {
     | "support_queue"
     | "session_summaries"
     | "signal_report";
+  signal_report?: string | null; // Inbox report UUID when origin_product is "signal_report"
   github_integration?: number | null;
   repository: string; // Format: "organization/repository" (e.g., "posthog/posthog-js")
   json_schema?: Record<string, unknown> | null; // JSON schema for task output validation