From 446d55932c6bd1340ef0e4082074b760357dc58c Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Wed, 15 Jul 2026 14:27:57 -0400 Subject: [PATCH 1/3] feat(orchestrator): fail the run properly on a missing skill variant MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replaces the dev/CI-only throw with an unconditional wizardAbort — same behavior on every build (no tree-shake gate to maintain): the user gets the error outro pointing at wizard@posthog.com, the WizardError context carries the misses, and the per-miss log + analytics capture stay. Generated-By: PostHog Code Task-Id: fafc230d-6f14-4e4d-9462-0e7f18a1eec1 --- .../orchestrator/orchestrator-runner.ts | 26 ++++++++----------- 1 file changed, 11 insertions(+), 15 deletions(-) diff --git a/src/lib/agent/runner/sequence/orchestrator/orchestrator-runner.ts b/src/lib/agent/runner/sequence/orchestrator/orchestrator-runner.ts index 61b737113..5af4b51b3 100644 --- a/src/lib/agent/runner/sequence/orchestrator/orchestrator-runner.ts +++ b/src/lib/agent/runner/sequence/orchestrator/orchestrator-runner.ts @@ -13,7 +13,6 @@ import { randomUUID } from 'crypto'; import { existsSync, rmSync } from 'fs'; import * as path from 'path'; -import { IS_PRODUCTION_BUILD } from '@env'; import { OutroKind, type WizardSession } from '@lib/wizard-session'; import { installSkillById, @@ -24,6 +23,7 @@ import { getUI } from '@ui'; import { analytics } from '@utils/analytics'; import { ciExcludedTaskTypes } from '@utils/ci-flag-overrides'; import { logToFile } from '@utils/debug'; +import { wizardAbort, WizardError } from '@utils/wizard-abort'; import type { ProgramConfig } from '@lib/programs/program-step'; import type { BootstrapResult } from '../../shared/types'; import { @@ -248,12 +248,7 @@ export async function runOrchestrator( ); } - // Preflight every task's mini-skills. A missing variant means the task runs - // skill-less — a silent zero-diff — so log + capture it on every build. In - // dev and CI the run then crashes so the gap can't slip through a test pass; - // the throw sits behind !IS_PRODUCTION_BUILD, which tsdown inlines to a - // literal, so it is stripped from the published bundle (real users get the - // degraded run, never a crash). + // Preflight every task's mini-skills: a miss would run tasks skill-less, so fail properly instead. const missingVariants: string[] = []; for (const type of registry.types) { for (const skillId of registry.get(type)?.skills ?? []) { @@ -273,14 +268,15 @@ export async function runOrchestrator( }); } } - if (!IS_PRODUCTION_BUILD && missingVariants.length > 0) { - throw new Error( - `Orchestrator preflight: no skill variant for ${missingVariants.join( - ', ', - )} (framework=${ - session.skillId ?? 'none' - }) — fix the context-mill menu or the framework mapping.`, - ); + if (missingVariants.length > 0) { + await wizardAbort({ + message: + 'Setup instructions for this project failed to download.\nPlease try again, or contact wizard@posthog.com.', + error: new WizardError('Orchestrator preflight: skill variant missing', { + missing: missingVariants.join(', '), + framework: session.skillId, + }), + }); } // The client injects the basics (project context + the I/O contract) around From c8a54c44effe32a90efdc12b9b54503fc0731a7f Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Wed, 15 Jul 2026 14:33:56 -0400 Subject: [PATCH 2/3] feat(orchestrator): point the preflight failure at self-serve fallbacks The abort outro now links the agent-skills repo (github.com/PostHog/skills) and the manual install docs alongside the wizard@posthog.com contact. Generated-By: PostHog Code Task-Id: fafc230d-6f14-4e4d-9462-0e7f18a1eec1 --- .../runner/sequence/orchestrator/orchestrator-runner.ts | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/lib/agent/runner/sequence/orchestrator/orchestrator-runner.ts b/src/lib/agent/runner/sequence/orchestrator/orchestrator-runner.ts index 5af4b51b3..3f7fcf081 100644 --- a/src/lib/agent/runner/sequence/orchestrator/orchestrator-runner.ts +++ b/src/lib/agent/runner/sequence/orchestrator/orchestrator-runner.ts @@ -271,7 +271,12 @@ export async function runOrchestrator( if (missingVariants.length > 0) { await wizardAbort({ message: - 'Setup instructions for this project failed to download.\nPlease try again, or contact wizard@posthog.com.', + 'Setup instructions for this project failed to download.\n' + + 'Please try again, or contact wizard@posthog.com.\n\n' + + 'You can also set up with your agent by downloading the skills here:\n' + + ' https://github.com/PostHog/skills\n' + + 'or integrate manually here:\n' + + ' https://posthog.com/docs/getting-started/install', error: new WizardError('Orchestrator preflight: skill variant missing', { missing: missingVariants.join(', '), framework: session.skillId, From 17d972157e351c29a1aa301cc8cdd29d41999054 Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Wed, 15 Jul 2026 14:37:58 -0400 Subject: [PATCH 3/3] fix(orchestrator): correct the preflight fallback links Skills download points at context-mill releases (where skills actually publish), and the manual-setup link uses the framework's own docsUrl from FRAMEWORK_REGISTRY, falling back to the generic docs when detection found no framework. Generated-By: PostHog Code Task-Id: fafc230d-6f14-4e4d-9462-0e7f18a1eec1 --- .../sequence/orchestrator/orchestrator-runner.ts | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/src/lib/agent/runner/sequence/orchestrator/orchestrator-runner.ts b/src/lib/agent/runner/sequence/orchestrator/orchestrator-runner.ts index 3f7fcf081..a7a10c17b 100644 --- a/src/lib/agent/runner/sequence/orchestrator/orchestrator-runner.ts +++ b/src/lib/agent/runner/sequence/orchestrator/orchestrator-runner.ts @@ -14,6 +14,8 @@ import { randomUUID } from 'crypto'; import { existsSync, rmSync } from 'fs'; import * as path from 'path'; import { OutroKind, type WizardSession } from '@lib/wizard-session'; +import { POSTHOG_DOCS_URL, type Integration } from '@lib/constants'; +import { FRAMEWORK_REGISTRY } from '@lib/registry'; import { installSkillById, fetchSkillMenu, @@ -269,14 +271,18 @@ export async function runOrchestrator( } } if (missingVariants.length > 0) { + // The framework's own docs page from its config; generic docs when detection found none. + const docsUrl = session.skillId + ? FRAMEWORK_REGISTRY[session.skillId as Integration]?.docsUrl + : undefined; await wizardAbort({ message: 'Setup instructions for this project failed to download.\n' + 'Please try again, or contact wizard@posthog.com.\n\n' + 'You can also set up with your agent by downloading the skills here:\n' + - ' https://github.com/PostHog/skills\n' + + ' https://github.com/PostHog/context-mill/releases\n' + 'or integrate manually here:\n' + - ' https://posthog.com/docs/getting-started/install', + ` ${docsUrl ?? POSTHOG_DOCS_URL}`, error: new WizardError('Orchestrator preflight: skill variant missing', { missing: missingVariants.join(', '), framework: session.skillId,