Skip to content

feat(app-preview): run local notebooks for run() - #619

Draft
tkislan wants to merge 7 commits into
mainfrom
tomaskislan/app-preview-runs
Draft

tkislan wants to merge 7 commits into
mainfrom
tomaskislan/app-preview-runs

Conversation

@tkislan

@tkislan tkislan commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

@coderabbitai ignore

Summary

In the app preview, a page's run(inputs) runs the workspace notebook that has that ID. The notebook runs headlessly in a new kernel on the toolkit server the extension runs for its .deepnote file. The project's init notebook runs first, then the notebook with the page's input values. Polling the run returns Deepnote's run shape, so run() resolves and result() returns the notebook's JSON.

Changes

  • POST /v2/runs and GET /v2/runs/:runId (appPreviewApi.node.ts).
    • Input values are checked against the notebook's input blocks. An input the notebook doesn't define, or a value that isn't a string, a boolean or a list of strings, answers 400.
    • Malformed JSON answers 400, and an oversized body answers 413.
  • AppPreviewRunner (appPreviewRunner.node.ts). For each run it:
    1. reads the file;
    2. finds the init notebook, in the same file or in a sibling file;
    3. opens the notebook document, so the integration endpoint serves the kernel its SQL credentials;
    4. resolves the interpreter and makes sure the toolkit is installed;
    5. starts the toolkit server;
    6. runs both notebooks through @deepnote/runtime-core's ExecutionEngine, with the project's integrations.
  • Block order. Blocks run in Deepnote's sortingKey order. runtime-core sorts with localeCompare, so the run's copy of the notebook is re-keyed first.
  • Outcomes: success, error, internal_error or stopped.
    • runtime-core reports a Python exception only as an error output. The run's error message is therefore ename: evalue, prefixed with Init notebook failed: when an init block fails.
  • Cancellation.
    • Before the kernel starts, every step checks the token.
    • Once the kernel runs, a cancellation stops the engine. That ends the running block, and the run ends stopped.
  • Run store. It keeps every unfinished run, each notebook's newest successful run, and up to 20 other finished runs.
  • Refactor. The init notebook runner's sibling init-notebook lookup and its Windows init-block adaptation are exported for reuse.
  • README.

Testing

  • Unit tests for the runner, with a fake ExecutionEngine that sorts and applies inputs like runtime-core 0.8.0. They cover:
    • each step's outcome and cancellation;
    • init failures;
    • block order;
    • the error message;
    • stopping the engine.
  • Unit tests for the API routes, with the runner as a ts-mockito mock whose runs each test settles: input validation, 400 and 413, outcomes, and the store's bound.
  • E2E, in the appPreview group, against a real kernel:
    • a successful run() whose result() returns the notebook's JSON;
    • a failing run showing ValueError: … and the outputs before it;
    • an unknown input rejected;
    • no "not supported" warning for run().
  • The E2E notebook uses Deepnote-written sorting keys, which localeCompare would reorder, so the test also checks the block order end to end.

Notes

  • There is no server-side run deadline, because the page's timeoutMs never reaches the server. A notebook that never finishes keeps its kernel until the window reloads.
  • Agent blocks run only when the provider's key, such as OPENAI_API_KEY, is in VS Code's own environment. runtime-core 0.8.0 cannot take the key the extension stores.
  • runtime-core ignores clear_output and update_display_data, so a block that redraws its JSON reports its first version.
  • Opening a legacy multi-notebook file for a run shows the "split it?" prompt, as opening it in the editor does.
  • Not verified: whether VS Code closes a notebook document opened without an editor before a slow kernel start fetches its SQL credentials.

@codecov

codecov Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 91.95980% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 39%. Comparing base (ab8fc86) to head (8fb1292).
✅ All tests successful. No failed tests found.

Files with missing lines Patch % Lines
...ebooks/deepnote/deepnoteInitNotebookRunner.node.ts 65% 4 Missing and 3 partials ⚠️
...books/deepnote/appPreview/appPreviewRunner.node.ts 94% 1 Missing and 4 partials ⚠️
...otebooks/deepnote/appPreview/appPreviewApi.node.ts 97% 0 Missing and 2 partials ⚠️
src/notebooks/serviceRegistry.node.ts 0% 1 Missing ⚠️
src/platform/common/utils/localize.ts 80% 1 Missing ⚠️
Additional details and impacted files
@@          Coverage Diff           @@
##            main    #619    +/-   ##
======================================
  Coverage     39%     39%            
======================================
  Files        832     834     +2     
  Lines      41939   42110   +171     
  Branches    9205    9246    +41     
======================================
+ Hits       16414   16581   +167     
+ Misses     23432   23431     -1     
- Partials    2093    2098     +5     
Files with missing lines Coverage Δ
...epnote/appPreview/appPreviewCommandHandler.node.ts 98% <100%> (+<1%) ⬆️
...ooks/deepnote/appPreview/appPreviewSession.node.ts 85% <100%> (+<1%) ⬆️
src/notebooks/deepnote/appPreview/types.ts 100% <100%> (ø)
src/notebooks/deepnote/deepnoteTestHelpers.ts 80% <100%> (+2%) ⬆️
src/notebooks/serviceRegistry.node.ts 0% <0%> (ø)
src/platform/common/utils/localize.ts 93% <80%> (-1%) ⬇️
...otebooks/deepnote/appPreview/appPreviewApi.node.ts 98% <97%> (-2%) ⬇️
...books/deepnote/appPreview/appPreviewRunner.node.ts 94% <94%> (ø)
...ebooks/deepnote/deepnoteInitNotebookRunner.node.ts 70% <65%> (+<1%) ⬆️

... and 2 files with indirect coverage changes

🚀 New features to boost your workflow:
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@tkislan
tkislan force-pushed the tomaskislan/app-preview-inputs branch from 171bba4 to 3617fe3 Compare November 16, 2026 07:21
@tkislan
tkislan force-pushed the tomaskislan/app-preview-runs branch from 1e619c2 to b8f166d Compare November 16, 2026 07:21
@tkislan
tkislan force-pushed the tomaskislan/app-preview-inputs branch from 3617fe3 to 2bb1879 Compare November 17, 2026 13:02
Base automatically changed from tomaskislan/app-preview-inputs to main November 18, 2026 11:01
…the Windows init-block swap

The app preview's run() executes the init notebook outside an editor kernel, so it
needs the same lookup and the same Windows replacement for Deepnote Cloud's %%bash
init block. Both move out of DeepnoteInitNotebookRunner unchanged; the lookup takes
the .deepnote file's URI instead of the notebook document.
POST /__deepnote/v2/runs and GET /__deepnote/v2/runs/:runId now answer as Deepnote
does instead of 501. A run executes the workspace notebook with that ID headlessly,
through @deepnote/runtime-core, in a new kernel on the toolkit server the extension
runs for its .deepnote file: the project's init notebook first with its saved
inputs, then the notebook with the page's inputs. The poll returns Deepnote's run
shape, so run() resolves and result() returns the notebook's JSON output.

- The body, the notebook and the inputs are validated with Deepnote's 400 messages.
- Blocks run in Deepnote's sorting-key order: the run's copy is re-keyed, because
  runtime-core sorts keys with localeCompare.
- A failing block's error is its message, or its Python exception's name and value;
  a failing init block's error starts with "Init notebook failed: ".
- A missing interpreter, a declined toolkit install, or a server or kernel that fails
  to start ends the run as internal_error.
- Closing the preview cancels its runs that have not reached their first block.
The page runs a notebook whose init notebook, in a sibling file, has an input of the
same name and another type, and shows each run's status and result(): an unknown
input rejects, a run succeeds with the notebook's JSON and the init notebook's saved
value, and a run whose last block raises ends as error with the exception and the
JSON displayed before it. The notebook's sorting keys are Deepnote-written ones that
localeCompare orders differently, so the second run's result also checks the block
order. No run() warning appears.
- Cancelling a run once its kernel is up now stops the kernel: runtime-core's
  stop() fails the executing block and shuts the session down, so the run ends as
  stopped instead of keeping the kernel until the window closes. Overlapping stop()
  calls throw, so every caller shares one.
- Runs pass the project's integrations to runtime-core, as the editor's agent
  cells do.
- A body express.json() rejects, such as malformed JSON or one over the size
  limit, gets its 4xx and message instead of a logged 500.
- The run store drops the oldest finished runs beyond 20, keeping unfinished runs
  and each notebook's newest successful run.
- The README says that agent blocks need the provider's key in VS Code's
  environment, that a run outlives the closed preview until the window reloads or
  closes, and that a legacy multi-notebook file shows its split prompt on the
  first run.
Replace the hand-written FakeRunner and its recording array in the API
tests with a ts-mockito mock of IAppPreviewRunner, as the notebook lookup
and the unsupported-operation callback already are. startRun() stubs
run() with a deferred outcome of its own, so a test settles the run it
started instead of indexing into the runner's calls.
@tkislan
tkislan force-pushed the tomaskislan/app-preview-runs branch from b8f166d to 8fb1292 Compare November 18, 2026 15:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant