@posthog/wizard 2.77.0 → 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/{add-mcp-server-to-clients-BnRyE4pw.js → add-mcp-server-to-clients-JMv8LP-O.js}

@@ -1,8 +1,9 @@
 import { t as __exportAll } from "./rolldown-runtime-B_-DWIq7.js";
-import { Ct as runtimeEnv, p as getUI, r as debug } from "./debug-B4kzIZPi.js";
-import { n as analytics } from "./analytics-C67F2vee.js";
-import { n as openTrackedLink, t as withProgress } from "./telemetry-BRnxBRWK.js";
-import { a as getNativeHTTPServerConfig, d as scrubHomePaths, i as getDefaultServerConfig, l as namesWithStatus, p as toClientResult, r as buildMCPUrl, s as expectedFailureHint, t as ALL_FEATURE_VALUES, u as redactSecrets } from "./defaults-4c4YwTmW.js";
+import { r as debug, v as runtimeEnv } from "./debug-Ch4BDOtD.js";
+import { n as analytics } from "./analytics-CHCZ_qUR.js";
+import { n as openTrackedLink, t as withProgress } from "./telemetry-D6ruCtnv.js";
+import { t as getUI } from "./ui-BBVuTM1v.js";
+import { a as getNativeHTTPServerConfig, d as scrubHomePaths, i as getDefaultServerConfig, l as namesWithStatus, p as toClientResult, r as buildMCPUrl, s as expectedFailureHint, t as ALL_FEATURE_VALUES, u as redactSecrets } from "./defaults-C6J7yL4O.js";
 import * as fs$2 from "fs";
 import * as path$3 from "path";
 import * as os from "node:os";
@@ -1214,4 +1215,4 @@ const removeMCPServer = async (clients, local) => {
 //#endregion
 export { getSupportedClients as a, removeMCPServer as c, getInstalledClients as i, removeMCPServerFromClientsStep as l, addMCPServerToClientsStep as n, getSupportedPluginClients as o, add_mcp_server_to_clients_exports as r, installPlugins as s, addMCPServer as t, isPluginCapable as u };
 
-//# sourceMappingURL=add-mcp-server-to-clients-BnRyE4pw.js.map
+//# sourceMappingURL=add-mcp-server-to-clients-JMv8LP-O.js.map