Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

8.9 KB
Raw Blame
/* Copyright 2026 Marimo. All rights reserved. */
import { logNever } from "@/utils/assertNever";
import { invariant } from "@/utils/invariant";
import { type Seconds, Time } from "@/utils/time";
import { extractAllTracebackInfo, type TracebackInfo } from "@/utils/traceback";
import { parseOutline } from "../dom/outline";
import type { CellMessage, OutputMessage } from "../kernel/messages";
import type { RuntimeState } from "../network/types";
import { collapseConsoleOutputs } from "./collapseConsoleOutputs";
import type { CellRuntimeState, ConsoleOutputMessage } from "./types";

// Ids increase with position, so the last output holds the maximum.
function nextConsoleOutputId(outputs: ConsoleOutputMessage[]): number {
  return (outputs.at(-1)?.id ?? 0) + 1;
}

export function transitionCell(
  cell: CellRuntimeState,
  message: CellMessage,
): CellRuntimeState {
  const nextCell = { ...cell };

  // Handle status transition and update output; message.status !== null
  // implies a status transition
  switch (message.status) {
    case "queued":
      nextCell.interrupted = false;
      nextCell.errored = false;
      nextCell.runElapsedTimeMs = null;
      nextCell.debuggerActive = false;
      // We intentionally don't update lastCodeRun, since the kernel queues
      // whatever code was last registered with it, which might not match
      // the cell's current code if the user modified it.
      break;
    case "running":
      // Clear interrupted here in case we start as "running"
      // This can happen on a resumed session
      nextCell.interrupted = false;
      // If was previously stopped, clear the outputs
      if (cell.stopped) {
        nextCell.output = null;
      }
      // If it transitioned from queued to running, remove previous console outputs
      if (nextCell.status === "queued") {
        nextCell.consoleOutputs = [];
      }
      nextCell.stopped = false;
      nextCell.runStartTimestamp = message.timestamp as Seconds;
      // Store the last run timestamp, since this gets cleared once idle
      nextCell.lastRunStartTimestamp = message.timestamp as Seconds;
      break;
    case "idle":
      if (cell.runStartTimestamp) {
        nextCell.runElapsedTimeMs = Time.fromSeconds(
          ((message.timestamp ?? 0) - cell.runStartTimestamp) as Seconds,
        ).toMilliseconds();
        nextCell.runStartTimestamp = null;
        nextCell.staleInputs = false;
      }
      // If last run start timestamp is not set, set it to the current timestamp
      // This happens on a resumed session
      if (!cell.lastRunStartTimestamp && message.timestamp) {
        nextCell.lastRunStartTimestamp = message.timestamp as Seconds;
      }
      nextCell.debuggerActive = false;
      break;
    case null:
      break;
    case "disabled-transitively":
      // Everything should already be up to date from prepareCellForExecution
      break;
    case undefined:
      break;
    default:
      logNever(message.status);
  }

  nextCell.output = message.output ?? nextCell.output;
  nextCell.staleInputs = message.stale_inputs ?? nextCell.staleInputs;
  nextCell.status = message.status ?? nextCell.status;
  // Tri-state partial update: an omitted field (undefined) leaves the hint
  // unchanged; null explicitly clears it; a string sets it.
  if (message.serialization !== undefined) {
    nextCell.serialization = message.serialization;
  }

  let didInterruptFromThisMessage = false;

  // Handle errors: marimo includes an error output when a cell is interrupted
  // or errored
  if (
    message.output != null &&
    message.output.mimetype === "application/vnd.marimo+error"
  ) {
    // The frontend manually sets status to queued when a user runs a cell,
    // to give immediate feedback, but the kernel doesn't know that.
    //
    // TODO(akshayka): Move all status management to the backend.
    if (nextCell.status === "queued" || nextCell.status === "running") {
      nextCell.status = "idle";
    }

    invariant(
      Array.isArray(message.output.data),
      "Expected error output data to be an array",
    );
    if (message.output.data.some((error) => error.type === "interruption")) {
      // Interrupted helps distinguish that the cell is stale
      nextCell.interrupted = true;
      didInterruptFromThisMessage = true;
    } else if (
      message.output.data.some((error) => error.type.includes("ancestor"))
    ) {
      // The cell didn't run, but it was intentional, so don't count as
      // errored.
      nextCell.stopped = true;
    } else {
      // Communicate that the cell errored (e.g., an exception was raised)
      nextCell.errored = true;
    }
  }

  // Coalesce console outputs, which are streamed during execution.
  let consoleOutputs = cell.consoleOutputs;

  // When the cell is interrupted or finishes (idle), there is no live
  // stdin/pdb session, so resolve any dangling stdin prompt. This removes the
  // debugger box — e.g. after quitting pdb with `q`, which stops the cell
  // (idle) rather than interrupting it.
  if (didInterruptFromThisMessage || message.status === "idle") {
    nextCell.debuggerActive = false;
    consoleOutputs = consoleOutputs.map((output) => {
      if (output.channel === "stdin") {
        // StatefulOutputMessage exposes data through a getter, which object
        // spread would omit.
        return {
          channel: output.channel,
          mimetype: output.mimetype,
          data: output.data,
          timestamp: output.timestamp,
          id: output.id,
          response: output.response ?? "",
        };
      }
      return output;
    });
  }

  const messageConsole = message.console;
  if (messageConsole != null) {
    // The kernel sends an empty array to clear the console; otherwise,
    // messageConsole is an output that needs to be appended to the
    // existing console outputs.
    consoleOutputs = Array.isArray(messageConsole)
      ? collapseConsoleOutputs(
          messageConsole.map((output, i) => ({ ...output, id: i + 1 })),
        )
      : collapseConsoleOutputs([
          ...consoleOutputs,
          { ...messageConsole, id: nextConsoleOutputId(consoleOutputs) },
        ]);
  }
  nextCell.consoleOutputs = consoleOutputs;
  // Derive outline from output
  nextCell.outline = parseOutline(nextCell.output);

  // Transition PDB
  const newConsoleOutputs = [message.console].flat().filter(Boolean);
  const pdbOutputs = newConsoleOutputs.filter(
    (output) => output.channel === "pdb",
  );
  const hasPdbOutput = pdbOutputs.length > 0;
  if (hasPdbOutput && pdbOutputs.some((output) => output.data === "start")) {
    nextCell.debuggerActive = true;
  }

  return nextCell;
}

// Should be called when a cell's code is registered with the kernel for
// execution.
export function prepareCellForExecution(
  cell: CellRuntimeState,
): CellRuntimeState {
  const nextCell = { ...cell };

  if (cell.status !== "disabled-transitively") {
    // TODO(akshayka): Move this to the backend. It's in the FE right now
    // to give the user immediate feedback.
    nextCell.status = "queued";
  }
  nextCell.interrupted = false;
  nextCell.errored = false;
  nextCell.runElapsedTimeMs = null;
  nextCell.debuggerActive = false;

  return nextCell;
}

/**
 * A cell's output is loading if it is running or queued.
 */
export function outputIsLoading(status: RuntimeState): boolean {
  return status === "running" || status === "queued";
}

/**
 * A cell's output is stale if it has been edited, is loading, or has errored.
 */
export function outputIsStale(
  cell: Pick<
    CellRuntimeState,
    "status" | "output" | "runStartTimestamp" | "interrupted" | "staleInputs"
  >,
  edited: boolean,
): boolean {
  const { status, output, runStartTimestamp, interrupted, staleInputs } = cell;

  // If interrupted, the output is not stale
  if (interrupted) {
    return false;
  }

  // If edited, the cell's output is stale
  if (edited) {
    return true;
  }

  // The cell is loading
  const loading = outputIsLoading(status);

  // Output is received while the cell is running (e.g. mo.output.append())
  const outputReceivedWhileRunning =
    status === "running" &&
    output !== null &&
    runStartTimestamp !== null &&
    (output.timestamp ?? 0) > runStartTimestamp;

  // If loading and output has not been received while running
  if (loading && !outputReceivedWhileRunning) {
    return true;
  }

  return staleInputs;
}

/**
 * Extract traceback information from a list of outputs.
 * This function searches for the first output with a mimetype of
 * "application/vnd.marimo+traceback" and parses its data to retrieve
 * all traceback details.
 */
export function outputToTracebackInfo(
  outputs: OutputMessage[],
): TracebackInfo[] | undefined {
  const firstTraceback = outputs.find(
    (output) => output.mimetype === "application/vnd.marimo+traceback",
  );
  if (!firstTraceback) {
    return undefined;
  }
  const traceback = firstTraceback.data;
  if (typeof traceback !== "string") {
    return undefined;
  }
  return extractAllTracebackInfo(traceback);
}