@posthog/agent 2.0.0 → 2.0.1

package/dist/types.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Stored custom notification following ACP extensibility model.
+ * Custom notifications use underscore-prefixed methods (e.g., `_posthog/phase_start`).
+ * See: https://agentclientprotocol.com/docs/extensibility
+ */
+interface StoredNotification {
+    type: "notification";
+    /** When this notification was stored */
+    timestamp: string;
+    /** JSON-RPC 2.0 notification (no id field = notification, not request) */
+    notification: {
+        jsonrpc: "2.0";
+        method: string;
+        params?: Record<string, unknown>;
+    };
+}
+/**
+ * Type alias for stored log entries.
+ */
+type StoredEntry = StoredNotification;
+interface Task {
+    id: string;
+    task_number?: number;
+    slug?: string;
+    title: string;
+    description: string;
+    origin_product: "error_tracking" | "eval_clusters" | "user_created" | "support_queue" | "session_summaries";
+    github_integration?: number | null;
+    repository: string;
+    json_schema?: Record<string, unknown> | null;
+    created_at: string;
+    updated_at: string;
+    created_by?: {
+        id: number;
+        uuid: string;
+        distinct_id: string;
+        first_name: string;
+        email: string;
+    };
+    latest_run?: TaskRun;
+}
+type ArtifactType = "plan" | "context" | "reference" | "output" | "artifact" | "tree_snapshot";
+interface TaskRunArtifact {
+    name: string;
+    type: ArtifactType;
+    size?: number;
+    content_type?: string;
+    storage_path?: string;
+    uploaded_at?: string;
+}
+type TaskRunStatus = "not_started" | "queued" | "in_progress" | "completed" | "failed" | "cancelled";
+type TaskRunEnvironment = "local" | "cloud";
+interface TaskRun {
+    id: string;
+    task: string;
+    team: number;
+    branch: string | null;
+    stage: string | null;
+    environment: TaskRunEnvironment;
+    status: TaskRunStatus;
+    log_url: string;
+    error_message: string | null;
+    output: Record<string, unknown> | null;
+    state: Record<string, unknown>;
+    artifacts?: TaskRunArtifact[];
+    created_at: string;
+    updated_at: string;
+    completed_at: string | null;
+}
+interface ProcessSpawnedCallback {
+    onProcessSpawned?: (info: {
+        pid: number;
+        command: string;
+        sessionId?: string;
+    }) => void;
+    onProcessExited?: (pid: number) => void;
+}
+interface TaskExecutionOptions {
+    repositoryPath?: string;
+    adapter?: "claude" | "codex";
+    model?: string;
+    codexBinaryPath?: string;
+    processCallbacks?: ProcessSpawnedCallback;
+}
+type LogLevel = "debug" | "info" | "warn" | "error";
+type OnLogCallback = (level: LogLevel, scope: string, message: string, data?: unknown) => void;
+interface PostHogAPIConfig {
+    apiUrl: string;
+    getApiKey: () => string;
+    projectId: number;
+}
+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;
+}
+interface AgentConfig {
+    posthog?: PostHogAPIConfig;
+    /** OTEL transport config for shipping logs to PostHog Logs */
+    otelTransport?: OtelTransportConfig;
+    debug?: boolean;
+    onLog?: OnLogCallback;
+}
+interface DeviceInfo {
+    type: "local" | "cloud";
+    name?: string;
+}
+type AgentMode = "interactive" | "background";
+type FileStatus = "A" | "M" | "D";
+interface FileChange {
+    path: string;
+    status: FileStatus;
+}
+interface TreeSnapshot {
+    treeHash: string;
+    baseCommit: string | null;
+    archiveUrl?: string;
+    changes: FileChange[];
+    timestamp: string;
+    interrupted?: boolean;
+}
+interface TreeSnapshotEvent extends TreeSnapshot {
+    device?: DeviceInfo;
+}
+
+export type { AgentConfig, AgentMode, ArtifactType, DeviceInfo, FileChange, FileStatus, LogLevel, OnLogCallback, OtelTransportConfig, PostHogAPIConfig, ProcessSpawnedCallback, StoredEntry, StoredNotification, Task, TaskExecutionOptions, TaskRun, TaskRunArtifact, TaskRunEnvironment, TaskRunStatus, TreeSnapshot, TreeSnapshotEvent };

package/dist/types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,18 +1,53 @@
 {
   "name": "@posthog/agent",
-  "version": "2.0.0",
-  "repository": "https://github.com/PostHog/array",
+  "version": "2.0.1",
+  "repository": "https://github.com/PostHog/twig",
   "description": "TypeScript agent framework wrapping Claude Agent SDK with Git-based task execution for PostHog",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.js"
+      "import": "./dist/index.js"
+    },
+    "./agent": {
+      "types": "./dist/agent.d.ts",
+      "import": "./dist/agent.js"
+    },
+    "./gateway-models": {
+      "types": "./dist/gateway-models.d.ts",
+      "import": "./dist/gateway-models.js"
+    },
+    "./posthog-api": {
+      "types": "./dist/posthog-api.d.ts",
+      "import": "./dist/posthog-api.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
+    "./adapters/claude/questions/utils": {
+      "types": "./dist/adapters/claude/questions/utils.d.ts",
+      "import": "./dist/adapters/claude/questions/utils.js"
+    },
+    "./adapters/claude/permissions/permission-options": {
+      "types": "./dist/adapters/claude/permissions/permission-options.d.ts",
+      "import": "./dist/adapters/claude/permissions/permission-options.js"
+    },
+    "./adapters/claude/tools": {
+      "types": "./dist/adapters/claude/tools.d.ts",
+      "import": "./dist/adapters/claude/tools.js"
+    },
+    "./adapters/claude/conversion/tool-use-to-acp": {
+      "types": "./dist/adapters/claude/conversion/tool-use-to-acp.d.ts",
+      "import": "./dist/adapters/claude/conversion/tool-use-to-acp.js"
+    },
+    "./server": {
+      "types": "./dist/server/agent-server.d.ts",
+      "import": "./dist/server/agent-server.js"
     }
   },
+  "bin": {
+    "agent-server": "./dist/server/bin.js"
+  },
   "type": "module",
   "keywords": [
     "posthog",
@@ -30,21 +65,37 @@
   "devDependencies": {
     "@changesets/cli": "^2.27.8",
     "@types/bun": "latest",
+    "@types/tar": "^6.1.13",
     "minimatch": "^10.0.3",
+    "msw": "^2.12.7",
     "tsup": "^8.5.1",
     "tsx": "^4.20.6",
-    "typescript": "^5.5.0"
+    "typescript": "^5.5.0",
+    "vitest": "^2.1.8"
   },
   "dependencies": {
-    "@agentclientprotocol/sdk": "^0.5.1",
-    "@anthropic-ai/claude-agent-sdk": "^0.1.55",
+    "@opentelemetry/api-logs": "^0.208.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.208.0",
+    "@opentelemetry/resources": "^2.0.0",
+    "@opentelemetry/sdk-logs": "^0.208.0",
+    "@opentelemetry/semantic-conventions": "^1.28.0",
+    "@agentclientprotocol/sdk": "^0.14.0",
+    "@anthropic-ai/claude-agent-sdk": "0.2.12",
     "@anthropic-ai/sdk": "^0.71.0",
-    "@modelcontextprotocol/sdk": "^1.23.0",
+    "@hono/node-server": "^1.19.9",
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "@types/jsonwebtoken": "^9.0.10",
+    "commander": "^14.0.2",
     "diff": "^8.0.2",
     "dotenv": "^17.2.3",
+    "hono": "^4.11.7",
+    "jsonwebtoken": "^9.0.2",
+    "tar": "^7.5.0",
     "uuid": "13.0.0",
     "yoga-wasm-web": "^0.3.3",
-    "zod": "^3.24.1"
+    "zod": "^3.24.1",
+    "@posthog/shared": "1.0.0",
+    "@twig/git": "1.0.0"
   },
   "files": [
     "dist/**/*",
@@ -58,7 +109,8 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "typecheck": "pnpm exec tsc --noEmit",
-    "example": "tsx example.ts"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "pnpm exec tsc --noEmit"
   }
 }

package/src/acp-extensions.ts

@@ -5,6 +5,10 @@
  * - Custom notification methods are prefixed with `_posthog/`
  * - Custom data can be attached via `_meta` fields
  *
+ * Note: When using `extNotification()` from the ACP SDK, it automatically
+ * adds an extra underscore prefix (e.g., `_posthog/tree_snapshot` becomes
+ * `__posthog/tree_snapshot` in the log). Code that reads logs should handle both.
+ *
  * See: https://agentclientprotocol.com/docs/extensibility
  */
 
@@ -13,23 +17,57 @@
  * Used with AgentSideConnection.extNotification() or Client.extNotification()
  */
 export const POSTHOG_NOTIFICATIONS = {
-  /** Git branch was created */
+  /** Git branch was created for a task */
   BRANCH_CREATED: "_posthog/branch_created",
-  /** Task run has started */
+
+  /** Task run has started execution */
   RUN_STARTED: "_posthog/run_started",
-  /** Task has completed */
+
+  /** Task has completed (success or failure) */
   TASK_COMPLETE: "_posthog/task_complete",
+
   /** Error occurred during task execution */
   ERROR: "_posthog/error",
-  /** Console/log output */
+
+  /** Console/log output from the agent */
   CONSOLE: "_posthog/console",
-  /** SDK session ID notification (for resumption) */
+
+  /** Maps taskRunId to agent's sessionId and adapter type (for resumption) */
   SDK_SESSION: "_posthog/sdk_session",
+
+  /** Tree state snapshot captured (git tree hash + file archive) */
+  TREE_SNAPSHOT: "_posthog/tree_snapshot",
+
+  /** Agent mode changed (interactive/background) */
+  MODE_CHANGE: "_posthog/mode_change",
+
+  /** Request to resume a session from previous state */
+  SESSION_RESUME: "_posthog/session/resume",
+
+  /** User message sent from client to agent */
+  USER_MESSAGE: "_posthog/user_message",
+
+  /** Request to cancel current operation */
+  CANCEL: "_posthog/cancel",
+
+  /** Request to close the session */
+  CLOSE: "_posthog/close",
+
+  /** Agent status update (thinking, working, etc.) */
+  STATUS: "_posthog/status",
+
+  /** Task-level notification (progress, milestones) */
+  TASK_NOTIFICATION: "_posthog/task_notification",
+
+  /** Marks a boundary for log compaction */
+  COMPACT_BOUNDARY: "_posthog/compact_boundary",
 } as const;
 
 export type PostHogNotificationType =
   (typeof POSTHOG_NOTIFICATIONS)[keyof typeof POSTHOG_NOTIFICATIONS];
 
+// --- Payload types for each notification ---
+
 export interface BranchCreatedPayload {
   branch: string;
 }
@@ -40,9 +78,6 @@ export interface RunStartedPayload {
   taskId?: string;
 }
 
-/**
- * Payload for task complete notification
- */
 export interface TaskCompletePayload {
   sessionId: string;
   taskId: string;
@@ -54,21 +89,61 @@ export interface ErrorNotificationPayload {
   error?: unknown;
 }
 
-/**
- * Console output for a session
- */
 export interface ConsoleNotificationPayload {
   sessionId: string;
   level: "debug" | "info" | "warn" | "error";
   message: string;
 }
 
-/**
- * Maps a session ID to a SDKs session ID
- */
 export interface SdkSessionPayload {
+  taskRunId: string;
+  sessionId: string;
+  adapter: "claude" | "codex";
+}
+
+export interface TreeSnapshotPayload {
+  treeHash: string;
+  baseCommit: string | null;
+  archiveUrl?: string;
+  changes: Array<{ path: string; status: "A" | "M" | "D" }>;
+  timestamp: string;
+  interrupted?: boolean;
+  device?: {
+    type: "local" | "cloud";
+    name?: string;
+  };
+}
+
+export interface ModeChangePayload {
+  mode: "interactive" | "background";
+  previous_mode: "interactive" | "background";
+}
+
+export interface SessionResumePayload {
+  sessionId: string;
+  fromSnapshot?: string;
+}
+
+export interface UserMessagePayload {
+  content: string;
+}
+
+export interface StatusPayload {
+  sessionId: string;
+  status: string;
+  message?: string;
+}
+
+export interface TaskNotificationPayload {
+  sessionId: string;
+  type: string;
+  message?: string;
+  data?: Record<string, unknown>;
+}
+
+export interface CompactBoundaryPayload {
   sessionId: string;
-  sdkSessionId: string;
+  timestamp: string;
 }
 
 export type PostHogNotificationPayload =
@@ -77,4 +152,11 @@ export type PostHogNotificationPayload =
   | TaskCompletePayload
   | ErrorNotificationPayload
   | ConsoleNotificationPayload
-  | SdkSessionPayload;
+  | SdkSessionPayload
+  | TreeSnapshotPayload
+  | ModeChangePayload
+  | SessionResumePayload
+  | UserMessagePayload
+  | StatusPayload
+  | TaskNotificationPayload
+  | CompactBoundaryPayload;