Skip to content

: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.

16.7 KB
Raw Blame
import { MakeLogicType, actions, connect, kea, key, listeners, path, props, reducers, selectors } from 'kea'
import posthog from 'posthog-js'

import { ApiConfig } from 'lib/api'
import { FEATURE_FLAGS } from 'lib/constants'
import { lemonToast } from 'lib/lemon-ui/LemonToast/LemonToast'
import { FeatureFlagsSet, featureFlagLogic } from 'lib/logic/featureFlagLogic'
import { delay } from 'lib/utils/async'

import {
    notebooksRunsCreate,
    notebooksRunsInterruptCreate,
    notebooksRunsRetrieve,
} from 'products/notebooks/frontend/generated/api'
import type {
    NotebookRunStartRequestApi,
    NotebookRunStatusResponseApi,
} from 'products/notebooks/frontend/generated/api.schemas'

import { buildNotebookRunFinishedEvent, buildNotebookRunStartedEvent } from './notebookAnalytics'
import { notebookLogic } from './notebookLogic'
import { notebookNodeStalenessLogic } from './notebookNodeStalenessLogic'
import { NotebookOperation, notebookOperationsLogic } from './notebookOperationsLogic'
import { notebookSettingsLogic } from './notebookSettingsLogic'
import { getSavableNotebookVariables } from './notebookVariables'
import { sandboxStartMessage } from './SandboxStartMessage'

/** How often the scene asks the backend where the run has got to. Matches the workflow's own cadence. */
const POLL_INTERVAL_MS = 2000

/** Consecutive failed status reads before the UI says so. Polling continues regardless. */
const MAX_POLL_FAILURES = 5

/** How long to wait for a pending content save before starting a run anyway. */
const SAVE_FLUSH_TIMEOUT_MS = 3000

export interface NotebookRunLogicProps {
    shortId: string
}

/** The operation id the run holds for its whole duration, so per-cell run buttons stay disabled. */
const runAllOperation = (shortId: string): NotebookOperation => ({
    id: `${shortId}:run-all`,
    nodeId: `${shortId}:run-all`,
    kind: 'run',
})

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface notebookRunLogicValues {
    featureFlags: FeatureFlagsSet // featureFlagLogic
    activeOperation: NotebookOperation | null // notebookOperationsLogic
    isBusy: boolean // notebookOperationsLogic
    cellCount: number
    currentCellNumber: number
    isInterrupting: boolean
    isRunning: boolean
    isSandboxComputeFree: boolean
    isStarting: boolean
    progressLabel: string | null
    run: NotebookRunStatusResponseApi | null
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface notebookRunLogicActions {
    adoptChainRun: (
        nodeId: string,
        runId: string
    ) => {
        nodeId: string
        runId: string
    } // notebookNodeStalenessLogic
    finishOperation: (id: string) => {
        id: string
    } // notebookOperationsLogic
    startOperation: (operation: NotebookOperation) => {
        operation: NotebookOperation
    } // notebookOperationsLogic
    setShowKernelInfo: (showKernelInfo: boolean) => {
        showKernelInfo: boolean
    } // notebookSettingsLogic
    interruptRun: () => {
        value: true
    }
    pollRun: () => {
        value: true
    }
    runFinished: (run: NotebookRunStatusResponseApi) => {
        run: NotebookRunStatusResponseApi
    }
    setInterrupting: (isInterrupting: boolean) => {
        isInterrupting: boolean
    }
    setRun: (run: NotebookRunStatusResponseApi | null) => {
        run: NotebookRunStatusResponseApi | null
    }
    setStarting: (isStarting: boolean) => {
        isStarting: boolean
    }
    startRun: () => {
        value: true
    }
    stopPolling: () => {
        value: true
    }
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface notebookRunLogicMeta {
    key: string
    __keaTypeGenInternalSelectorTypes: {
        isRunning: (run: NotebookRunStatusResponseApi | null, isStarting: boolean) => boolean
        cellCount: (run: NotebookRunStatusResponseApi | null) => number
        currentCellNumber: (run: NotebookRunStatusResponseApi | null) => number
        progressLabel: (run: NotebookRunStatusResponseApi | null) => string | null
        isSandboxComputeFree: (featureFlags: FeatureFlagsSet) => boolean
    }
}

export type notebookRunLogicType = MakeLogicType<
    notebookRunLogicValues,
    notebookRunLogicActions,
    NotebookRunLogicProps,
    notebookRunLogicMeta
>

/**
 * Runs every SQL and Python cell of a markdown notebook through the backend's whole-notebook
 * run, and hands each cell's result back to the cell that owns it.
 *
 * The backend drives the cells, so this logic only starts the run, polls it, and tells each
 * mounted cell which run id is now its own. The cell's existing poll path writes the result
 * into the document and reports it to the staleness chain, so result rendering, stale marks,
 * and interrupt all keep working with no new code.
 */
export const notebookRunLogic = kea<notebookRunLogicType>([
    props({} as NotebookRunLogicProps),
    key((props) => props.shortId),
    path((key) => ['scenes', 'notebooks', 'Notebook', 'notebookRunLogic', key]),
    connect((props: NotebookRunLogicProps) => ({
        values: [
            featureFlagLogic,
            ['featureFlags'],
            notebookOperationsLogic({ shortId: props.shortId }),
            ['isBusy', 'activeOperation'],
        ],
        actions: [
            notebookOperationsLogic({ shortId: props.shortId }),
            ['startOperation', 'finishOperation'],
            notebookNodeStalenessLogic({ shortId: props.shortId }),
            ['adoptChainRun'],
            notebookSettingsLogic,
            ['setShowKernelInfo'],
        ],
    })),
    actions({
        startRun: true,
        pollRun: true,
        interruptRun: true,
        stopPolling: true,
        setRun: (run: NotebookRunStatusResponseApi | null) => ({ run }),
        setStarting: (isStarting: boolean) => ({ isStarting }),
        setInterrupting: (isInterrupting: boolean) => ({ isInterrupting }),
        runFinished: (run: NotebookRunStatusResponseApi) => ({ run }),
    }),
    reducers({
        run: [
            null as NotebookRunStatusResponseApi | null,
            {
                setRun: (_, { run }) => run,
                startRun: () => null,
            },
        ],
        // The stop request is in flight; guards the Stop button against a second click.
        isInterrupting: [
            false,
            {
                interruptRun: () => true,
                setInterrupting: (_, { isInterrupting }) => isInterrupting,
                stopPolling: () => false,
                startRun: () => false,
            },
        ],
        // The window between the start request and the first status: the button is already
        // busy, but there is no run to report progress for yet.
        isStarting: [
            false,
            {
                startRun: () => true,
                setStarting: (_, { isStarting }) => isStarting,
                stopPolling: () => false,
            },
        ],
    }),
    selectors({
        isRunning: [
            (s) => [s.run, s.isStarting],
            (run: NotebookRunStatusResponseApi | null, isStarting: boolean): boolean =>
                isStarting || run?.status === 'running',
        ],
        cellCount: [(s) => [s.run], (run: NotebookRunStatusResponseApi | null): number => run?.cell_count ?? 0],
        currentCellNumber: [
            (s) => [s.run],
            (run: NotebookRunStatusResponseApi | null): number =>
                run ? Math.min(run.current_index + 1, run.cell_count) : 0,
        ],
        progressLabel: [
            (s) => [s.run],
            (run: NotebookRunStatusResponseApi | null): string | null =>
                run && run.status === 'running' && run.cell_count > 0
                    ? `Running cell ${Math.min(run.current_index + 1, run.cell_count)} of ${run.cell_count}`
                    : null,
        ],
        isSandboxComputeFree: [
            (s) => [s.featureFlags],
            (featureFlags: FeatureFlagsSet): boolean => !!featureFlags[FEATURE_FLAGS.NOTEBOOK_SANDBOX_FREE_COMPUTE],
        ],
    }),
    listeners(({ props, actions, values, cache }) => {
        const operation = runAllOperation(props.shortId)
        const teamId = (): string => String(ApiConfig.getCurrentTeamId())

        /** Save whatever autosave is still holding, and return the run body to start with. */
        const flushPendingEdits = async (): Promise<NotebookRunStartRequestApi> => {
            const notebook = notebookLogic.findMounted({ shortId: props.shortId })
            if (!notebook) {
                return {}
            }
            if (notebook.values.localContent) {
                notebook.actions.saveNotebookNow()
                // The save clears localContent, which is the signal it landed. Bounded: a save
                // that cannot complete must not block the run forever, and the worst case is
                // the behaviour this had before — a run against the last saved content.
                const deadline = performance.now() + SAVE_FLUSH_TIMEOUT_MS
                while (notebook.values.localContent && performance.now() < deadline) {
                    await delay(50)
                }
            }
            const variables = getSavableNotebookVariables(notebook.values.variables ?? [])
            return variables.length ? { variables } : {}
        }

        return {
            startRun: async () => {
                if (values.isBusy && values.activeOperation?.id !== operation.id) {
                    lemonToast.info('Another operation is running in this notebook — wait for it to finish.')
                    actions.setStarting(false)
                    return
                }
                actions.startOperation(operation)
                cache.startedAt = performance.now()
                cache.interruptRequested = false
                try {
                    // Autosave debounces content by 400ms and variables by 500ms, so clicking
                    // straight after an edit used to freeze the previously saved code and
                    // values: the results then landed under newer text the user could see.
                    // Flush the content, and hand the variables to the start call, which
                    // stores them in the same transaction that creates the run.
                    const body = await flushPendingEdits()
                    const started = await notebooksRunsCreate(teamId(), props.shortId, body)
                    // The only place this id exists before the first poll, and `startRun`
                    // cleared the previous run, so without it every poll asks for /runs/undefined/.
                    cache.runId = started.run_id
                    if (cache.interruptRequested) {
                        // Stop was pressed while this request was still out. Send it now that
                        // there is something to stop, rather than dropping the click.
                        cache.interruptRequested = false
                        actions.interruptRun()
                    }
                    posthog.capture(...buildNotebookRunStartedEvent(props.shortId, started.cell_count))
                    if (started.starts_sandbox) {
                        // The backend decides this at dispatch, so it is the only accurate source.
                        // Open the panel so the user can watch the sandbox come up.
                        actions.setShowKernelInfo(true)
                        lemonToast.info(
                            sandboxStartMessage(started.sandbox_hourly_price ?? null, values.isSandboxComputeFree)
                        )
                    }
                    cache.seenCellRunIds = new Set<string>()
                    cache.pollFailures = 0
                    actions.setStarting(false)
                    actions.pollRun()
                    cache.disposables.add(() => {
                        const timer = window.setInterval(() => actions.pollRun(), POLL_INTERVAL_MS)
                        return () => clearInterval(timer)
                    }, 'pollRun')
                } catch (error: any) {
                    actions.stopPolling()
                    lemonToast.error(error?.detail || error?.message || 'Could not start the run')
                }
            },
            pollRun: async () => {
                if (cache.pollInFlight) {
                    return
                }
                cache.pollInFlight = true
                try {
                    const run = await notebooksRunsRetrieve(teamId(), props.shortId, values.run?.run_id ?? cache.runId)
                    cache.runId = run.run_id
                    actions.setRun(run)
                    // Hand every newly started cell to the cell that owns it, so its own poll
                    // path writes the result into the document.
                    const seen: Set<string> = (cache.seenCellRunIds ??= new Set<string>())
                    for (const cell of run.cells) {
                        if (cell.run_id && !seen.has(cell.run_id)) {
                            seen.add(cell.run_id)
                            actions.adoptChainRun(cell.node_id, cell.run_id)
                        }
                    }
                    cache.pollFailures = 0
                    if (run.status !== 'running') {
                        actions.runFinished(run)
                    }
                } catch (error: any) {
                    if ((error as { status?: number } | null)?.status === 404) {
                        // The run is gone, so there is nothing left to recover.
                        actions.stopPolling()
                        lemonToast.error('That run no longer exists.')
                        return
                    }
                    // Anything else is the status endpoint being unreachable, and the run keeps
                    // going on the backend regardless. Giving up here released the notebook
                    // while the run was still live — letting a per-cell run start underneath it
                    // — and left the banner stuck on Stop with no way back. So keep the timer
                    // and the operation, say so once, and let a later poll pick the run up.
                    cache.pollFailures = (cache.pollFailures ?? 0) + 1
                    if (cache.pollFailures === MAX_POLL_FAILURES) {
                        lemonToast.error(error?.detail || error?.message || 'Lost contact with the run — still trying')
                    }
                } finally {
                    cache.pollInFlight = false
                }
            },
            runFinished: ({ run }) => {
                actions.stopPolling()
                posthog.capture(
                    ...buildNotebookRunFinishedEvent(
                        props.shortId,
                        run,
                        Math.round(performance.now() - (cache.startedAt ?? 0))
                    )
                )
                if (run.status === 'done') {
                    lemonToast.success('Notebook run finished.')
                    return
                }
                if (run.status === 'interrupted') {
                    lemonToast.info('Notebook run stopped.')
                    return
                }
                const failed = run.cells.find((cell) => cell.node_id === run.failed_node_id)
                const position = run.cells.findIndex((cell) => cell.node_id === run.failed_node_id) + 1
                const name = failed?.dataframe_name || (position > 0 ? `cell ${position}` : 'a cell')
                lemonToast.error(`The run stopped at ${name}. Fix it and run again.`)
            },
            interruptRun: async () => {
                const runId = values.run?.run_id ?? cache.runId
                if (!runId) {
                    // The start request has not answered yet, so there is no run to stop.
                    // Remember the click: `startRun` sends it the moment the id lands. Without
                    // this the click vanished and left both Stop controls disabled for the
                    // rest of the run, because nothing reset the in-flight flag.
                    cache.interruptRequested = true
                    actions.setInterrupting(false)
                    return
                }
                try {
                    await notebooksRunsInterruptCreate(teamId(), props.shortId, runId)
                    // The next poll observes the terminal state and reports it once.
                    actions.pollRun()
                } catch (error: any) {
                    actions.setInterrupting(false)
                    lemonToast.error(error?.detail || error?.message || 'Could not stop the run')
                }
            },
            stopPolling: () => {
                cache.disposables.dispose('pollRun')
                actions.finishOperation(operation.id)
            },
        }
    }),
])