deepseek-harness/packages/session-query/session-log-export

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 Session log button in the Session Header 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 click Session log in the Session Header or type /export; the browser downloads dsh-session-<id>.zip.

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 GET /api/session.export?sessionId=<id>&includeDescendants=true
/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.

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.

Download flow

Both entry paths issue a HEAD preflight to GET /api/session.export?..., then hand the GET URL 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 /export command 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.