@posthog/agent 2.0.0 → 2.0.1

package/src/types.ts

@@ -1,12 +1,3 @@
-// import and export to keep a single type file
-
-import type { SessionNotification } from "@agentclientprotocol/sdk";
-import type {
-  CanUseTool,
-  PermissionResult,
-} from "@anthropic-ai/claude-agent-sdk";
-export type { CanUseTool, PermissionResult, SessionNotification };
-
 /**
  * Stored custom notification following ACP extensibility model.
  * Custom notifications use underscore-prefixed methods (e.g., `_posthog/phase_start`).
@@ -29,7 +20,7 @@ export interface StoredNotification {
  */
 export type StoredEntry = StoredNotification;
 
-// PostHog Task model (matches Array's OpenAPI schema)
+// PostHog Task model (matches Twig's OpenAPI schema)
 export interface Task {
   id: string;
   task_number?: number;
@@ -64,7 +55,8 @@ export type ArtifactType =
   | "context"
   | "reference"
   | "output"
-  | "artifact";
+  | "artifact"
+  | "tree_snapshot";
 
 export interface TaskRunArtifact {
   name: string;
@@ -104,88 +96,23 @@ export interface TaskRun {
   completed_at: string | null;
 }
 
-export interface SupportingFile {
-  name: string;
-  content: string;
-  type: ArtifactType;
-  created_at: string;
-}
-
-export interface TaskArtifactUploadPayload {
-  name: string;
-  type: ArtifactType;
-  content: string;
-  content_type?: string;
-}
-
-export enum PermissionMode {
-  PLAN = "plan",
-  DEFAULT = "default",
-  ACCEPT_EDITS = "acceptEdits",
-  BYPASS = "bypassPermissions",
-}
-
-export interface ExecutionOptions {
-  repositoryPath?: string;
-  permissionMode?: PermissionMode;
+export interface ProcessSpawnedCallback {
+  onProcessSpawned?: (info: {
+    pid: number;
+    command: string;
+    sessionId?: string;
+  }) => void;
+  onProcessExited?: (pid: number) => void;
 }
 
 export interface TaskExecutionOptions {
   repositoryPath?: string;
-  permissionMode?: PermissionMode;
-  isCloudMode?: boolean; // Determines local vs cloud behavior (local pauses after each phase)
-  createPR?: boolean; // Whether to create PR after build (defaults to false)
-  autoProgress?: boolean;
-  queryOverrides?: Record<string, unknown>;
-  // Fine-grained permission control (only applied to build phase)
-  // See: https://docs.claude.com/en/api/agent-sdk/permissions
-  canUseTool?: CanUseTool;
-  skipGitBranch?: boolean; // Skip creating a task-specific git branch
-  framework?: "claude"; // Agent framework to use (defaults to "claude")
-  task?: Task; // Pre-fetched task to avoid redundant API call
-  isReconnect?: boolean; // Session recreation - skip RUN_STARTED notification
-}
-
-export interface ExecutionResult {
-  // biome-ignore lint/suspicious/noExplicitAny: Results array contains varying SDK response types
-  results: any[];
-}
-
-export interface PlanResult {
-  plan: string;
-}
-
-export interface TaskExecutionResult {
-  task: Task;
-  plan?: string;
-  executionResult?: ExecutionResult;
+  adapter?: "claude" | "codex";
+  model?: string;
+  codexBinaryPath?: string;
+  processCallbacks?: ProcessSpawnedCallback;
 }
 
-// MCP Server configuration types (re-exported from Claude SDK for convenience)
-export type McpServerConfig =
-  | {
-      type?: "stdio";
-      command: string;
-      args?: string[];
-      env?: Record<string, string>;
-    }
-  | {
-      type: "sse";
-      url: string;
-      headers?: Record<string, string>;
-    }
-  | {
-      type: "http";
-      url: string;
-      headers?: Record<string, string>;
-    }
-  | {
-      type: "sdk";
-      name: string;
-      // biome-ignore lint/suspicious/noExplicitAny: McpServer instance type from external SDK
-      instance?: any;
-    };
-
 export type LogLevel = "debug" | "info" | "warn" | "error";
 
 export type OnLogCallback = (
@@ -195,67 +122,57 @@ export type OnLogCallback = (
   data?: unknown,
 ) => void;
 
-export interface AgentConfig {
-  workingDirectory?: string;
-
-  // PostHog API configuration (optional - enables PostHog integration when provided)
-  posthogApiUrl?: string;
-  getPosthogApiKey?: () => string;
-  posthogProjectId?: number;
-
-  // PostHog MCP configuration
-  posthogMcpUrl?: string;
+export interface PostHogAPIConfig {
+  apiUrl: string;
+  getApiKey: () => string;
+  projectId: number;
+}
 
-  // MCP Server configuration
-  // Additional MCP servers (PostHog MCP is always included by default)
-  // You can override the PostHog MCP config by providing mcpServers.posthog
-  mcpServers?: Record<string, McpServerConfig>;
+export interface OtelTransportConfig {
+  /** PostHog ingest host, e.g., "https://us.i.posthog.com" */
+  host: string;
+  /** Project API key */
+  apiKey: string;
+  /** Override the logs endpoint path (default: /i/v1/logs) */
+  logsPath?: string;
+}
 
-  // Logging configuration
+export interface AgentConfig {
+  posthog?: PostHogAPIConfig;
+  /** OTEL transport config for shipping logs to PostHog Logs */
+  otelTransport?: OtelTransportConfig;
   debug?: boolean;
   onLog?: OnLogCallback;
-
-  // Fine-grained permission control for direct run() calls
-  // See: https://docs.claude.com/en/api/agent-sdk/permissions
-  canUseTool?: CanUseTool;
 }
 
-export interface PostHogAPIConfig {
-  apiUrl: string;
-  getApiKey: () => string;
-  projectId: number;
+// Device info for tracking where work happens
+export interface DeviceInfo {
+  type: "local" | "cloud";
+  name?: string;
 }
 
-// URL mention types
-export type ResourceType =
-  | "error"
-  | "experiment"
-  | "insight"
-  | "feature_flag"
-  | "generic";
+// Agent execution mode - for tracking interactive vs background runs, when backgrounded an agent will continue working without asking questions
+export type AgentMode = "interactive" | "background";
 
-export interface PostHogResource {
-  type: ResourceType;
-  id: string;
-  url: string;
-  title?: string;
-  content: string;
-  // biome-ignore lint/suspicious/noExplicitAny: Metadata contains varying resource-specific fields
-  metadata?: Record<string, any>;
+// Git file status codes
+export type FileStatus = "A" | "M" | "D";
+
+export interface FileChange {
+  path: string;
+  status: FileStatus;
 }
 
-export interface UrlMention {
-  url: string;
-  type: ResourceType;
-  id?: string;
-  label?: string;
+// Tree snapshot - what TreeTracker captures
+export interface TreeSnapshot {
+  treeHash: string;
+  baseCommit: string | null;
+  archiveUrl?: string;
+  changes: FileChange[];
+  timestamp: string;
+  interrupted?: boolean;
 }
 
-// Worktree types for parallel task development
-export interface WorktreeInfo {
-  worktreePath: string;
-  worktreeName: string;
-  branchName: string;
-  baseBranch: string;
-  createdAt: string;
+// Tree snapshot event - includes device info when sent as notification
+export interface TreeSnapshotEvent extends TreeSnapshot {
+  device?: DeviceInfo;
 }

package/src/utils/acp-content.ts

@@ -0,0 +1,58 @@
+import type { ContentBlock, ToolCallContent } from "@agentclientprotocol/sdk";
+
+export function text(value: string): ContentBlock {
+  return { type: "text", text: value };
+}
+
+export function image(
+  data: string,
+  mimeType: string,
+  uri?: string,
+): ContentBlock {
+  return { type: "image", data, mimeType, uri };
+}
+
+export function resourceLink(
+  uri: string,
+  name: string,
+  options?: {
+    mimeType?: string;
+    title?: string;
+    description?: string;
+    size?: bigint;
+  },
+): ContentBlock {
+  return {
+    type: "resource_link",
+    uri,
+    name,
+    ...options,
+  };
+}
+
+class ToolContentBuilder {
+  private items: ToolCallContent[] = [];
+
+  text(value: string): this {
+    this.items.push({ type: "content", content: text(value) });
+    return this;
+  }
+
+  image(data: string, mimeType: string, uri?: string): this {
+    this.items.push({ type: "content", content: image(data, mimeType, uri) });
+    return this;
+  }
+
+  diff(path: string, oldText: string | null, newText: string): this {
+    this.items.push({ type: "diff", path, oldText, newText });
+    return this;
+  }
+
+  build(): ToolCallContent[] {
+    return this.items;
+  }
+}
+
+export function toolContent(): ToolContentBuilder {
+  return new ToolContentBuilder();
+}

package/src/utils/async-mutex.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from "vitest";
+import { AsyncMutex } from "./async-mutex.js";
+
+describe("AsyncMutex", () => {
+  it("acquires lock when unlocked", async () => {
+    const mutex = new AsyncMutex();
+
+    expect(mutex.isLocked()).toBe(false);
+    await mutex.acquire();
+    expect(mutex.isLocked()).toBe(true);
+  });
+
+  it("releases lock", async () => {
+    const mutex = new AsyncMutex();
+
+    await mutex.acquire();
+    expect(mutex.isLocked()).toBe(true);
+
+    mutex.release();
+    expect(mutex.isLocked()).toBe(false);
+  });
+
+  it("queues concurrent acquires", async () => {
+    const mutex = new AsyncMutex();
+    const order: number[] = [];
+
+    await mutex.acquire();
+    expect(mutex.queueLength).toBe(0);
+
+    const promise1 = mutex.acquire().then(() => order.push(1));
+    const promise2 = mutex.acquire().then(() => order.push(2));
+
+    expect(mutex.queueLength).toBe(2);
+
+    mutex.release();
+    await promise1;
+    expect(order).toEqual([1]);
+
+    mutex.release();
+    await promise2;
+    expect(order).toEqual([1, 2]);
+  });
+
+  it("processes queue in FIFO order", async () => {
+    const mutex = new AsyncMutex();
+    const order: number[] = [];
+
+    await mutex.acquire();
+
+    const promises = [1, 2, 3, 4, 5].map((n) =>
+      mutex.acquire().then(() => {
+        order.push(n);
+      }),
+    );
+
+    expect(mutex.queueLength).toBe(5);
+
+    for (let i = 0; i < 5; i++) {
+      mutex.release();
+      await promises[i];
+    }
+
+    expect(order).toEqual([1, 2, 3, 4, 5]);
+  });
+
+  it("serializes concurrent operations", async () => {
+    const mutex = new AsyncMutex();
+    const results: string[] = [];
+
+    const operation = async (id: string, delay: number) => {
+      await mutex.acquire();
+      try {
+        results.push(`${id}-start`);
+        await new Promise((r) => setTimeout(r, delay));
+        results.push(`${id}-end`);
+      } finally {
+        mutex.release();
+      }
+    };
+
+    await Promise.all([
+      operation("a", 10),
+      operation("b", 5),
+      operation("c", 1),
+    ]);
+
+    expect(results).toEqual([
+      "a-start",
+      "a-end",
+      "b-start",
+      "b-end",
+      "c-start",
+      "c-end",
+    ]);
+  });
+
+  it("handles release without acquire gracefully", () => {
+    const mutex = new AsyncMutex();
+
+    expect(mutex.isLocked()).toBe(false);
+    mutex.release();
+    expect(mutex.isLocked()).toBe(false);
+  });
+});

package/src/utils/async-mutex.ts

@@ -0,0 +1,31 @@
+export class AsyncMutex {
+  private locked = false;
+  private queue: Array<() => void> = [];
+
+  async acquire(): Promise<void> {
+    if (!this.locked) {
+      this.locked = true;
+      return;
+    }
+    return new Promise((resolve) => {
+      this.queue.push(resolve);
+    });
+  }
+
+  release(): void {
+    const next = this.queue.shift();
+    if (next) {
+      next();
+    } else {
+      this.locked = false;
+    }
+  }
+
+  isLocked(): boolean {
+    return this.locked;
+  }
+
+  get queueLength(): number {
+    return this.queue.length;
+  }
+}

package/src/utils/common.ts

@@ -0,0 +1,15 @@
+import type { Logger } from "./logger.js";
+
+export const IS_ROOT =
+  typeof process !== "undefined" &&
+  (process.geteuid?.() ?? process.getuid?.()) === 0;
+
+export function unreachable(value: never, logger: Logger): void {
+  let valueAsString: string;
+  try {
+    valueAsString = JSON.stringify(value);
+  } catch {
+    valueAsString = value;
+  }
+  logger.error(`Unexpected case: ${valueAsString}`);
+}

package/src/utils/gateway.ts

@@ -2,14 +2,17 @@ export function getLlmGatewayUrl(posthogHost: string): string {
   const url = new URL(posthogHost);
   const hostname = url.hostname;
 
+  // Local development (normalize 127.0.0.1 to localhost)
   if (hostname === "localhost" || hostname === "127.0.0.1") {
-    return `${url.protocol}//localhost:3308`;
+    return `${url.protocol}//localhost:3308/twig`;
   }
 
-  // Extract region from hostname (us.posthog.com, eu.posthog.com)
-  // app.posthog.com is legacy US
-  const regionMatch = hostname.match(/^(us|eu)\.posthog\.com$/);
-  const region = regionMatch ? regionMatch[1] : "us";
+  // Docker containers accessing host
+  if (hostname === "host.docker.internal") {
+    return `${url.protocol}//host.docker.internal:3308/twig`;
+  }
 
-  return `https://gateway.${region}.posthog.com`;
+  // Production - extract region from hostname, default to US
+  const region = hostname.match(/^(us|eu)\.posthog\.com$/)?.[1] ?? "us";
+  return `https://gateway.${region}.posthog.com/twig`;
 }

package/src/utils/logger.ts

@@ -1,15 +1,5 @@
 import type { LogLevel as LogLevelType, OnLogCallback } from "../types.js";
 
-/**
- * Simple logger utility with configurable debug mode and external log forwarding
- */
-export enum LogLevel {
-  ERROR = 0,
-  WARN = 1,
-  INFO = 2,
-  DEBUG = 3,
-}
-
 export interface LoggerConfig {
   debug?: boolean;
   prefix?: string;
@@ -30,14 +20,6 @@ export class Logger {
     this.onLog = config.onLog;
   }
 
-  setDebug(enabled: boolean) {
-    this.debugEnabled = enabled;
-  }
-
-  setOnLog(onLog: OnLogCallback | undefined) {
-    this.onLog = onLog;
-  }
-
   private formatMessage(
     level: string,
     message: string,
@@ -87,18 +69,6 @@ export class Logger {
     this.emitLog("debug", message, data);
   }
 
-  log(level: LogLevelType, message: string, data?: unknown, scope?: string) {
-    const originalScope = this.scope;
-    if (scope) {
-      this.scope = scope;
-    }
-    this.emitLog(level, message, data);
-    this.scope = originalScope;
-  }
-
-  /**
-   * Create a child logger with additional prefix and scope
-   */
   child(childPrefix: string): Logger {
     return new Logger({
       debug: this.debugEnabled,