:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
fix(onboarding): show a clear message when the wizard hits its ai usage limit (#119215)
posthog[bot]6f0b5a00eb0d
diff --git a/frontend/snapshots.yml b/frontend/snapshots.ymlindex 5bc8aa3888a2..f14335700bb0 100644--- a/frontend/snapshots.yml+++ b/frontend/snapshots.yml@@ -15790,6 +15790,10 @@ snapshots:hash: v1.k794b7964.7fcafd04ed6c719a8ad01cebc7abcc7265a3f677a2398e6ee19004eac26d1eff.kASMuoxhwilbDbtUhEblU0HnMTCXcWhk0aGBx34zYYkscenes-other-onboarding-shared-installation-progress--failed-provisioning--light:hash: v1.k794b7964.ae9111e8e758485d7791e5d85cd44d5cd5ffb2d5ec8948b1a9bb360455bc6674.O0Mx_17KqsoiMCWOgBgvn9w30i-uCzJpz05Jk9K3Isc+ scenes-other-onboarding-shared-installation-progress--failed-usage-limit--dark:+ hash: v1.k794b7964.60aae9b667df8cbdb74bf7419d201ece1ecede99bfb47de5ab86ca92cf29a3ca.vJvgDkUSC7s5hJ5wiiC1F7WgLlRUqmshkqDn5bOB0e8+ scenes-other-onboarding-shared-installation-progress--failed-usage-limit--light:+ hash: v1.k794b7964.50c4be57a0b7f54e4f9576afc3c8640b7fe50d81fb5ac53491a7627514c98759.2_g9z9UW7cdf77LuleEVHVIKOKW9qDlojT8K9IRbrLkscenes-other-onboarding-shared-installation-progress--failed-wizard--dark:hash: v1.k794b7964.3a1cef199fe6ff0b83ed59eb7c203067ceb40d28992890194f4b65eb54037063.G8lqwGkC_dmlyq1MoxtZlaWREPKsfAmXjlt1i3opb-wscenes-other-onboarding-shared-installation-progress--failed-wizard--light:diff --git a/frontend/src/lib/components/AgentPromptButton/AgentPromptButton.tsx b/frontend/src/lib/components/AgentPromptButton/AgentPromptButton.tsxindex 73c22f152a47..8448fe60635d 100644--- a/frontend/src/lib/components/AgentPromptButton/AgentPromptButton.tsx+++ b/frontend/src/lib/components/AgentPromptButton/AgentPromptButton.tsx@@ -75,6 +75,8 @@ export interface AgentPromptButtonProps {actions: AgentPromptAction[]/** Agent always shown on the main button, in place of the one the user last picked. */pinnedAgentKey?: AgentPromptDestination+ /** Agents left out of the menu, for prompts a given agent cannot act on. */+ excludeAgentKeys?: AgentPromptDestination[]/** `destination` names the agent on the main button ("Open in Cursor") instead of the prompt ("Open Fix prompt"). */labelMode?: 'action' | 'destination'/** Extra classes for the dropdown menu, e.g. a higher z-index when the button sits inside a toast. */@@ -84,6 +86,8 @@ export interface AgentPromptButtonProps {variant?: NonNullable<QuillButtonProps['variant']>/** `lemon` renders a LemonButton with a side menu, to sit beside other Lemon buttons. `size` and `variant` apply to `quill` only. */appearance?: 'quill' | 'lemon'+ /** LemonButton type for the `lemon` appearance. */+ lemonType?: 'primary' | 'secondary'/** Renders the dropdown open on first paint. Useful for visual regression snapshots. */defaultOpen?: boolean/** Fired whenever a combo runs (agent deeplink opened or clipboard copied). Useful for analytics. */@@ -289,12 +293,14 @@ export function buildAgentPrompt(export function AgentPromptButton({actions,pinnedAgentKey,+ excludeAgentKeys,labelMode = 'action',menuClassName,onOpenChange,size = 'default',variant = 'default',appearance = 'quill',+ lemonType = 'secondary',defaultOpen = false,onRun,repository,@@ -311,7 +317,9 @@ export function AgentPromptButton({const { todayRailEnabled } = useValues(todayShellLogic)const { currentProjectId } = useValues(projectLogic)const { isCloudOrDev } = useValues(preflightLogic)- const availableAgents = AGENTS.filter((agent) => !(todayRailEnabled && agent.key === 'posthog-ai'))+ const availableAgents = AGENTS.filter(+ (agent) => !(todayRailEnabled && agent.key === 'posthog-ai') && !excludeAgentKeys?.includes(agent.key)+ )// The Lemon menu renders its overlay directly, so it wires LemonMenu's arrow-key focus handling itself.const lemonKeyboard = useKeyboardNavigation<HTMLButtonElement>((actions.length > 1 ? actions.length : 0) + availableAgents.length@@ -364,7 +372,7 @@ export function AgentPromptButton({onKeyDown={(e) => e.currentTarget.contains(e.target as Node) && lemonKeyboard.onTriggerKeyDown(e)}><LemonButton- type="secondary"+ type={lemonType}size="small"icon={<AgentLogo logo={activeAgent.logo} logoClassName={activeAgent.logoClassName} />}onClick={handleMainClick}diff --git a/frontend/src/lib/utils/eventUsageLogic.ts b/frontend/src/lib/utils/eventUsageLogic.tsindex 2f1caab03c23..8c0234a36b64 100644--- a/frontend/src/lib/utils/eventUsageLogic.ts+++ b/frontend/src/lib/utils/eventUsageLogic.ts@@ -10,6 +10,7 @@ import { preflightLogic } from 'lib/logic/preflightLogic'import { objectClean } from 'lib/utils/objects'import { BillingUsageInteractionProps } from 'scenes/billing/types'import { SharedMetric } from 'scenes/experiments/SharedMetrics/sharedMetricLogic'+import type { InstallationErrorKind } from 'scenes/onboarding/shared/wizard-sync/installationProgressLogic'import { ProductTourEvent } from 'scenes/product-tours/constants'import { SURVEY_CREATED_SOURCE } from 'scenes/surveys/constants'import { userLogic } from 'scenes/userLogic'@@ -1653,6 +1654,7 @@ export interface eventUsageLogicActions {reportWizardSyncSessionFinished: (props: {completedTaskCount: numberelapsedSeconds: number+ errorKind: InstallationErrorKind | nulloutcome: stringskillId: stringtaskCount: number@@ -1660,6 +1662,7 @@ export interface eventUsageLogicActions {}) => {completedTaskCount: numberelapsedSeconds: number+ errorKind: 'usage_limit' | nulloutcome: stringskillId: stringtaskCount: number@@ -2001,6 +2004,7 @@ export const eventUsageLogic = kea<eventUsageLogicType>([workflowId: stringskillId: stringoutcome: string+ errorKind: InstallationErrorKind | nulltaskCount: numbercompletedTaskCount: numberelapsedSeconds: number@@ -2744,6 +2748,7 @@ export const eventUsageLogic = kea<eventUsageLogicType>([workflowId,skillId,outcome,+ errorKind,taskCount,completedTaskCount,elapsedSeconds,@@ -2752,6 +2757,7 @@ export const eventUsageLogic = kea<eventUsageLogicType>([workflow_id: workflowId,skill_id: skillId,outcome,+ error_kind: errorKind,task_count: taskCount,completed_task_count: completedTaskCount,elapsed_seconds: elapsedSeconds,diff --git a/frontend/src/scenes/onboarding/onboardingEventUsageLogic.ts b/frontend/src/scenes/onboarding/onboardingEventUsageLogic.tsindex df175129e6d4..8c9d0964c221 100644--- a/frontend/src/scenes/onboarding/onboardingEventUsageLogic.ts+++ b/frontend/src/scenes/onboarding/onboardingEventUsageLogic.ts@@ -103,6 +103,11 @@ export interface onboardingEventUsageLogicActions {phase: stringrunKey: string}+ reportWizardSyncUsageLimitAgentOpened: (props: { agent: string; mode: 'cloud' | 'local'; runKey: string }) => {+ agent: string+ mode: 'cloud' | 'local'+ runKey: string+ }}export type onboardingEventUsageLogicType = MakeLogicType<@@ -146,6 +151,8 @@ export const onboardingEventUsageLogic = kea<onboardingEventUsageLogicType>([mode: 'cloud' | 'local'trigger: 'auto' | 'button'}) => props,+ reportWizardSyncUsageLimitAgentOpened: (props: { runKey: string; mode: 'cloud' | 'local'; agent: string }) =>+ props,}),listeners(({ values }) => ({reportOnboardingInstallModeSelected: ({ mode }) => {@@ -227,5 +234,13 @@ export const onboardingEventUsageLogic = kea<onboardingEventUsageLogicType>([...wizardSyncEventProps(values.featureFlags),})},+ reportWizardSyncUsageLimitAgentOpened: ({ runKey, mode, agent }) => {+ posthog.capture('wizard sync usage limit agent opened', {+ run_key: runKey,+ mode,+ agent,+ ...wizardSyncEventProps(values.featureFlags),+ })+ },})),])diff --git a/frontend/src/scenes/onboarding/shared/wizard-sync/InstallationProgressContent.tsx b/frontend/src/scenes/onboarding/shared/wizard-sync/InstallationProgressContent.tsxindex dec60f99fdc6..5dc78a706ba7 100644--- a/frontend/src/scenes/onboarding/shared/wizard-sync/InstallationProgressContent.tsx+++ b/frontend/src/scenes/onboarding/shared/wizard-sync/InstallationProgressContent.tsx@@ -5,6 +5,7 @@ import { IconDocument, IconPullRequest, IconRocket, IconSearch, IconTerminal, Icimport { LemonBanner, LemonButton, Spinner } from '@posthog/lemon-ui'import { pngHoggie } from 'lib/brand/hoggies'+import { AgentPromptButton } from 'lib/components/AgentPromptButton'import { cn } from 'lib/utils/css-classes'import { CheckList } from '../components/CheckList'@@ -33,6 +34,7 @@ export function InstallationProgressContent({onViewReport,onDismiss,onRetryLocally,+ onAgentPromptRun,}: {progress: InstallationProgress/** Tailors the connecting state (copy + upcoming-step preview) to where the run happens. */@@ -49,8 +51,10 @@ export function InstallationProgressContent({/** When set, a failed run offers a "Run it yourself" button (switches the install step to the local* command). Omitted where no local fallback exists (e.g. the floating FAB), which shows only docs. */onRetryLocally?: () => void+ onAgentPromptRun?: (agentKey: string) => void}): JSX.Element {const { phase, steps, error, prUrl, prMerged } = progress+ const usageLimited = error?.kind === 'usage_limit'// The PR is opened mid-run: while the run keeps going (keeping CI green), surface it as ready rather// than an indefinite "setting up". Terminal phases keep their own headline.@@ -194,15 +198,41 @@ export function InstallationProgressContent({)}{phase === 'error' && (- // The cloud run failed — offer self-serve recovery so the user isn't stuck: run the wizard- // themselves (switches the install step to the local command) or follow the manual docs.+ // Self-serve recovery so the user isn't stuck. A usage-limited run skips the rerun, which+ // stops at the same AI gateway limit, and hands the setup to the user's own coding agent.<div className="flex flex-wrap gap-2">- {onRetryLocally && (- <LemonButton type="primary" onClick={onRetryLocally} icon={<IconTerminal />}>- Run it yourself- </LemonButton>+ {usageLimited ? (+ <AgentPromptButton+ actions={[+ {+ key: 'finish-setup',+ label: 'setup prompt',+ buildPrompt: () =>+ `Set up PostHog in this project. Follow the instructions at ${docsUrl}`,+ },+ ]}+ pinnedAgentKey="clipboard"+ // PostHog AI cannot edit the user's codebase, so it cannot finish an SDK install.+ excludeAgentKeys={['posthog-ai']}+ appearance="lemon"+ lemonType="primary"+ onRun={({ agentKey }) => onAgentPromptRun?.(agentKey)}+ data-attr="wizard-usage-limit-agent-prompt"+ />+ ) : (+ onRetryLocally && (+ <LemonButton type="primary" onClick={onRetryLocally} icon={<IconTerminal />}>+ Run it yourself+ </LemonButton>+ ))}- <LemonButton type={onRetryLocally ? 'secondary' : 'primary'} to={docsUrl} targetBlank>+ <LemonButton+ type={usageLimited || onRetryLocally ? 'secondary' : 'primary'}+ // The Lemon agent button only comes in small.+ size={usageLimited ? 'small' : undefined}+ to={docsUrl}+ targetBlank+ >Read the docs</LemonButton></div>diff --git a/frontend/src/scenes/onboarding/shared/wizard-sync/InstallationProgressView.stories.tsx b/frontend/src/scenes/onboarding/shared/wizard-sync/InstallationProgressView.stories.tsxindex 8bc7ad8059b0..c7fb9e26cabf 100644--- a/frontend/src/scenes/onboarding/shared/wizard-sync/InstallationProgressView.stories.tsx+++ b/frontend/src/scenes/onboarding/shared/wizard-sync/InstallationProgressView.stories.tsx@@ -214,6 +214,20 @@ export const FailedWizard: Story = {},}+export const FailedUsageLimit: Story = {+ args: {+ progress: progress({+ phase: 'error',+ steps: steps(['completed', 'completed', 'failed', 'pending']),+ error: {+ title: 'AI usage limit reached',+ detail: 'The setup agent ran out of AI usage before it finished. Your own coding agent can finish the setup from our docs.',+ kind: 'usage_limit',+ },+ }),+ },+}+// A run whose stream never delivered any state: no pipeline steps to show, only the recovery CTAs.export const LostContact: Story = {args: {diff --git a/frontend/src/scenes/onboarding/shared/wizard-sync/InstallationProgressView.tsx b/frontend/src/scenes/onboarding/shared/wizard-sync/InstallationProgressView.tsxindex 474d2c66a266..7b27c7b5db9f 100644--- a/frontend/src/scenes/onboarding/shared/wizard-sync/InstallationProgressView.tsx+++ b/frontend/src/scenes/onboarding/shared/wizard-sync/InstallationProgressView.tsx@@ -44,7 +44,8 @@ export function InstallationProgressView({)const { claimInlinePanel, releaseInlinePanel, openHandoffDoc } = useActions(wizardSyncUiLogic)const { dismissLocalRun } = useActions(finishedLocalRunLogic)- const { reportWizardSyncHandoffShown, reportWizardSyncHandoffDocOpened } = useActions(onboardingEventUsageLogic)+ const { reportWizardSyncHandoffShown, reportWizardSyncHandoffDocOpened, reportWizardSyncUsageLimitAgentOpened } =+ useActions(onboardingEventUsageLogic)// While shown inline on the install step, hide the floating FAB so the same run isn't in two places.useEffect(() => {@@ -92,6 +93,9 @@ export function InstallationProgressView({onViewReport={handleViewReport}onDismiss={onDismiss ?? defaultLocalDismiss}onRetryLocally={onRetryLocally}+ onAgentPromptRun={+ runKey ? (agent) => reportWizardSyncUsageLimitAgentOpened({ runKey, mode, agent }) : undefined+ }/>)}diff --git a/frontend/src/scenes/onboarding/shared/wizard-sync/helpers.ts b/frontend/src/scenes/onboarding/shared/wizard-sync/helpers.tsindex ba91d80225f5..84cfd0110b9d 100644--- a/frontend/src/scenes/onboarding/shared/wizard-sync/helpers.ts+++ b/frontend/src/scenes/onboarding/shared/wizard-sync/helpers.ts@@ -12,6 +12,10 @@ export function startedByFromSession(session: WizardSessionDTOApi | null): { namreturn { name: createdBy.first_name || createdBy.email, email: createdBy.email }}+export function sessionErrorMessage(session: WizardSessionDTOApi | null): string | undefined {+ return (session?.error as { message?: string } | null)?.message+}+// Ceiling on the displayed elapsed time. The clock is driven by a persisted handle that outlives the// run it names, so without a cap a run nobody ever settled counts up for as long as the browser keeps// the handle. Display only: telemetry keeps the true elapsed.diff --git a/frontend/src/scenes/onboarding/shared/wizard-sync/installationProgress.ts b/frontend/src/scenes/onboarding/shared/wizard-sync/installationProgress.tsindex 082f1d8304a3..b49403cc9790 100644--- a/frontend/src/scenes/onboarding/shared/wizard-sync/installationProgress.ts+++ b/frontend/src/scenes/onboarding/shared/wizard-sync/installationProgress.ts@@ -1,8 +1,10 @@import type { WizardSessionDTOApi } from 'products/wizard/frontend/generated/api.schemas'import type { FinishedLocalRunHandle } from './finishedLocalRunLogic'-import { startedByFromSession } from './helpers'+import { sessionErrorMessage, startedByFromSession } from './helpers'import type {+ InstallationError,+ InstallationErrorKind,InstallationPhase,InstallationProgress,InstallationStep,@@ -63,6 +65,25 @@ export function pendingInputFromSession(session: WizardSessionDTOApi | null): Wi}}+// The AI gateway refuses with a 402 when the run's token cap or the org's quota runs out. The wizard+// forwards the raw gateway JSON, which tells the user nothing, so replace it with a next step.+const USAGE_LIMIT_ERROR_REGEX = /\b(?:token_cap_exceeded|insufficient_quota)\b/i++export function errorKindFromMessage(message?: string | null): InstallationErrorKind | null {+ return message && USAGE_LIMIT_ERROR_REGEX.test(message) ? 'usage_limit' : null+}++function runError(title: string, detail?: string | null): InstallationError {+ if (errorKindFromMessage(detail) === 'usage_limit') {+ return {+ title: 'AI usage limit reached',+ detail: 'The setup agent ran out of AI usage before it finished. Your own coding agent can finish the setup from our docs.',+ kind: 'usage_limit',+ }+ }+ return { title, detail: detail ?? null }+}+const STEP_STATUSES: Record<string, InstallationStepStatus> = {pending: 'pending',in_progress: 'in_progress',@@ -99,7 +120,7 @@ export function cloudProgress(runStartedAt: string | null = null): InstallationProgress {let phase: InstallationPhase- let stalledError: { title: string; detail: string | null } | null = null+ let stalledError: InstallationError | null = nullif (!taskRunState && isStalled) {// The stream never delivered any run state (deleted or access-revoked run, a stream that// stayed silent past taskRunStreamLogic's no-state window). `idle` renders as a spinner with@@ -228,13 +249,13 @@ export function cloudProgress(const error =phase === 'error'- ? (stalledError ?? {+ ? (stalledError ??+ runError(// A cancelled run is a deliberate stop (Cancel button or closing the setup PR),// not a broken installation — presenting it as a failure reads as a bug.- title: taskRunState?.status === 'cancelled' ? 'Run cancelled' : 'Installation failed',- detail:- taskRunState?.error_message ?? (session?.error as { message?: string } | null)?.message ?? null,- })+ taskRunState?.status === 'cancelled' ? 'Run cancelled' : 'Installation failed',+ taskRunState?.error_message ?? sessionErrorMessage(session)+ )): null// The doc rides the run-window check, not the recency gate: the cloud wizard finishes (and@@ -309,12 +330,9 @@ export function localProgress(detail: null,}))- let error: { title: string; detail: string | null } | null = null+ let error: InstallationError | null = nullif (latestSession.run_phase === 'error') {- error = {- title: 'Wizard hit an error',- detail: (latestSession.error as { message?: string } | null)?.message ?? null,- }+ error = runError('Wizard hit an error', sessionErrorMessage(latestSession))} else if (stalled) {error = {title: 'Setup lost contact',@@ -341,10 +359,7 @@ export function progressFromFinishedLocalRun(handle: FinishedLocalRunHandle): Inreturn {phase: handle.runPhase,steps: handle.tasks.map((t) => ({ id: t.id, label: t.title, status: stepStatus(t.status), detail: null })),- error:- handle.runPhase === 'error'- ? { title: 'Wizard hit an error', detail: handle.error?.message ?? null }- : null,+ error: handle.runPhase === 'error' ? runError('Wizard hit an error', handle.error?.message) : null,prUrl: null,prMerged: false,isCurrent: true,diff --git a/frontend/src/scenes/onboarding/shared/wizard-sync/installationProgressLogic.test.ts b/frontend/src/scenes/onboarding/shared/wizard-sync/installationProgressLogic.test.tsindex beee0e9082f8..6a78bbd2fe54 100644--- a/frontend/src/scenes/onboarding/shared/wizard-sync/installationProgressLogic.test.ts+++ b/frontend/src/scenes/onboarding/shared/wizard-sync/installationProgressLogic.test.ts@@ -16,6 +16,11 @@ import { POSTHOG_INTEGRATION_WORKFLOW_ID, SELF_DRIVING_WORKFLOW_ID } from './wor// Matches the fixtures' timestamps so sessions read as fresh where intended.const NOW = new Date('2026-01-01T00:00:30Z').getTime()+const USAGE_LIMIT_ERROR = {+ title: 'AI usage limit reached',+ detail: 'The setup agent ran out of AI usage before it finished. Your own coding agent can finish the setup from our docs.',+ kind: 'usage_limit',+}import { TaskRunProgressStep, TaskRunStreamState } from './taskRunStreamLogic'function taskState(overrides: Partial<TaskRunStreamState> = {}): TaskRunStreamState {@@ -226,6 +231,20 @@ describe('installationProgressLogic merge', () => {).toEqual({ title: 'Installation failed', detail: 'wizard boom' })})+ it('replaces a raw gateway usage limit refusal with a usage limit message', () => {+ expect(+ cloudProgress(+ taskState({+ status: 'failed',+ error_message: 'posthog-gateway API error (402) token_cap_exceeded',+ }),+ [],+ 'open',+ null+ ).error+ ).toEqual(USAGE_LIMIT_ERROR)+ })+it('error detail is null when neither source has a message', () => {expect(cloudProgress(taskState({ status: 'failed', error_message: null }), [], 'open', null).error).toEqual({@@ -311,6 +330,18 @@ describe('installationProgressLogic merge', () => {})})+ it.each([+ ['token cap', 'API Error: 402 {"error":{"code":"token_cap_exceeded","message":"cap reached"}}', true],+ ['quota', 'API Error: 402 {"error":{"type":"insufficient_quota"}}', true],+ ['uppercase code', 'API Error: 402 TOKEN_CAP_EXCEEDED', true],+ ['prefixed code', 'API Error: 402 my_token_cap_exceeded', false],+ ['suffixed code', 'API Error: 402 insufficient_quota_v2', false],+ ])('maps a gateway refusal with a %s to the usage limit message', (_name, message, usageLimit) => {+ expect(localProgress(session({ run_phase: 'error', error: { message } }), 'open', true).error).toEqual(+ usageLimit ? USAGE_LIMIT_ERROR : { title: 'Wizard hit an error', detail: message }+ )+ })+it('error detail is null when the session has no error message', () => {expect(localProgress(session({ run_phase: 'error', error: null }), 'open', true).error).toEqual({title: 'Wizard hit an error',@@ -647,6 +678,20 @@ describe('installationProgressLogic merge', () => {expect(actions.reportWizardSyncSessionFinished).toHaveBeenCalledTimes(1)})+ it.each([+ ['usage limit refusal', 'API Error: 402 token_cap_exceeded', 'usage_limit'],+ ['different error', 'boom', null],+ ])('reports the error kind for a %s', (_name, message, errorKind) => {+ const actions = spyActions()+ runLocalSessionBookkeeping(+ fresh({ session_id: `kind-${message}`, run_phase: 'error', error: { message } }),+ fresh({ session_id: `kind-${message}`, run_phase: 'running' }),+ POSTHOG_INTEGRATION_WORKFLOW_ID,+ actions+ )+ expect(actions.reportWizardSyncSessionFinished).toHaveBeenCalledWith(expect.objectContaining({ errorKind }))+ })+it.each([// Recording must fire on every fresh terminal delivery (a replayed terminal state after// a remount is exactly when the FAB needs its snapshot back), never on stale ones —diff --git a/frontend/src/scenes/onboarding/shared/wizard-sync/installationProgressLogic.ts b/frontend/src/scenes/onboarding/shared/wizard-sync/installationProgressLogic.tsindex e70d8452a020..d9c3c987ef84 100644--- a/frontend/src/scenes/onboarding/shared/wizard-sync/installationProgressLogic.ts+++ b/frontend/src/scenes/onboarding/shared/wizard-sync/installationProgressLogic.ts@@ -23,7 +23,8 @@ import type { WizardConnectionStatus } from '../../../../../../products/wizard/fimport { activeCloudRunLogic } from './activeCloudRunLogic'import type { CloudRunHandle } from './activeCloudRunLogic'import { finishedLocalRunLogic } from './finishedLocalRunLogic'-import { cloudProgress, isSessionFresh, localProgress } from './installationProgress'+import { sessionErrorMessage } from './helpers'+import { cloudProgress, errorKindFromMessage, isSessionFresh, localProgress } from './installationProgress'import { taskRunStreamLogic, TaskRunProgressStep, TaskRunStreamState } from './taskRunStreamLogic'import type { TaskRunConnectionStatus } from './taskRunStreamLogic'import {@@ -119,10 +120,19 @@ export interface WizardPendingInput {prompts: string[]}+/** Set when the AI gateway stopped the run, so the UI offers the user's own agent in place of a retry. */+export type InstallationErrorKind = 'usage_limit'++export interface InstallationError {+ title: string+ detail: string | null+ kind?: InstallationErrorKind+}+export interface InstallationProgress {phase: InstallationPhasesteps: InstallationStep[]- error: { title: string; detail: string | null } | null+ error: InstallationError | nullprUrl: string | null/** The bound PR was merged (webhook-recorded on the run's output). */prMerged: boolean@@ -176,6 +186,7 @@ export interface installationProgressLogicActions {reportWizardSyncSessionFinished: (props: {completedTaskCount: numberelapsedSeconds: number+ errorKind: InstallationErrorKind | nulloutcome: stringskillId: stringtaskCount: number@@ -183,6 +194,7 @@ export interface installationProgressLogicActions {}) => {completedTaskCount: numberelapsedSeconds: number+ errorKind: 'usage_limit' | nulloutcome: stringskillId: stringtaskCount: number@@ -438,6 +450,7 @@ export function runLocalSessionBookkeeping(workflowId: stringskillId: stringoutcome: string+ errorKind: InstallationErrorKind | nulltaskCount: numbercompletedTaskCount: numberelapsedSeconds: number@@ -513,6 +526,7 @@ export function runLocalSessionBookkeeping(workflowId,skillId: session.skill_id,outcome: session.run_phase,+ errorKind: errorKindFromMessage(sessionErrorMessage(session)),taskCount: tasks.length,completedTaskCount: tasks.filter((t) => t.status === 'completed').length,elapsedSeconds: elapsedSecondsFrom(session.started_at, now),