feat(handoff): create a standalone report from a chat session

[cpsievert]

What this adds

querychat is great for exploring data conversationally — but today that exploration is trapped in the chat conversation. This PR lets a user turn the work they did during a querychat session into a standalone, runnable, downloadable handoff: a Quarto dashboard, a Shiny app, a Marimo or Jupyter notebook, or a freeform format they describe in words.

In short: chat your way to the right queries and visualizations, then use the /handoff slash command. You'll be prompted with a dialog to choose relevant findings, an output format (e.g., Quarto, Jupyter, etc), a language (e.g., R and Python), and addition instructions for generating the "handoff" document. This standalone document, a README, as well as the data (if it's small enough), will all be bundled into downloaded zip file.

Why it's useful

• Bridges exploration → deliverable. Insights found by asking questions become a reproducible asset.
• Meets people where they work. Pick the output format (dashboard / app / notebook) and language (R or Python) that fits the team.
• Self-contained. Small datasets are bundled as CSV so the handoff runs as-is; larger / DB-backed sources get a clearly-marked data-setup TODO.
• Iterative. Revise with AI and download a zip (source + README + data).

ℹ️ Python-only for now (pkg-py). See Limitations.

See it in action

Upon requesting a new handoff:

After generating the handoff:

How it works (user's-eye view)

1. Open the Prepare Handoff modal — type /handoff, or the assistant offers it when it senses you're ready.
2. The modal shows a gallery of the session's queries & charts, an output-format picker, a language picker, and a directions box. An LLM recommendation pre-selects sensible defaults while it opens.
3. Hit Generate — a side panel slides open and the handoff source streams into a read-only editor; a pill is added to the chat linking back to it.
4. From the panel: revise with AI and download the zip.
5. State survives bookmarking, so a restored session re-shows its handoffs.

Approach & architecture (for reviewers)

Built around a few deliberate constraints:

• A hard reactivity boundary. HandoffOrchestrator is plain async business logic — reads no reactive.Value, defines no effects, never touches input.*. All reactivity lives in handoff_server(). That's what lets every flow be unit-tested with plain fakes.
• One owner per concern.
  • HandoffView — the only place server→client output happens (custom messages, modal, chat pill).
  • HandoffChat — the only place chatlas is touched; deep-copies the live chat before each call, so generate/revise/recommend never pollute the visible conversation.
  • HandoffStore — the only place handoffs are held (LRU) and serialized.
  • active_handoff_id — a single reactive value, the sole source of truth for panel visibility.
• State is pydantic; bookmarks stay small. HandoffState holds the current source plus cumulative turns. Immutable CSV snapshots live in a bounded in-session bundle store, not bookmark payloads; if a restored handoff's snapshot is unavailable, its source remains viewable but download is disabled.
• Tool names are a shared contract centralized in _tool_names.py, so tool registration and the gallery that mines chat turns can't silently drift.
• Two entry paths, one modal-opening path. The /handoff command and the querychat_request_handoff tool converge on the same flow (the tool fires mid-stream where no reactive context exists, so it relays through a status-gated effect).

Browser (handoff-core.ts)
   ▲  querychat-handoff-* messages         │ inputs / setInputValue
   │                                        ▼
handoff_server()   ← all reactivity, active_handoff_id
   │ drives
   ▼
HandoffOrchestrator   ← no reactive state
   ├── HandoffChat   (chatlas fork + streaming)
   ├── HandoffView   (server→client, modal, pill)
   ├── HandoffStore  (LRU + bookmark)
   └── pure helpers  (data · prompt · gallery · readme)

Limitations & things to know

• Depends on unreleased shinychat. Relies on shinychat slash commands and a recent shiny; pyproject.toml currently pins shinychat to the dev/querychat-pr311-history-save git branch. This must move to a released version before any release.
• Python only. No R counterpart yet; the layering is a reasonable template if/when parity is pursued.
• Always-on, no opt-out. The tool and /handoff command register regardless of the tools= config, and the panel UI is always injected. Deliberate by omission — worth revisiting.
• The Py↔JS wire contract is hand-duplicated on both sides with no shared schema; a rename in one language silently no-ops in the other. Known maintenance hazard.
• Generated front-end assets are committed. static/js/handoff.js / static/css/handoff.css are build outputs of js/src/* — edit the source and rebuild, never the generated files.
• Stored handoffs are LRU-capped (25/session); reopening an evicted handoff's pill no-ops.
• Data bundling threshold: DataFrame sources ≤ 5 MB are bundled as CSV; larger or DB-backed sources get a data-setup TODO.

Testing

• Unit tests per module (tests/test_handoff_*.py); the orchestrator suite runs on plain fakes thanks to the no-reactive-state rule.
• Playwright integration tests (test_13_handoff.py, test_15_handoff_module_scope.py) cover the modal, generation, panel, pill navigation, browser-history restore, and module scoping.
• Full Python unit suite passes locally; handoff e2e (modal → generate → panel → pill) verified against a live LLM.