@posthog/agent 1.11.0 → 1.13.0

package/README.md

@@ -1,6 +1,6 @@
 # PostHog Agent SDK
 
-TypeScript agent framework that wraps the Claude Agent SDK for PostHog's Array desktop app. Features a Git-based workflow that stores task artifacts alongside your code.
+TypeScript agent framework that wraps the Claude Agent SDK for PostHog's Array desktop app. Features a Git-based task execution system that stores task artifacts alongside your code.
 
 ## Quick Start
 
@@ -11,9 +11,9 @@ bun run example
 
 ## Key Features
 
-- **Git-Based Workflow**: Plans and artifacts stored in `.posthog/` folders and committed to Git
+- **Git-Based Task Execution**: Plans and artifacts stored in `.posthog/` folders and committed to Git
 - **PostHog Integration**: Fetches existing tasks from PostHog API
-- **Configurable Workflows**: Execute tasks via PostHog-defined or local workflows
+- **3-Phase Execution**: Research → Plan → Build with automatic progression
 - **Branch Management**: Automatic branch creation for planning and implementation
 - **Progress Tracking**: Execution status stored in PostHog `TaskRun` records for easy polling
 
@@ -35,12 +35,14 @@ const agent = new Agent({
     },
 });
 
-// Run by workflow
+// Run a task
 const taskId = "task_abc123";
-const workflowId = "workflow_123";
-await agent.runWorkflow(taskId, workflowId, {
+const task = await agent.getPostHogClient()?.fetchTask(taskId);
+
+await agent.runTask(task, {
   repositoryPath: "/path/to/repo",
   permissionMode: PermissionMode.ACCEPT_EDITS,
+  isCloudMode: false,
   autoProgress: true,
 });
 ```
@@ -54,32 +56,13 @@ const agent = new Agent({
 });
 ```
 
-## Workflow
-
-Each task execution creates Git branches:
-
-1. **Planning**: `posthog/task-{id}-planning` - Contains plan in `.posthog/{id}/plan.md`
-2. **Implementation**: `posthog/task-{id}-implementation` - Contains code changes
-
-## Manual Stages and Resume
-
-- Manual stages (no agent, or `is_manual_only`) are stop-points: the SDK will not auto-advance.
-- On manual stages, a PR is opened by default for human review (configurable per stage with `openPullRequest`).
+## Task Execution
 
-Resume from the current stage:
+Each task execution creates Git branches and follows a 3-phase approach:
 
-```typescript
-await agent.runWorkflow(taskId, workflowId, {
-  repositoryPath: "/path/to/repo",
-  permissionMode: PermissionMode.ACCEPT_EDITS,
-  resumeFromCurrentStage: true,
-  autoProgress: true, // ignored on manual stages
-});
-
-// Or explicitly progress via API then resume
-await agent.progressToNextStage(taskId);
-await agent.runWorkflow(taskId, workflowId, { resumeFromCurrentStage: true });
-```
+1. **Research Phase**: Analyzes the codebase and may generate clarifying questions
+2. **Planning Phase**: Creates an implementation plan in `.posthog/{id}/plan.md` on branch `posthog/task-{id}-planning`
+3. **Build Phase**: Implements code changes on branch `posthog/task-{id}-implementation`
 
 ## File System
 
@@ -90,6 +73,7 @@ your-repo/
 │   ├── .gitignore
 │   └── {task-id}/
 │       ├── plan.md
+│       ├── questions.json (if research phase generated questions)
 │       └── context.md (optional)
 └── (your code)
 ```
@@ -111,12 +95,12 @@ const poller = setInterval(async () => {
     new Date(b.created_at).getTime() - new Date(a.created_at).getTime()
   )[0];
   if (latestRun) {
-    renderProgress(latestRun.status, latestRun.log, latestRun.current_stage);
+    renderProgress(latestRun.status, latestRun.log);
   }
 }, 3000);
 
 try {
-  await agent.runWorkflow(taskId, workflowId, { repositoryPath: repoPath });
+  await agent.runTask(task, { repositoryPath: repoPath });
 } finally {
   clearInterval(poller);
 }
@@ -141,46 +125,23 @@ function handleLiveEvent(event: AgentEvent) {
 ## Requirements
 
 - Bun runtime
-- Git repository 
+- Git repository
 - PostHog API access
 - Claude API access via `@anthropic-ai/claude-agent-sdk`
 
+## Configuration Options
 
-## Stage overrides and query overrides
-
-You can customize behavior per workflow stage using `stageOverrides`, and pass low-level model options using `queryOverrides`.
+You can customize behavior using `TaskExecutionOptions`:
 
 ```ts
-await agent.runWorkflow(taskId, workflowId, {
+await agent.runTask(task, {
   repositoryPath: "/path/to/repo",
-  // Global defaults for this run
-  permissionMode: PermissionMode.ACCEPT_EDITS,
-  queryOverrides: { model: 'claude-3-7-sonnet' },
-
-  // Per-stage overrides (keys must match your workflow's stage keys)
-  stageOverrides: {
-    plan: {
-      permissionMode: PermissionMode.PLAN,
-      createPlanningBranch: true,
-      // Only applied during the planning stage
-      queryOverrides: { temperature: 0.2 }
-    },
-    build: {
-      createImplementationBranch: true,
-      openPullRequest: false,
-      // Inject custom MCP servers or any other query option
-      queryOverrides: {
-        mcpServers: {
-          // example: override or add servers
-        }
-      }
-    },
-    complete: {
-      // ensure a PR is opened at the end regardless of edits
-      openPullRequest: true
-    }
+  permissionMode: PermissionMode.ACCEPT_EDITS, // or PLAN, DEFAULT, BYPASS
+  isCloudMode: false, // local execution with pauses between phases
+  autoProgress: true, // automatically progress through phases
+  queryOverrides: {
+    model: 'claude-sonnet-4-5-20250929',
+    temperature: 0.7
   }
 });
 ```
-
-Precedence for query options: base defaults in the SDK < global `queryOverrides` < per-stage `stageOverrides[stageKey].queryOverrides`.

package/dist/_virtual/_commonjsHelpers.js

@@ -0,0 +1,6 @@
+function getDefaultExportFromCjs (x) {
+	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
+}
+
+export { getDefaultExportFromCjs };
+//# sourceMappingURL=_commonjsHelpers.js.map

package/dist/_virtual/_commonjsHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_commonjsHelpers.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;"}

package/dist/_virtual/index.js

@@ -0,0 +1,4 @@
+var secureJsonParse = {exports: {}};
+
+export { secureJsonParse as __module };
+//# sourceMappingURL=index.js.map

package/dist/_virtual/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;"}

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 export { Agent, } from './src/agent.js';
 export { PermissionMode, } from './src/types.js';
 export type { Task, TaskRun, SupportingFile, ExecutionResult, AgentConfig, McpServerConfig, AgentEvent } from './src/types.js';
-export type { WorkflowDefinition, WorkflowStage, WorkflowExecutionOptions, AgentDefinition } from './src/workflow-types.js';
 export { Logger, LogLevel, } from './src/utils/logger.js';
 export type { LoggerConfig } from './src/utils/logger.js';
 export type { ExtractedQuestion, ExtractedQuestionWithAnswer, StructuredExtractor } from './src/structured-extraction.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,OAAO,EACH,KAAK,GACR,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACH,cAAc,GACjB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACR,IAAI,EACJ,OAAO,EACP,cAAc,EACd,eAAe,EACf,WAAW,EACX,eAAe,EACf,UAAU,EACb,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,kBAAkB,EAClB,aAAa,EACb,wBAAwB,EACxB,eAAe,EAChB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACH,MAAM,EACN,QAAQ,GACX,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACR,YAAY,EACf,MAAM,uBAAuB,CAAC;AAG/B,YAAY,EACR,iBAAiB,EACjB,2BAA2B,EAC3B,mBAAmB,EACtB,MAAM,gCAAgC,CAAC;AAGxC,YAAY,EACR,YAAY,EACZ,UAAU,EACV,aAAa,EAChB,MAAM,uBAAuB,CAAC;AAG/B,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AAGxE,YAAY,EACR,IAAI,EACJ,YAAY,EACZ,SAAS,EACT,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,gBAAgB,EAChB,QAAQ,EACR,cAAc,EACd,aAAa,EACb,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,aAAa,EACb,gBAAgB,EAChB,gBAAgB,GACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,OAAO,EACH,KAAK,GACR,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACH,cAAc,GACjB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACR,IAAI,EACJ,OAAO,EACP,cAAc,EACd,eAAe,EACf,WAAW,EACX,eAAe,EACf,UAAU,EACb,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACH,MAAM,EACN,QAAQ,GACX,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACR,YAAY,EACf,MAAM,uBAAuB,CAAC;AAG/B,YAAY,EACR,iBAAiB,EACjB,2BAA2B,EAC3B,mBAAmB,EACtB,MAAM,gCAAgC,CAAC;AAGxC,YAAY,EACR,YAAY,EACZ,UAAU,EACV,aAAa,EAChB,MAAM,uBAAuB,CAAC;AAG/B,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AAGxE,YAAY,EACR,IAAI,EACJ,YAAY,EACZ,SAAS,EACT,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,gBAAgB,EAChB,QAAQ,EACR,cAAc,EACd,aAAa,EACb,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,aAAa,EACb,gBAAgB,EAChB,gBAAgB,GACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC"}