Skip to content

docs(skill): document the hosted app client and how apps read notebook results - #553

Draft
voyti wants to merge 1 commit into
mainfrom
wojtek1/blu-6433-revive-the-dynamic-apps-skill-for-local-agents
Draft

docs(skill): document the hosted app client and how apps read notebook results#553
voyti wants to merge 1 commit into
mainfrom
wojtek1/blu-6433-revive-the-dynamic-apps-skill-for-local-agents

Conversation

@voyti

@voyti voyti commented Oct 6, 2026 •
edited by coderabbitai Bot
Loading

Copy link
Copy Markdown
Contributor

The viewer API section of apps.md told app authors to write the token handshake themselves. Deepnote hosts a browser client that does it, and no public doc mentioned the client or how an app gets notebook results into the page.

  • apps.md, Add viewer API access: leads with https://deepnote.com/static/app-client/v1.js and window.Deepnote.connect(). The handshake description stays for apps that call the API directly, which should now also send detachedRunStorageMode: "readonly".
  • apps.md, Return notebook results to an app (new):
    • a JSON output with a schema, built with to_json, because to_dict sends "nan" and fails on missing timestamps
    • the output size limits
    • how dataframe outputs page their rows and encode their values
  • blocks-code-and-sql.md: what deepnote_table_state.pageSize does.
  • Cloud app example: runs start with read-only project storage, as the guidance asks.

pnpm run lintAndFormat, pnpm typecheck, pnpm test (184 files, 3,368 tests), and cspell on the changed docs pass. The encoding statements were checked by running the toolkit's dataframe formatter and a real IPython kernel. The agent plugin counterpart is deepnote/agent-plugins#22.

Summary by CodeRabbit

  • New Features
    • Runs started from the example cloud app now use read-only storage.
  • Documentation
    • Expanded app viewer guidance for connecting, managing viewer tokens, starting runs, checking status, and selecting JSON results.
    • Added details on JSON output limits, dataframe paging and value representations, and read-only storage for runs.
    • Documented the table output pageSize setting, including its default and constraints.

@voyti
docs(skill): document the hosted app client and how apps read noteboo…
cce3213 
…k results

The viewer API section told app authors to hand-roll the token handshake and
said nothing about the client Deepnote hosts at /static/app-client/v1.js, which
handles the token, polling, and read-only runs. apps.md now leads with that
client and adds how an app gets notebook results: a JSON output with a schema,
or a dataframe output, which holds one page of rows with the total in
row_count and encodes values as described.

The cloud app example now starts its runs with read-only project storage, as
the guidance asks of clients that call the API directly.
@linear-code

linear-code Bot commented Oct 6, 2026

Copy link
Copy Markdown

BLU-6433

@voyti voyti mentioned this pull request Oct 6, 2026
Draft
@coderabbitai

coderabbitai Bot commented Oct 6, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: CHILL
  • Plan: Essentials
  • Run ID: 0768b440-b43d-447a-b890-6787a1fe28b4
📥 Commits

Reviewing files that changed from the base of the PR and between dc889f4 and cce3213.

📒 Files selected for processing (3)
  • examples/local-runner/cloud-app/index.html
  • skills/deepnote/references/apps.md
  • skills/deepnote/references/blocks-code-and-sql.md

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.

📝 Walkthrough

Walkthrough

The local runner now sets detachedRunStorageMode to readonly when starting a run. The app guidance adds a browser viewer flow, token handling details, and guidance for notebook JSON results and dataframe representations. The deepnote_table_state description now specifies how pageSize controls stored output rows.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~12 minutes

Change: Other

Suggested reviewers: jamesbhobbs

Merge Risk: ⚪ Minimal · up to cce32

No specific breakage is established in the viewer example or notebook-output guidance, so there is no identified merge-blocking risk.

🚥 Pre-merge checks | ✅ 6
✅ Passed checks (6 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly summarizes the main change: documenting the hosted app client and how apps read notebook results.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Updates Docs ✅ Passed The PR updates the OSS app documentation with the hosted client, direct API storage-mode guidance, notebook result formats, and dataframe paging details. It also updates the cloud app example and bloc…
  • Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Some tools did not complete. Review the errors below.

🔧 LanguageTool

LanguageTool checks were skipped: reviews.tools.languagetool.enabled_only requires at least one selection in enabled_rules or enabled_categories. Select rules/categories, set enabled_only to false to use the default rules, or set enabled to false to disable LanguageTool.

Comment @coderabbitai help to get the list of available commands.

@codecov

codecov Bot commented Oct 6, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.00%. Comparing base (dc889f4) to head (cce3213).

Additional details and impacted files 
@@           Coverage Diff            @@
##             main     #553    +/-   ##
========================================
  Coverage   90.00%   90.00%            
========================================
  Files         211      211            
  Lines       12451    12451            
  Branches     3588     3482   -106     
========================================
  Hits        11206    11206            
  Misses       1242     1242            
  Partials        3        3

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

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

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@coderabbitai coderabbitai[bot] coderabbitai[bot] approved these changes

At least 2 approving reviews are required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@voyti