feat(web,hub): export session conversation as JSON or Markdown download

[swear01]

What feature would you like to see?

Export the entire session conversation from the web UI as a single file download.

User flow

• Session header overflow menu (⋯) → Export conversation
• Small dialog: choose format JSON (default) or Markdown, then Download
• Remember last format in localStorage (hapi.sessionExportFormat)
• Show loading / error toasts; support AbortController if the user leaves mid-export
• Trigger browser download via Blob + <a download> (desktop + mobile PWA)

Why JSON is the default

• Lossless: preserves hub DecryptedMessage + session metadata (tools, codex, attachments meta, etc.)
• Markdown is a human-readable derived view from the same payload, not a second source of truth

Hub: single export endpoint

GET /api/sessions/:id/export

Returns HapiSessionExport v1 (format-agnostic):

{
  "schemaVersion": 1,
  "exportedAt": 1730000000000,
  "session": { },
  "messages": []
}

• Same auth as existing session routes (requireSessionFromParam)
• Server-side getAllMessagesForExport(sessionId) — do not paginate via repeated public /messages calls from the browser
• Apply visible-message filtering consistent with the chat UI where applicable
• Hard cap (e.g. 20_000 messages) → 413 with a clear message; no silent truncation

Web serialization

• JSON: JSON.stringify(payload, null, 2) → .json
• Markdown: serializeSessionMarkdown(payload) using normalizeDecryptedMessage; skip nulls; ## User / ## Assistant sections; concise tool summaries; optional YAML front matter → .md
• Filename example: {title-slug}-{sessionId-8chars}-{YYYY-MM-DD}.{json|md}

Suggested files

• shared/src/sessionExport.ts — schema/types
• hub/src/store/messages.ts — export query helper
• hub/src/web/routes/sessions.ts — route
• web/src/lib/sessionExport/* — fetch, download helper, markdown serializer + tests
• web/src/components/SessionHeader.tsx — menu + dialog
• web/src/lib/locales/en.ts, zh-CN.ts

Additional information

Motivation

• No full-session backup/share path today; only paginated GET /api/sessions/:id/messages (200/page)
• Per-message copy is desktop-only for assistant text (bug(web): copy button on assistant messages always visible on mobile, looks misplaced #456 hid mobile copy button) and does not cover whole sessions

Acceptance criteria

• GET /api/sessions/:id/export returns HapiSessionExport v1 (session + chronological visible messages)
• Over cap → 413, explicit error
• Export menu in session header; JSON default; format preference persisted
• JSON download matches API payload (pretty-print OK)
• Markdown generated from the same payload (one fetch)
• File download works on desktop and mobile browsers
• Tests: hub route (empty, multi-message, over-limit); serializeMarkdown unit tests

Out of scope

• Import / restore
• Batch export all sessions
• PDF / CSV / screenshot
• CLI export command
• Per-message mobile long-press copy (bug(web): copy button on assistant messages always visible on mobile, looks misplaced #456 follow-up)

Prior art
Open WebUI, LibreChat, LobeChat: JSON as canonical export + optional Markdown for reading.

Manual test plan

1. Short session → JSON → verify count/order
2. Same session → Markdown → readable structure
3. Reload → format preference retained
4. Very long session → 413 or success with clear UX
5. iPhone PWA / Android Chrome → file downloads

[github-actions]

This is not implemented in the current codebase. The existing web API only exposes paginated session messages, with limit validated to a maximum of 200, so a full-session export should not be built by looping over the public messages endpoint from the browser. Your proposed single hub endpoint matches the current route/guard structure.

The chat UI already does additional client-side visibility work before rendering: it removes queued/uninvoked messages from the timeline and then skips messages whose normalizeDecryptedMessage() result is null. A Markdown export should reuse that normalization path if it is meant to match the readable chat view.

Relevant code:

• hub/src/web/routes/messages.ts:10 - current GET /api/sessions/:id/messages route.
• shared/src/apiTypes.ts:148 - messages query schema caps limit at 200.
• hub/src/web/routes/guards.ts:35 - requireSessionFromParam session access guard used by session routes.
• hub/src/sync/messageService.ts:10 - server-side visible-message filtering for redundant goal status events.
• hub/src/sync/messageService.ts:53 - current page-based message service API.
• hub/src/store/messages.ts:155 - DB pagination query orders messages by display position and returns ascending display order.
• web/src/components/SessionActionMenu.tsx:232 - current overflow menu actions are rename plus archive/delete; no export action found.
• web/src/components/SessionChat.tsx:312 - chat timeline excludes queued messages before rendering.
• web/src/chat/normalize.ts:8 - normalizeDecryptedMessage() returns null for skipped readable-chat messages.
• web/src/api/client.ts:200 - web client currently has getMessages(), but no export fetch helper found.

No more info needed from the issue as written; the acceptance criteria are specific enough for implementation.

---

HAPI Bot