: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
import type { Schemas } from '@/api/generated'
import type { Context } from '@/tools/types'
import {
buildResultProp,
POLL_DELAYS_MS,
RUN_WAIT_BUDGET_MS,
shapeRunForModel,
sleep,
type ShapedRunResult,
} from './cellRuns'
import { findCellTag, readStringProp, removeProp, replaceCellTag, upsertProp } from './cellTags'
import { applyMarkdownEdit } from './markdownDoc'
export interface NotebookRunCellOutcome {
node_id: string
dataframe_name?: string
/** 'running', 'done', 'failed', 'interrupted', or null before the run reaches the cell. */
status: string | null
run?: ShapedRunResult
}
export interface NotebookRunOutcome {
run_id: string
status: string
cell_count: number
completed_count: number
failed_cell?: string
cells: NotebookRunCellOutcome[]
starts_sandbox?: boolean
sandbox_hourly_price?: number | null
hint?: string
}
const STILL_RUNNING_HINT =
'The notebook is still running. Call notebooks-run-status with this run_id to keep waiting and to write the remaining results into the document.'
const TERMINAL_CELL_STATUSES = new Set(['done', 'failed', 'interrupted'])
/**
* How many cells one document save may carry. Batching keeps a poll that finds a whole
* notebook's worth of finished cells — the agent that started a run and came back later —
* from holding every result envelope in memory at once, since a single envelope can run to
* megabytes. A normal poll finds far fewer than this, so it still saves once.
*/
const MAX_CELLS_PER_SAVE = 10
/** A cell result already written into the document, keyed by the run that produced it. */
/**
* Whether the cell already carries this run's result, or one from a later run.
*
* Run ids are uuid7, so their canonical form sorts by creation time and an id above this one
* belongs to a later execution. Without the ordering, reading the status of an older run —
* an agent polling run A after run B has finished — puts A's rows back under the cell that
* B produced, leaving results that do not match the code beside them.
*/
function carriesThisRunOrNewer(markdown: string, nodeId: string, runId: string): boolean {
const block = findCellTag(markdown, nodeId)
if (!block) {
return false
}
const existing = readStringProp(block.source, 'runId')
return !!existing && existing >= runId
}
/**
* Wait for a whole-notebook run, writing each cell's result into the document as it lands.
*
* One `applyMarkdownEdit` per poll, not per cell: a ten-cell run would otherwise save the
* document ten times in a few seconds, and every save is a version bump other editors see.
* Returns as soon as the run is terminal, or when the budget runs out — in which case the
* caller tells the agent to continue with notebooks-run-status.
*/
export async function awaitNotebookRun(
context: Context,
notebookId: string,
notebookPath: string,
runId: string,
waitBudgetMs: number = RUN_WAIT_BUDGET_MS
): Promise<NotebookRunOutcome> {
const deadline = Date.now() + waitBudgetMs
const shapedByNodeId = new Map<string, ShapedRunResult>()
const writtenRunIds = new Set<string>()
let pollIndex = 0
for (;;) {
const status = await context.api.request<Schemas.NotebookRunStatusResponse>({
method: 'GET',
path: `${notebookPath}runs/${encodeURIComponent(runId)}/`,
})
await writeLandedCells(context, notebookId, notebookPath, status, shapedByNodeId, writtenRunIds)
if (status.status !== 'running') {
return buildOutcome(runId, status, shapedByNodeId)
}
const delay = POLL_DELAYS_MS[Math.min(pollIndex, POLL_DELAYS_MS.length - 1)]!
pollIndex += 1
if (Date.now() + delay > deadline) {
return { ...buildOutcome(runId, status, shapedByNodeId), hint: STILL_RUNNING_HINT }
}
await sleep(delay)
}
}
async function writeLandedCells(
context: Context,
notebookId: string,
notebookPath: string,
status: Schemas.NotebookRunStatusResponse,
shapedByNodeId: Map<string, ShapedRunResult>,
writtenRunIds: Set<string>
): Promise<void> {
const landed = status.cells.filter(
(cell) => cell.run_id && !writtenRunIds.has(cell.run_id) && TERMINAL_CELL_STATUSES.has(cell.status ?? '')
)
for (let start = 0; start < landed.length; start += MAX_CELLS_PER_SAVE) {
await writeCellBatch(
context,
notebookId,
notebookPath,
landed.slice(start, start + MAX_CELLS_PER_SAVE),
shapedByNodeId,
writtenRunIds
)
}
}
async function writeCellBatch(
context: Context,
notebookId: string,
notebookPath: string,
batch: Schemas.NotebookRunCell[],
shapedByNodeId: Map<string, ShapedRunResult>,
writtenRunIds: Set<string>
): Promise<void> {
const envelopes: { nodeId: string; runId: string; envelope: Schemas.NotebookSQLV2Envelope | null }[] = []
for (const cell of batch) {
const cellRunId = cell.run_id!
writtenRunIds.add(cellRunId)
const result = await context.api.request<Schemas.NotebookSQLV2RunStatusResponse>({
method: 'GET',
path: `${notebookPath}sql_v2/runs/${encodeURIComponent(cellRunId)}/`,
})
const envelope = result.result ?? null
shapedByNodeId.set(
cell.node_id,
shapeRunForModel({
run_id: cellRunId,
status: (cell.status ?? 'failed') as ShapedRunResult['status'],
envelope,
error: result.error ?? null,
})
)
envelopes.push({ nodeId: cell.node_id, runId: cellRunId, envelope })
}
await applyMarkdownEdit(context, notebookId, (current) => {
let markdown = current
for (const { nodeId, runId: cellRunId, envelope } of envelopes) {
// A cell deleted while the run worked has nowhere for its result to land, a cell
// already carrying this run's result must not be written twice, and one carrying a
// later run's result must not be rolled back to this one.
if (carriesThisRunOrNewer(markdown, nodeId, cellRunId)) {
continue
}
const block = findCellTag(markdown, nodeId)
if (!block) {
continue
}
let source = upsertProp(block.source, 'runId', cellRunId)
source = envelope
? upsertProp(source, 'result', buildResultProp(envelope))
: // No envelope means this run produced none — it failed or was stopped. Leaving
// the previous run's rows attached would show them as this run's output, and
// the editor skips recovery for a cell that already carries a result.
removeProp(source, 'result')
markdown = replaceCellTag(markdown, block, source)
}
return markdown
})
}
function buildOutcome(
runId: string,
status: Schemas.NotebookRunStatusResponse,
shapedByNodeId: Map<string, ShapedRunResult>
): NotebookRunOutcome {
const cells: NotebookRunCellOutcome[] = status.cells.map((cell) => ({
node_id: cell.node_id,
...(cell.dataframe_name ? { dataframe_name: cell.dataframe_name } : {}),
status: cell.status ?? null,
...(shapedByNodeId.has(cell.node_id) ? { run: shapedByNodeId.get(cell.node_id)! } : {}),
}))
return {
run_id: runId,
status: status.status,
cell_count: status.cell_count,
completed_count: cells.filter((cell) => cell.status === 'done').length,
...(status.failed_node_id ? { failed_cell: status.failed_node_id } : {}),
cells,
}
}