8.5 KiB
description, kind
| description | kind |
|---|---|
| Web Session-log ZIP export: Host streaming, the authenticated download route, the Session Header action, and the /export command. | package-reference |
@deepseek-ai/dsh-session-log-export
English | 中文
Summary
dsh-session-log-export lets the Web interface download a session's full history: a Download session log menu item under the Session Header's more-actions button and an /export slash command both hand the session tree — the session, its sub-sessions, and attachments — to the browser as a ZIP download. The package owns the Host archive stream, its authenticated Fetch route, and the browser controls and feedback. The browser chooses the download destination. Setup and usage come first; implementation details follow.
Table of Contents
- Use this package
- Understand the implementation
- Further Exploration
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Use this package
Use this package when the Web bundle should let users export a session log. It requires Connection, the command registry, Session query and persistence, and attachments. Mount the plugin, then choose Download session log from the Session Header's more-actions menu or type /export; the browser downloads dsh-session-<id>.zip.
When ui-message-feedback is mounted, the same menu also offers Feedback, which opens its existing Session feedback dialog. Opening or dismissing that form does not export the Session or submit feedback. The feedback row follows the feedback plugin's availability; export remains available independently.
When to choose it
Choose it for a Web deployment that needs user-facing session export with a visible download dialog. Avoid it when a programmatic or Host-side export is needed: this package produces a browser download, not a Host path write. The logs are serialized from persistence read handles, so any mounted backend is supported.
Composition
- id: session-log-download
name: '@deepseek-ai/dsh-session-log-export'
The Web bundle mounts the package with Connection, dsh-commands, dsh-client-ui-commands, and dsh-client-ui-conversation.
Configuration
| Field | Default | Meaning |
|---|---|---|
compressionLevel |
6 |
DEFLATE level from 0 through 9 for each ZIP entry. |
Command contract
| Input | Result |
|---|---|
/export |
Records a human-command lifecycle; the submitting browser downloads the document-relative api/session.export?sessionId=<id>&includeDescendants=true (Host route /api/session.export) |
/export <path> |
An error; browser downloads choose their destination through the browser's ordinary download behavior |
What to expect
The dialog reports three phases: preparing, download started, or failed. Closing the dialog does not cancel an in-flight download, and the dialog does not reopen when that operation later settles. One session admits one active download at a time; repeated gestures share that operation. The export includes the live session's newest events: the host endpoint flushes a live root session before reading, so a slash-triggered ZIP includes the command/run and command/done pair that started the download; cold persisted sessions need no flush. Each logical log uses the current generation's canonical filename inside the archive (session.jsonl for v0, otherwise session.vN.jsonl), including beneath each sub-session directory. Images use media/<attachmentId>.<ext>, and generic files use files/<digest-prefix>/<digest>/<name>. Generic-file bytes are read and compressed as bounded chunks, so exporting a large upload does not buffer it in full.
Attachment collection reads declared content fields of built-in Session events and completed assistant stream blocks, including flat V4 tool-role messages. Unknown event payloads and unrelated fields remain unchanged in the exported log but do not cause attachment reads.
Failures
The dialog shows a preparation error when the preflight fails before ZIP streaming starts — for example an unreachable or misconfigured host endpoint. A descendant or attachment read failure after the browser accepts the GET is reported by the browser download manager, not by the dialog.
Understand the implementation
Implementation internals — click to expand
This section explains how the package wires the export control and points at the code that realizes it; the observable behavior is fully covered in Use this package.
Design split
The package has two halves. The Host half (src/index.ts) registers the /export command and contributes the exact GET/HEAD /api/session.export Fetch route to Connection; src/archive.ts builds the bounded ZIP stream. The browser half (src/client/index.ts) provides the shared download controller and UI, and observes command/executed so only the submitting browser starts a download.
The Header’s More action uses the shared compact Button, with a 28px square target and the same radius and hover fill as the right-sidebar expand control.
Download flow
Both entry paths issue a HEAD preflight to the document-relative api/session.export?..., then hand the GET route to the browser download manager without buffering the ZIP in JavaScript. One controller owns one in-flight download per session, collapses concurrent gestures into that operation, and cancels the preflight on plugin disposal. Modal state lives in a snapshot store keyed by session, so the button and the command share one dialog per session.
The Host route is a feature-owned exact Fetch contribution. Connection applies its Host/Origin and browser-session checks and bridges the streaming Response; this package owns query validation, live-session flushes, handle-based log reads and attachment reads, ZIP generation, and HTTP status semantics.
Further Exploration
Read these pages when the package-level contract is not enough. They move from the Web control to the host endpoint and the surrounding command and session surfaces.
- dsh-client-connection — the authenticated Fetch-route carrier used by the Host endpoint.
- Commands subsystem reference — the human-command registry the
/exportcommand registers on. - dsh-client-ui-commands — the browser command surface that renders and acknowledges
/export. - Session Query package map — the retrieval family this package belongs to.
Model Experience
Human /export control
What the model sees
Nothing. /export stays on the human-command plane, and the ZIP download does not enter model history.
Token effect
Zero. The command creates no model turn.
KV Cache effect
None. The log-only command lifecycle and browser download do not change the derived request prefix.
Known Limitations and Deferred Work
These limits define when this package is a poor fit or needs special operational care. They are current package constraints, not a task backlog.
- Browser download, not a Host-path writer — the browser chooses the local destination; no Host path or native folder action is returned.
- Preflight reports only pre-stream failures — a descendant or attachment failure after the browser accepts the GET is reported by the browser download manager, not by the dialog.
Dev Note
Working context for maintainers — click to expand
This Dev Note is working context for maintainers: open design questions and directions that are not decided. It is explicitly non-authoritative — shipped behavior, limits, and accepted rationale live in the sections above, the package code, and the linked pages.
Future: export destinations beyond the browser
The download is deliberately browser-scoped; a Host-path or native folder export would need a new endpoint contract and a decision on where the ZIP lands.
Runtime invariant: No companion is published. Connection and the command registry own both registrations, while each export reads authoritative Session services.