@posthog/wizard 2.76.1 → 2.78.0

package/README.md

@@ -155,7 +155,7 @@ route review to their owning team instead.
 | Path | Owning team |
 |---|---|
 | `*` (everything else, including all other programs) | `@PostHog/team-wizard-docs` |
-| `src/lib/agent/` | `@PostHog/team-wizard-docs` |
+| `src/agent/` | `@PostHog/team-wizard-docs` |
 | `src/lib/programs/posthog-integration/` | `@PostHog/team-wizard-docs` |
 | `src/lib/programs/error-tracking-upload-source-maps/` | `@PostHog/team-error-tracking` |
 | `src/lib/programs/mcp-analytics/` | `@PostHog/team-mcp-analytics` |
@@ -267,18 +267,29 @@ When creating your personal API key, grant it the wizard's base scope set:
 ```
 user:read project:read organization:read llm_gateway:read query:read
 dashboard:write insight:write notebook:write event_definition:write
-health_issue:read wizard_session:read wizard_session:write
+health_issue:read wizard_session:read wizard_session:write wizard_run:write
 ```
 
-The source of truth is `WIZARD_OAUTH_SCOPES` in `src/lib/constants.ts`, which
+The source of truth is `WIZARD_OAUTH_SCOPES` in `src/shared/constants.ts`, which
 documents why each scope is needed — if this block drifts, trust the code.
 Some programs request more on top (`PROGRAM_SCOPE_ADDITIONS` in
 `src/lib/oauth/program-scopes.ts`); the default integration flow adds
 `integration:read` and `external_data_source:read` /
 `external_data_source:write`.
 
+The `wizard-run-sync` flag selects remote synchronization: `wizard-session`
+(the default) uses WizardSession; `wizard-run` uses WizardRun. In the latter
+mode, local executions synchronize tasks and terminal status. Cloud executions
+require an explicit `POSTHOG_WIZARD_RUN_ID` assignment and leave terminal status
+to their worker. See [WizardRun synchronization](docs/local-dev.md#wizardrun-synchronization)
+for limits, shutdown behavior, migration compatibility, and deployment checks.
+
 ### OAuth app scope ceiling
 
+Both the interactive and cloud Wizard OAuth apps must allow `wizard_run:write`
+in every deployed region. Existing tokens need renewed authorization; refresh
+does not add the grant. Run synchronization needs no read scope.
+
 The wizard's OAuth app on the PostHog side caps the scopes its tokens may
 carry (`OAuthApplication.scopes`). Any scope requested in this repo (see
 `src/lib/oauth/program-scopes.ts`) must be grantable under that ceiling, or
@@ -291,7 +302,7 @@ are clamped silently (`clamp_scopes_to_ceiling`) — neither path errors;
 `/oauth/token` just returns a smaller `scope`. So never assume the token
 carries what was requested: the token response's `scope` field is the truth.
 The wizard diffs granted vs requested at login (`missingOAuthScopes` in
-`src/utils/oauth.ts`), warns the user which permissions are missing, and emits
+`src/shared/utils/oauth.ts`), warns the user which permissions are missing, and emits
 `wizard: oauth grant narrowed` so narrowed runs are countable in analytics.
 The diff also rides on the session (`credentials.missingScopes`), so when a
 run does fail on a scope-gated step, the error names the missing permission
@@ -310,7 +321,7 @@ every scope in `WIZARD_OAUTH_SCOPES`:
 
 ```
 python manage.py seed_oauth_app_scopes --client-id <id> --dry-run \
-  --scopes "@default,llm_gateway:read,wizard_session:read,wizard_session:write,user:read,project:read,organization:read,query:read,dashboard:write,insight:write,notebook:write,event_definition:write,health_issue:read"
+  --scopes "@default,llm_gateway:read,wizard_session:read,wizard_session:write,wizard_run:write,user:read,project:read,organization:read,query:read,dashboard:write,insight:write,notebook:write,event_definition:write,health_issue:read"
 ```
 
 then re-run without `--dry-run`. Keep `@default` in the list — dropping it
@@ -396,7 +407,7 @@ and set up the general flow of the application.
 ## Analytics
 
 Did you know you can capture PostHog events even for smaller, supporting
-products like a command line tool? `src/utils/analytics.ts` is a great example
+products like a command line tool? `src/shared/utils/analytics.ts` is a great example
 of how to do it.
 
 This file wraps `posthog-node` with some convenience functions to set up an
@@ -405,19 +416,19 @@ wizard alongside all of our other PostHog product data, and this is very
 powerful. For example: we could show in-product surveys to people who have used
 the wizard to improve the experience.
 
-When the user authenticates, the wizard also streams live run state — current
+With `wizard-run-sync=wizard-session`, the wizard streams live run state — current
 phase, task list, planned events — to `POST /api/projects/{id}/wizard/sessions/`
 so the PostHog web app can render real-time progress. Updates are debounced
 (250ms) with phase changes flushed immediately; failures fall back silently to
 the wizard's debug log without disturbing the TUI. Pass `--no-telemetry` (or
-set `POSTHOG_WIZARD_NO_TELEMETRY=1`) to disable.
+set `POSTHOG_WIZARD_NO_TELEMETRY=1`) to disable either remote transport.
 
 ## Leave rules behind
 
 Supporting agent sessions after we leave is important. There are plenty of ways
 to break or misconfigure PostHog, so guarding against this is key.
 
-`src/utils/rules/add-editor-rules.ts` demonstrates how to dynamically construct
+`src/shared/utils/rules/add-editor-rules.ts` demonstrates how to dynamically construct
 rules files and store them in the project's `.cursor/rules` directory.
 
 ## Prompts and LLM interactions
@@ -433,7 +444,7 @@ _If_ they are well prompted.
 chaotic process. Every wizard session gets the same prompt, tailored to the
 specific files in the project.
 
-These prompts are channeled using `src/utils/query.ts` to an LLM interface we
+These prompts are channeled using `src/shared/utils/query.ts` to an LLM interface we
 host. This gives us more control: we can be certain of the model version and
 provider which interpret the prompts and modify the files. This way, we can find
 the right tools for the job and again, apply them consistently.
@@ -450,14 +461,14 @@ orchestrates that journey, but the raw value should _never_ enter the LLM
 conversation, where it would be sent to the model provider, written to
 transcripts, and captured in logs.
 
-`src/lib/secret-vault.ts` is a small, reusable pattern for exactly this. It's a
+`src/shared/secret-vault.ts` is a small, reusable pattern for exactly this. It's a
 session-scoped, in-memory vault: a tool that handles a secret calls `put()` to
 store the raw value and hands the agent an opaque `secret:<uuid>` reference
 instead. The agent passes that ref between tools as if it were the value; the
 host resolves it back to the real secret only at the last moment, inside the
 process, when it writes the file.
 
-Two tools in `src/lib/wizard-tools.ts` form the ends of that pipe:
+Two tools in `src/agent/tools/tools.ts` form the ends of that pipe:
 
 - `wizard_ask` with `sensitive: true` vaults the user's typed answer and returns
   `{ secretRef: "secret:..." }` to the agent rather than the string.
@@ -504,7 +515,11 @@ Path aliases defined in `tsconfig.build.json`, resolved by tsdown:
 |---|---|
 | `@env` | `src/env.ts` |
 | `@lib/*` | `src/lib/*` |
-| `@utils/*` | `src/utils/*` |
+| `@agent` | `src/agent/index.ts`, the agent's runtime entry; the only agent import outside `src/agent` besides types |
+| `@agent/types` | `src/agent/types.ts`, type-only |
+| `@agent/*` | `src/agent/*`, inside `src/agent` and its tests only |
+| `@shared/*` | `src/shared/*` |
+| `@utils/*` | `src/shared/utils/*` |
 | `@ui/*` | `src/ui/*` |
 | `@steps/*` | `src/steps/*` |
 | `@frameworks/*` | `src/frameworks/*` |
@@ -605,7 +620,7 @@ To make your version of a tool usable with a one-line `npx` command:
 
 # Health checks
 
-`src/lib/health-checks/` checks skills download origins before the wizard runs.
+`src/shared/health-checks/` checks skills download origins before the wizard runs.
 The entry point is `evaluateWizardReadiness()`, which only blocks on skill downloads:
 
 | Decision            | Meaning                                                         |
@@ -645,7 +660,7 @@ gateway URL and reports an unavailable gateway through the existing error path.
 
 `skillsOrigin` is one entry covering two origins: skills are published to
 GitHub Releases and an AWS mirror under the same filenames, and downloads fail
-over between them (`src/lib/fetch-retry.ts`). Both are probed in parallel, so
+over between them (`src/shared/fetch-retry.ts`). Both are probed in parallel, so
 the key only reports **Down** when neither origin answers — a GitHub Releases
 outage on its own doesn't block a run, including a 403 or 404, which is as
 often about the origin (expired asset redirect, blocked region, a publish that

package/dist/README.md

@@ -12,17 +12,18 @@ real ink render) and is driven purely by store state manipulation; a PTY parent
 ([`e2e-harness/tui-capture.ts`](../e2e-harness/tui-capture.ts), node-pty +
 `@xterm/headless`) captures the real rendered screen.
 
-| Script                          | What it does                                                                                                                                                                                          | Needs                                                              |
-| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| **`tui-host.no-jest.ts`** | Real TUI host: `MODE=fixed` follows a profile; `MODE=serve` accepts socket commands. | `APP_DIR`, `PROJECT_ID`, key for a full run, `SNAP_CTRL`; run under a PTY, with `CONTROL_SOCK` in serve mode |
-| **`tui-snapshots.no-jest.ts`** | Runs the fixed host and saves colored `SNAP_OUT/NN-<screen>.ans` frames, including within-screen progress. | `SNAP_OUT`, `APP_DIR`, `PROJECT_ID`, `POSTHOG_KEY_FILE` or `POSTHOG_PERSONAL_API_KEY` |
-| **`wizard-ci-mcp.no-jest.ts`** | Stdio MCP server: `open_app`, `read_state`, `perform_action`, `render_screen`, `run_agent`. Screen output is plain text. | Spawns the host; `open_app` requires `appDir` and `projectId`, with optional `keyFile`, `apiKey`, `region` |
-| **`wizard-ci-explore.no-jest.ts`** | `pnpm wizard-ci-explore`: opens an app, confirms setup, reads state, prints one frame, and exits. It does not run the agent. | `APP_DIR`, `PROJECT_ID`; optional `POSTHOG_KEY_FILE` |
+| Script                             | What it does                                                                                                                                                                                                                             | Needs                                                                                                        |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| **`tui-host.no-jest.ts`**          | Real TUI host: `MODE=fixed` follows a profile; `MODE=serve` accepts socket commands.                                                                                                                                                     | `APP_DIR`, `PROJECT_ID`, key for a full run, `SNAP_CTRL`; run under a PTY, with `CONTROL_SOCK` in serve mode |
+| **`tui-snapshots.no-jest.ts`**     | Runs the fixed host and saves colored `SNAP_OUT/NN-<screen>.ans` frames, including within-screen progress.                                                                                                                               | `SNAP_OUT`, `APP_DIR`, `PROJECT_ID`, `POSTHOG_KEY_FILE` or `POSTHOG_PERSONAL_API_KEY`                        |
+| **`wizard-ci-mcp.no-jest.ts`**     | Stdio MCP server: `open_app`, `read_state`, `perform_action`, `render_screen`, `run_agent`. Screen output is plain text.                                                                                                                 | Spawns the host; `open_app` requires `appDir` and `projectId`, with optional `keyFile`, `apiKey`, `region`   |
+| **`chunk-manifest.no-jest.ts`**    | Prints a structural manifest of `dist/`: per chunk, the source files it contains and the chunks it imports, hash suffixes stripped. `--summary` prints chunk names plus the sorted source set. A reading tool, nothing diffs its output. | A built `dist/`                                                                                              |
+| **`wizard-ci-explore.no-jest.ts`** | `pnpm wizard-ci-explore`: opens an app, confirms setup, reads state, prints one frame, and exits. It does not run the agent.                                                                                                             | `APP_DIR`, `PROJECT_ID`; optional `POSTHOG_KEY_FILE`                                                         |
 
 > You usually don't call these directly — `pnpm wizard-ci-snapshots` (in
 > [wizard-workbench](https://github.com/PostHog/wizard-workbench)) orchestrates
-> the snapshot route; the MCP server is registered in this repo's `.mcp.json` and
-> used via the `exploring-the-wizard` skill.
+> the snapshot route; the MCP server is registered in this repo's `.mcp.json`
+> and used via the `exploring-the-wizard` skill.
 
 `PROGRAM`, `SNAP_HARNESS`, `SNAP_SEQUENCE`, `SNAP_MODEL`, and `E2E_ASK` are host
 environment inputs, inherited from the launcher; they are not MCP tool
@@ -34,11 +35,11 @@ before choosing credentials or an EU project.
 ## Credentials for full agent runs
 
 Full TUI host and snapshot runs require both the personal API key (or
-`POSTHOG_KEY_FILE`) and `WIZARD_CI_GATEWAY_TOKEN_FILE`, plus `PROJECT_ID`.
-For MCP runs, pass the personal key through `open_app` and set the gateway
-token file path in the server environment before launch. Restart the server
-after changing it; the gateway path is not an MCP tool argument.
-Detection-only exploration does not need either secret. See
+`POSTHOG_KEY_FILE`) and `WIZARD_CI_GATEWAY_TOKEN_FILE`, plus `PROJECT_ID`. For
+MCP runs, pass the personal key through `open_app` and set the gateway token
+file path in the server environment before launch. Restart the server after
+changing it; the gateway path is not an MCP tool argument. Detection-only
+exploration does not need either secret. See
 [local credential setup](../docs/local-dev.md#credentials-for-local-ci-and-headless-runs).
 
 ## Background
@@ -46,5 +47,5 @@ Detection-only exploration does not need either secret. See
 The control plane lives in [`e2e-harness/`](../e2e-harness/) — out of `src/`, so
 none of it ships in prod. `WizardCiDriver` (read/act over the store), the
 screen→action registry, the e2e profiles, and `tui-capture` (real-TUI PTY
-capture). See [`ARCHITECTURE.md`](../e2e-harness/ARCHITECTURE.md) for how the two
-routes drive these (env strip, scoped project id, gotchas).
+capture). See [`ARCHITECTURE.md`](../e2e-harness/ARCHITECTURE.md) for how the
+two routes drive these (env strip, scoped project id, gotchas).