feat(local-runner): durable notebook steps for Workflow SDK - #499

4 of 4. Stacked on #498 → #497 → #496. Its only real dependency is #496 (the engine); it sits on the tip to avoid conflicting with #498 over tsdown.config.ts and package exports.

Closes the gap the first three PRs leave: they ship one-shot orchestration and no durability story at all.

orchestrate() holds its state in one process and is gone if that process is — right for a script or an interactive page, wrong for anything scheduled or long-lived.

import { runNotebookStep } from "@deepnote/local-runner/workflows";

export async function salesReview() {
  "use workflow";
  const regions = await Promise.all(
    REGIONS.map((r) => runNotebookStep({ id: r.name, notebookId: r.notebookId })),
  );
  return runNotebookStep({ id: "arbiter", notebookId: ARBITER, inputs: { … } });
}

Delegating rather than reimplementing

This branch's history is instructive: a checkpoint/resume layer and a retry-policy layer were both built here and then deliberately removed (remove the checkpoint/resume persistence layer, remove runWithPolicy, point durability at Workflow SDK). That was the right call — growing your own durable execution is how an orchestration library turns into a bad workflow engine. Replay, retries, timers, and observability are a real engine's job.

Costs nothing to consumers who don't want it

workflow is an optional peer dependency. Without its compiler the 'use step' directive is inert and runNotebookStep is an ordinary async function — which is also how the tests exercise it. Zero lockfile churn (verified: no diff against #498).

This is why the library piece is here and the Nitro/Vite example from #435 is not — that example is what brought nitro@…-beta, vite@^8, and ~5,275 lines of lock. It can follow separately if wanted.

Two deliberate choices worth reviewing

• The token is read from the environment inside the step, not taken as an argument, so the credential stays out of the workflow's arguments and therefore out of its persisted event log.
• maxRetries = 0. A notebook may write files, mutate databases, or spend model budget. Repeating that implicitly is not a safe default; a consumer who has made a notebook idempotent can wrap it in their own step with whatever policy they want.

Separate entry point (/workflows) because this is server-side by definition — a durable engine needs a process that outlives a page — and it reads process.env.

6 new tests, including that the result survives a JSON round trip across a step boundary. Full suite, typecheck, lint, prettier, cspell green.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added durable workflow support for running Deepnote notebooks with runNotebookStep.
  • Notebook workflows now support polling configuration, serializable results, custom API origins, and explicitly allowed failed runs.
  • Workflow-managed retries, timers, replay, and observability are supported.
  • Added a public workflows package entry point for easier integration.

• Documentation

  • Added setup and usage guidance, including environment-based credential configuration and notebook retry behavior.