@posthog/agent 2.3.658 → 2.3.670

package/dist/types.d.ts

@@ -91,6 +91,8 @@ interface TaskExecutionOptions {
     processCallbacks?: ProcessSpawnedCallback;
     /** Callback invoked when the agent calls the create_output tool for structured output */
     onStructuredOutput?: (output: Record<string, unknown>) => Promise<void>;
+    /** Additional directories the agent process can access beyond cwd. */
+    additionalDirectories?: string[];
 }
 type LogLevel = "debug" | "info" | "warn" | "error";
 type OnLogCallback = (level: LogLevel, scope: string, message: string, data?: unknown) => void;

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}\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":";AA+MO,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  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":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/agent",
-  "version": "2.3.658",
+  "version": "2.3.670",
   "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/mcp/local-tools.test.ts

@@ -29,7 +29,7 @@ describe("createLocalToolsMcpServer", () => {
   it("exposes git_signed_commit over MCP in a cloud run with a token", async () => {
     const server = createLocalToolsMcpServer(
       { cwd: "/repo", token: "ghs_x" },
-      { taskRunId: "run-1" },
+      { environment: "cloud" },
     );
     if (!server) {
       throw new Error("expected the local-tools server to be registered");

package/src/adapters/claude/types.ts

@@ -121,6 +121,7 @@ export type SDKMessageFilter = {
 export type NewSessionMeta = {
   taskRunId?: string;
   taskId?: string;
+  environment?: "local" | "cloud";
   disableBuiltInTools?: boolean;
   systemPrompt?: unknown;
   sessionId?: string;

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

@@ -97,6 +97,7 @@ export {
 interface NewSessionMeta {
   taskRunId?: string;
   taskId?: string;
+  environment?: "local" | "cloud";
   systemPrompt?: string;
   permissionMode?: string;
   model?: string;

package/src/adapters/codex/spawn.ts

@@ -17,6 +17,8 @@ export interface CodexProcessOptions {
   logger?: Logger;
   processCallbacks?: ProcessSpawnedCallback;
   settings?: CodexSettings;
+  /** Additional writable roots passed to Codex's workspace-write sandbox. */
+  additionalDirectories?: string[];
 }
 
 export interface CodexProcess {
@@ -57,6 +59,13 @@ function buildConfigArgs(options: CodexProcessOptions): string[] {
     args.push("-c", `model_reasoning_effort="${options.reasoningEffort}"`);
   }
 
+  if (options.additionalDirectories?.length) {
+    const escaped = options.additionalDirectories
+      .map((p) => `"${p.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`)
+      .join(",");
+    args.push("-c", `sandbox_workspace_write.writable_roots=[${escaped}]`);
+  }
+
   if (options.instructions) {
     const escaped = options.instructions
       .replace(/\\/g, "\\\\")

package/src/adapters/local-tools/registry.test.ts

@@ -10,7 +10,7 @@ describe("local-tools registry", () => {
   const savedSandbox = process.env.IS_SANDBOX;
 
   beforeEach(() => {
-    // isCloudRun also keys off IS_SANDBOX; clear it so meta.taskRunId is the
+    // isCloudRun also keys off IS_SANDBOX; clear it so meta.environment is the
     // only cloud signal under test.
     delete process.env.IS_SANDBOX;
   });
@@ -35,23 +35,44 @@ describe("local-tools registry", () => {
   });
 
   it.each([
-    { name: "cloud run with a token", taskRunId: "run-1", token: "ghs_x" },
-    { name: "cloud run without a token", taskRunId: "run-1", token: undefined },
-    { name: "desktop run with a token", taskRunId: undefined, token: "ghs_x" },
+    {
+      name: "cloud run with a token",
+      meta: { environment: "cloud" as const },
+      token: "ghs_x",
+      expected: true,
+    },
+    {
+      name: "cloud run without a token",
+      meta: { environment: "cloud" as const },
+      token: undefined,
+      expected: false,
+    },
+    {
+      name: "desktop run with a token",
+      meta: { environment: "local" as const },
+      token: "ghs_x",
+      expected: false,
+    },
     {
       name: "desktop run without a token",
-      taskRunId: undefined,
+      meta: { environment: "local" as const },
       token: undefined,
+      expected: false,
     },
   ])(
     "exposes git_signed_commit only in $name when cloud+token",
-    ({ taskRunId, token }) => {
-      const tools = enabledLocalTools(
-        { cwd: "/repo", token },
-        taskRunId ? { taskRunId } : undefined,
-      );
+    ({ meta, token, expected }) => {
+      const tools = enabledLocalTools({ cwd: "/repo", token }, meta);
       const hasSignedCommit = tools.some((t) => t.name === "git_signed_commit");
-      expect(hasSignedCommit).toBe(Boolean(taskRunId) && Boolean(token));
+      expect(hasSignedCommit).toBe(expected);
     },
   );
+
+  it("does not treat legacy taskRunId-only metadata as cloud", () => {
+    const tools = enabledLocalTools({ cwd: "/repo", token: "ghs_x" }, {
+      taskRunId: "run-1",
+    } as unknown as { environment?: "local" | "cloud" });
+    const hasSignedCommit = tools.some((t) => t.name === "git_signed_commit");
+    expect(hasSignedCommit).toBe(false);
+  });
 });

package/src/adapters/local-tools/registry.ts

@@ -19,7 +19,7 @@ export interface LocalToolCtx {
 
 /** Minimal session-meta shape needed to gate tools (e.g. cloud-only). */
 export interface LocalToolGateMeta {
-  taskRunId?: string;
+  environment?: "local" | "cloud";
 }
 
 /**

package/src/agent.ts

@@ -136,6 +136,7 @@ export class Agent {
               binaryPath: options.codexBinaryPath,
               model: sanitizedModel,
               instructions: options.instructions,
+              additionalDirectories: options.additionalDirectories,
             }
           : undefined,
     });

package/src/server/agent-server.ts

@@ -976,6 +976,7 @@ export class AgentServer {
         sessionId: payload.run_id,
         taskRunId: payload.run_id,
         taskId: payload.task_id,
+        environment: "cloud",
         systemPrompt: sessionSystemPrompt,
         ...(this.config.model && { model: this.config.model }),
         allowedDomains: this.config.allowedDomains,

package/src/types.ts

@@ -125,6 +125,8 @@ export interface TaskExecutionOptions {
   processCallbacks?: ProcessSpawnedCallback;
   /** Callback invoked when the agent calls the create_output tool for structured output */
   onStructuredOutput?: (output: Record<string, unknown>) => Promise<void>;
+  /** Additional directories the agent process can access beyond cwd. */
+  additionalDirectories?: string[];
 }
 
 export type LogLevel = "debug" | "info" | "warn" | "error";

package/src/utils/common.ts

@@ -27,11 +27,16 @@ export const IS_ROOT =
 export const ALLOW_BYPASS = !IS_ROOT || !!process.env.IS_SANDBOX;
 
 /**
- * A cloud sandbox run, as opposed to a local desktop session. Cloud sandboxes
- * always set IS_SANDBOX and carry a taskRunId; desktop sessions have neither.
+ * A cloud sandbox run, as opposed to a local desktop session. `taskRunId` is
+ * used by both desktop and cloud for persistence, so it must not imply cloud.
  */
-export function isCloudRun(meta: { taskRunId?: string } | undefined): boolean {
-  return !!process.env.IS_SANDBOX || !!meta?.taskRunId;
+export function isCloudRun(
+  meta: { environment?: "local" | "cloud" } | undefined,
+): boolean {
+  if (meta?.environment) {
+    return meta.environment === "cloud";
+  }
+  return !!process.env.IS_SANDBOX;
 }
 
 /** The GitHub token available to the sandbox, if any. */