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.

9.6 KB
Raw Blame
import { z } from 'zod'

import type { Context, ToolBase } from '@/tools/types'

import { wrapRunResultAsInformational } from './cellRuns'
import {
    findCellTag,
    materializeLegacySqlProps,
    replaceCellTag,
    normalizeForTagScan,
    startsComponentTag,
    upsertProp,
} from './cellTags'
import {
    applyVisualization,
    CellVisualizationSchema,
    storedVisualizationWarnings,
    VISUALIZATION_PARAM_DESCRIPTION,
} from './cellVisualization'
import { applyMarkdownEdit, fetchMarkdownNotebook, replaceMarkdownCell } from './markdownDoc'
import { NOTEBOOK_SHORT_ID_DESCRIPTION, notebookIdAliases } from './notebookId'
import { runExistingCell, type RunCellResult } from './runCell'

/**
 * The two id shapes a markdown block can carry: derived from its text by
 * `_create_stable_markdown_prose_id` in `products/notebooks/backend/util.py`, or stored in the
 * document as an anchor above the block.
 *
 * Only sharpens an error, because the content parameter decides the branch. A prefix change in
 * the backend therefore degrades one message and breaks nothing.
 */
const PROSE_NODE_ID_PREFIXES = ['mdp-', 'phb-']

const UpdateCellInputSchema = z
    .object({
        notebook_id: z.string().describe(NOTEBOOK_SHORT_ID_DESCRIPTION),
        node_id: z.string().describe('The cell to update, as returned by notebooks-add-cell.'),
        code: z
            .string()
            .optional()
            .describe(
                'New SQL or Python source. Omitting code and visualization still re-runs the cell as-is, but prefer notebooks-run-cell for that.'
            ),
        markdown: z
            .string()
            .optional()
            .describe(
                'New markdown for a markdown cell: prose, a heading, a table, or a fenced block. Use this instead of `code` when notebooks-get reports the cell as cell_type "markdown". Pass the replacement only; the surrounding cells are untouched.'
            ),
        visualization: CellVisualizationSchema.nullable()
            .optional()
            .describe(
                `${VISUALIZATION_PARAM_DESCRIPTION} Pass null to show the results table again. Without code, the chart changes and the cell does not re-run.`
            ),
    })
    .strict()

export const NotebooksUpdateCellSchema = z.preprocess(notebookIdAliases('notebook_id'), UpdateCellInputSchema)

export type UpdateCellResult = RunCellResult

export interface UpdateVisualizationResult {
    node_id: string
    updated: true
    visualization_warnings?: string[]
}

export interface UpdateProseCellResult {
    node_id: string
    updated: true
}

/** Reject markdown that opens a component tag, so a cell can only be added by the tool that owns runs and identity. */
function assertNoComponentTag(markdown: string): void {
    let insideFence = false
    // The backend collapses `\r\n` and a lone `\r` to a newline before it looks for tags, so a
    // payload split only on `\n` hides a tag from this guard that the backend later reads as a
    // live cell.
    for (const line of markdown.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n')) {
        // Fence detection normalizes the same characters as the tag check. Python strips them,
        // so a control-prefixed fence opens a block there and reads as prose here, which moves
        // every tag after it in or out of the fence.
        if (normalizeForTagScan(line).startsWith('```')) {
            insideFence = !insideFence
            continue
        }
        // Both walkers read fenced content as inert, so a tag written as an example there opens
        // no cell and the guard would reject a legitimate edit.
        if (insideFence || !startsComponentTag(line)) {
            continue
        }
        throw new Error(
            `markdown must not contain a component tag (found ${line.trim().slice(0, 40)}). Add cells with notebooks-add-cell, which assigns identity, names the dataframe, and runs the cell. To show a tag as an example, put it in a fenced code block.`
        )
    }
    // An unclosed fence flips the fence state of everything after this block, which decides
    // whether the tags already in the document open cells.
    if (insideFence) {
        throw new Error('markdown must not leave a code fence open. Close every ``` block in the replacement.')
    }
}

async function updateProseCell(
    context: Context,
    params: z.infer<typeof NotebooksUpdateCellSchema>
): Promise<UpdateProseCellResult> {
    if (params.visualization !== undefined) {
        throw new Error(`Cell ${params.node_id} is a markdown cell. visualization applies to sql cells only.`)
    }
    if (params.code !== undefined) {
        throw new Error(
            `Cell ${params.node_id} is a markdown cell. Pass its replacement as \`markdown\`, not \`code\`.`
        )
    }
    const next = params.markdown
    if (next === undefined || !next.trim()) {
        throw new Error('markdown must be non-empty. Remove a cell with notebooks-delete-cell.')
    }
    assertNoComponentTag(next)

    await replaceMarkdownCell(context, params.notebook_id, params.node_id, next.trim())
    return { node_id: params.node_id, updated: true }
}

export const updateCellHandler: ToolBase<
    typeof NotebooksUpdateCellSchema,
    UpdateCellResult | UpdateProseCellResult | UpdateVisualizationResult
>['handler'] = async (context: Context, params: z.infer<typeof NotebooksUpdateCellSchema>) => {
    if (params.visualization !== undefined && params.markdown !== undefined) {
        throw new Error('visualization applies to sql cells only. A markdown cell has no chart.')
    }
    if (params.code !== undefined && params.markdown !== undefined) {
        throw new Error(
            'Pass either code (a SQL or Python cell) or markdown (a markdown cell), not both. The cell type follows from node_id; read it from notebooks-get.'
        )
    }
    // A prefix only hints at the cell type. A tag holds its id in a prop, and nothing stops that
    // prop from reading like a markdown block id, so the document decides when the two disagree.
    const looksLikeProse = PROSE_NODE_ID_PREFIXES.some((prefix) => params.node_id.startsWith(prefix))
    if (looksLikeProse && (params.code !== undefined || params.visualization !== undefined)) {
        const { markdown } = await fetchMarkdownNotebook(context, params.notebook_id)
        if (!findCellTag(markdown, params.node_id)) {
            return await updateProseCell(context, params)
        }
    } else if (looksLikeProse || params.markdown !== undefined) {
        return await updateProseCell(context, params)
    }
    if (params.code !== undefined && !params.code.trim()) {
        throw new Error('code must be non-empty; omit it to re-run the cell unchanged.')
    }

    const initial = await fetchMarkdownNotebook(context, params.notebook_id)
    const existing = findCellTag(initial.markdown, params.node_id)
    if (!existing) {
        throw new Error(`No cell with node_id ${params.node_id} in notebook ${params.notebook_id}.`)
    }
    if (existing.tagName !== 'SQLV2' && existing.tagName !== 'PythonV2') {
        throw new Error(
            `Cell ${params.node_id} is a ${existing.tagName} cell and cannot be updated with this tool — delete and re-add it instead.`
        )
    }
    if (params.visualization !== undefined && existing.tagName !== 'SQLV2') {
        throw new Error(
            `visualization applies to sql cells only, and ${params.node_id} is a python cell. A python cell plots with matplotlib.`
        )
    }

    let markdown = initial.markdown
    let notebook = initial.notebook
    const codeChanged = params.code !== undefined && params.code !== existing.code
    if (codeChanged || params.visualization !== undefined) {
        const applied = await applyMarkdownEdit(context, params.notebook_id, (current) => {
            const block = findCellTag(current, params.node_id)
            if (!block) {
                throw new Error(`No cell with node_id ${params.node_id} in notebook ${params.notebook_id}.`)
            }
            let source = block.tagName === 'SQLV2' ? materializeLegacySqlProps(block.source) : block.source
            if (codeChanged) {
                source = upsertProp(source, 'code', params.code)
            }
            if (params.visualization !== undefined) {
                source = applyVisualization(source, params.visualization)
            }
            return replaceCellTag(current, block, source)
        })
        if (params.code === undefined) {
            const updated = findCellTag(applied.markdown, params.node_id)
            const warnings = updated ? storedVisualizationWarnings(updated.source) : []
            return wrapRunResultAsInformational({
                node_id: params.node_id,
                updated: true as const,
                ...(warnings.length ? { visualization_warnings: warnings } : {}),
            })
        }
        markdown = applied.markdown
        // The save response carries the notebook as it stood when the save committed, so it holds a
        // variable edit that landed after the read above.
        notebook = applied.notebook
    }

    const code = params.code ?? existing.code
    if (!code.trim()) {
        throw new Error(`Cell ${params.node_id} has no code to run.`)
    }

    return await runExistingCell(
        context,
        params.notebook_id,
        { nodeId: params.node_id, tagName: existing.tagName, code, returnVariable: existing.returnVariable },
        markdown,
        notebook.variables
    )
}

const tool = (): ToolBase<
    typeof NotebooksUpdateCellSchema,
    UpdateCellResult | UpdateProseCellResult | UpdateVisualizationResult
> => ({
    name: 'notebooks-update-cell',
    schema: NotebooksUpdateCellSchema,
    handler: updateCellHandler,
})

export default tool