description: "Web Session-log ZIP export: Host streaming, the authenticated download route, the Session Header action, and the /export command." kind: "package-reference"

@xlaunch/session-log-export

Summary

xlaunch-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 xlaunch-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: '@xlaunch/session-log-export'

The Web bundle mounts the package with Connection, xlaunch-commands, xlaunch-client-ui-commands, and xlaunch-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. 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.

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

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.

• xlaunch-client-connection — the authenticated Fetch-route carrier used by the Host endpoint.
• Commands subsystem reference — the human-command registry the /export command registers on.
• xlaunch-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

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.