Tracking issue: redesign wizard runs #83776

Briefing

We need to create a proper infra for handling cloud runs for the wizard.

WIP

• feat(wizard): add run registry foundation #85921

Responsibilities

@PostHog/team-growth

• Design and implement a new Wizard Run system (P0)
  • Backend: Implement new wizard run system #85854
  • UI1: Wizard launchpad UI #86677
• Design a data model for communication (P1)
• Richer interface and stateful experience for wizard cloud runs
• Web sockets for bidirectional data

@PostHog/team-wizard-docs

• Context API refactor (P0)
• New data model for bidirectional wizard (P1)
• Headless wizard and rip out TUI from CLI (P1)

Contract (draft)

Concepts

• A workspace contains an user provided project (e.g. a folder with a Next.js project)
• The wizard is a setup agent that runs specific agentic tasks in a workspace (e.g. posthog-integration, audit, etc...)
• The wizard owns its harness, and skills, and operates through the AI gateway for token spend.
• A workspace can be: a local folder in an user's own machine, a git repository, or an uploaded archive.
• A wizard run is an individual execution of the Wizard inside a workspace.
• A wizard run has an environment: local, or cloud.
  • A local environment is the user's own machine.
  • A cloud environment is a PostHog-provisioned sandbox in which we access the workspace.
  • A cloud environment running a wizard execution is called a Wizard Worker.
• The end results of a Wizard Run is a set of Run Artifacts.
• A Run Artifact is a modified version of the original workspace: a git diff, a pull request, or an updated archive.
• A Wizard Run, in any environment, syncs it's internal state with the backend.
  • A local run creates an instance of Wizard Run at startup, and sends updates to the Wizard Run's ID.
  • A cloud run has it's Wizard Run instance created before provisioning a Wizard Worker, and the ID is passed to the Wizard agent, which reuses the Run ID for sending state updates.
  • For a v0, we keep the original state update system. For a v1, we will store state updates for individual Wizard Runs.

Valid configurations:

• Environment = Local
  • Workspace = Local folder
• Environment = Cloud
  • Workspace = Git repository
  • Workspace = Uploaded archive

API

• GET /projects/:projectId/wizard/runs -> list wizard runs
  • ?q=
  • ?page=
  • ?order_by= created_by DESC
• POST /projects/:projectId/wizard/runs -> create a new run
  • body.type=LOCAL|CLOUD -> local run registering a run
  • body.sync_version=v1 -> v1 for legacy state sync, v2 for new dag-based state sync
  • body.
• (?) POST /projects/:projectId/wizard/runs/:runId/state
• (?) GET /projects/:projectId/wizard/runs/:runId/state

In the future:

• ws://(base-url)/projects/:projectId/wizard/runs/:runId/state/ws
  • Used for two-way communication between the wizard and the UI.

Cool ideas

• Diff visualizer. Once an artifact is ready, we can show a diff in the UI.

organically produced ©