@deepseek-ai/dsh-session-log-export 0.1.2-alpha.5 → 0.1.3-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session-query/session-log-export/README.md
-README.md: a096cea71b2e0bed4882a6e8d23c8f35dc3d0fb7
-README.zh.md: 0c2da35ae0be9420cfd6ff076dd038c3a8edf2cb
+README.md: db26d9c405b3408cc24f27e5947c94ccaa2393e8
+README.zh.md: 4e2eb00de94dd6520af8c1836155a00d187ef99f

package/README.md

@@ -29,7 +29,7 @@ Use this package when the Web bundle should let users export a session log. It r
 
 ### 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, and it requires the shipped JSONL provider's per-Session raw artifact in plaintext or zstd form.
+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
 
@@ -55,7 +55,7 @@ The Web bundle mounts the package with Connection, `dsh-commands`, `dsh-client-u
 
 ### 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.
+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
 
@@ -79,7 +79,7 @@ The package has two halves. The Host half ([`src/index.ts`](src/index.ts)) regis
 
 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, raw artifact and attachment reads, ZIP generation, and HTTP status semantics.
+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.
 
 </details>
 
@@ -121,7 +121,6 @@ None. The log-only command lifecycle and browser download do not change the deri
 
 These limits define when this package is a poor fit or needs special operational care. They are current package constraints, not a task backlog.
 
-- **Requires a per-Session raw artifact** — the download endpoint reads the shipped JSONL provider's plaintext or zstd artifact; an out-of-tree provider without a raw artifact cannot serve this route.
 - **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.
 

package/README.zh.md

@@ -29,7 +29,7 @@ kind: "package-reference"
 
 ### 何时选择
 
-为需要带可见下载弹窗的用户级会话导出的 Web 部署选择它。需要程序化或 Host 侧导出时避免使用：本包产生的是浏览器下载，而非 Host 路径写入，并且它要求随产品交付的 JSONL provider 提供逐 Session 的明文或 zstd 原始产物。
+为需要带可见下载弹窗的用户级会话导出的 Web 部署选择它。需要程序化或 Host 侧导出时避免使用：本包产生的是浏览器下载，而非 Host 路径写入。日志从持久化读句柄序列化而来，因此任何已挂载后端都受支持。
 
 ### 组合
 
@@ -55,7 +55,7 @@ Web bundle 将本包与 Connection、`dsh-commands`、`dsh-client-ui-commands`
 
 ### 预期行为
 
-弹窗报告三个阶段：准备中、开始下载或失败。关闭弹窗不会取消正在进行的下载，该操作随后完成时弹窗也不会重新打开。每个会话同时只允许一项下载，重复操作共用该任务。导出包含实时会话的最新事件：Host 端点在读取前会 flush 活动的根会话，因此斜杠命令触发的 ZIP 会包含启动下载的 `command/run` 与 `command/done` 事件对；冷持久化会话不需要 flush。
+弹窗报告三个阶段：准备中、开始下载或失败。关闭弹窗不会取消正在进行的下载，该操作随后完成时弹窗也不会重新打开。每个会话同时只允许一项下载，重复操作共用该任务。导出包含实时会话的最新事件：Host 端点在读取前会 flush 活动的根会话，因此斜杠命令触发的 ZIP 会包含启动下载的 `command/run` 与 `command/done` 事件对；冷持久化会话不需要 flush。每份逻辑日志在归档中使用当前 generation 的规范文件名（v0 为 `session.jsonl`，其他版本为 `session.vN.jsonl`），每个子会话目录下也遵循同一规则。图片使用 `media/<attachmentId>.<ext>`，通用文件使用 `files/<digest-prefix>/<digest>/<name>`。通用文件以有界分块读取并压缩，因此导出大文件时不会把它完整缓冲进内存。
 
 ### 失败
 
@@ -79,7 +79,7 @@ Web bundle 将本包与 Connection、`dsh-commands`、`dsh-client-ui-commands`
 
 两条入口都会对 `GET /api/session.export?...` 发出 `HEAD` 预检，然后把 GET URL 交给浏览器下载管理器，JavaScript 不缓冲 ZIP。一个控制器按会话持有一项进行中的下载，把并发操作折叠进该任务，并在插件释放时取消预检。弹窗状态存放在按会话键控的快照存储中，因此按钮与命令按会话共享一个弹窗。
 
-Host 路由是业务拥有的精确 Fetch contribution。Connection 应用 Host/Origin 与浏览器会话检查并桥接流式 `Response`；本包拥有查询校验、活动会话 flush、原始产物与附件读取、ZIP 生成和 HTTP 状态语义。
+Host 路由是业务拥有的精确 Fetch contribution。Connection 应用 Host/Origin 与浏览器会话检查并桥接流式 `Response`；本包拥有查询校验、活动会话 flush、基于句柄的日志读取与附件读取、ZIP 生成和 HTTP 状态语义。
 
 </details>
 
@@ -121,7 +121,6 @@ Host 路由是业务拥有的精确 Fetch contribution。Connection 应用 Host/
 
 这些限制说明本包何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是任务积压。
 
-- **要求逐 Session 原始产物**——下载端点读取随产品交付的 JSONL provider 所提供的明文或 zstd 产物；没有原始产物的仓库外 provider 无法服务该 route。
 - **浏览器下载，而非 Host 路径写入**——目标位置由浏览器选择；不会返回 Host 路径或原生文件夹操作。
 - **预检只报告流式传输前的失败**——浏览器接受 GET 后发生的子会话或附件读取失败由浏览器下载管理器报告，不通过弹窗报告。
 

package/lib/client.js

@@ -169,7 +169,7 @@ window.__ModuleLoader__.load({
 		}
 		//#endregion
 		//#region \0dsh-css:/home/runner/work/deepseek-harness/deepseek-harness/packages/session-query/session-log-export/src/client/HeaderAction.module.css.mjs
-		const css = ".nL4_yW_sessionLogButton{border:.5px solid var(--dsw-alias-border-l4);min-width:111px;height:32px;color:var(--dsw-alias-label-primary);font-family:var(--dsw-font-family);cursor:pointer;background:0 0;border-radius:18px;justify-content:center;align-items:center;gap:4px;padding:6px 12px;font-size:13px;font-weight:400;line-height:20px;display:inline-flex}.nL4_yW_sessionLogButton:hover:not(:disabled){background:var(--dsw-alias-interactive-bg-hover)}.nL4_yW_sessionLogButton:disabled{color:var(--dsw-alias-label-dimmed);cursor:wait}.nL4_yW_sessionLogButton span,.nL4_yW_sessionLogButton svg{flex:none}.nL4_yW_sessionLogButton span{white-space:nowrap}";
+		const css = ".nL4_yW_sessionLogButton{border:.5px solid var(--dsw-alias-border-l4);height:26px;color:var(--dsw-alias-label-primary);font-family:var(--dsw-font-family);cursor:pointer;background:0 0;border-radius:13px;justify-content:center;align-items:center;gap:5px;padding:5px 10px;font-size:11px;font-weight:400;line-height:16px;display:inline-flex}.nL4_yW_sessionLogButton:hover:not(:disabled){background:var(--dsw-alias-interactive-bg-hover)}.nL4_yW_sessionLogButton:disabled{color:var(--dsw-alias-label-dimmed);cursor:wait}.nL4_yW_sessionLogButton span,.nL4_yW_sessionLogButton svg{flex:none}.nL4_yW_sessionLogButton svg{color:var(--dsw-alias-label-secondary)}.nL4_yW_sessionLogButton span{white-space:nowrap}";
 		const tagId = "@deepseek-ai/dsh-session-log-export/HeaderAction.module.css";
 		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {
 			const tag = document.createElement("style");
@@ -197,7 +197,7 @@ window.__ModuleLoader__.load({
 				onClick: () => {
 					request(sessionId);
 				},
-				children: [(0, react_jsx_runtime.jsx)("span", { children: t("header.action") }), (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconDownloadOutline16, { size: 12 })]
+				children: [(0, react_jsx_runtime.jsx)("span", { children: t("header.action") }), (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconDownloadOutline16, { size: 10 })]
 			}), (0, react_jsx_runtime.jsx)(SessionLogDownloadDialog, { ...props })] });
 		}
 		//#endregion

package/lib/index.js

@@ -1,20 +1,25 @@
 import Schema from "@deepseek-ai/schemastery";
 import { brandString } from "@deepseek-ai/dsh-brand";
 import { Zip, ZipDeflate } from "fflate";
+import { SESSION_FORMAT_VERSION } from "@deepseek-ai/dsh-session";
+import { sessionFormatLogFilename } from "@deepseek-ai/dsh-session-format";
+import { SessionPersistenceNotFoundError } from "@deepseek-ai/dsh-session-persistence";
 //#region lib/types/archive.js
 /**
 * Host-side session-log download: streams one ZIP archive whose files are the
-* sessions' stored artifact text verbatim plus every referenced media object.
-* The root artifact sits under its original base name (`session.jsonl`); each
-* subagent descendant under `subagents/<id>/<filename>`; each image referenced
-* by any included log under `media/<attachmentId>.<ext>` (content-addressed,
-* so one archive never duplicates a shared image). No manifest is written —
-* every file is byte-identical to the backend's durable artifact or attachment
-* store and self-describing through its own header line or media type. Before
-* each live session's artifact read, the SessionStore flush barrier makes the
-* current in-memory log durable; cold sessions need no barrier. Request abort
-* and response-consumer cancellation share one producer signal and terminate
-* the active compressor.
+* sessions' logical session logs plus every referenced attachment. Each log
+* is read through a persistence read handle and serialized here as canonical
+* JSONL — one header line, then one line per validated event — so every
+* backend (JSONL, SQLite, future) exports identically. The root log uses the
+* current generation's canonical `session[.vN].jsonl` name; each subagent
+* descendant uses `subagents/<id>/session[.vN].jsonl`; each image referenced by any included log
+* under `media/<attachmentId>.<ext>` (content-addressed, so one archive never
+* duplicates a shared image); each generic file sits under
+* `files/<prefix>/<digest>/<name>` and streams from the attachment store. No
+* manifest is written. Before each live session's log read, the SessionStore
+* flush barrier makes the current in-memory log durable; cold sessions need no
+* barrier. Request abort and response-consumer cancellation share one producer
+* signal and terminate the active compressor.
 * Compression runs on the host with fflate's streaming Zip API, so the archive
 * bytes are produced incrementally and the host never holds the whole archive
 * in one buffer; production waits for consumer pull whenever the response queue
@@ -39,7 +44,7 @@ function sessionLogExportDeps(ctx) {
 }
 /**
 * Flush one currently live session through the store's authoritative durability
-* barrier immediately before its raw artifact is read. A cold or absent id has
+* barrier immediately before its logical log is read. A cold or absent id has
 * no in-memory work to flush.
 * @param deps - export services, including the optional live-session store.
 * @param id - the session whose artifact is about to be read.
@@ -54,6 +59,57 @@ async function flushLiveSessionLog(deps, id, signal) {
 	await sessions.flush(session);
 	signal?.throwIfAborted();
 }
+/** The current generation's canonical base filename for every exported session log. */
+const SESSION_LOG_FILENAME = sessionFormatLogFilename(SESSION_FORMAT_VERSION);
+/**
+* Serialize one session's logical log as canonical JSONL text: the header
+* line, then one line per event, with a trailing newline.
+* @param header - the session's immutable header.
+* @param events - the validated committed events in seq order.
+* @returns the JSONL text.
+*/
+function serializeSessionLog(header, events) {
+	const lines = [JSON.stringify({
+		type: "session",
+		version: header.version,
+		id: header.id,
+		createdAt: header.createdAt,
+		...header.cwd !== void 0 ? { cwd: header.cwd } : {},
+		...header.parentSession !== void 0 ? { parentSession: header.parentSession } : {},
+		isSeeded: header.isSeeded,
+		...header.origin !== void 0 ? { origin: header.origin } : {},
+		delegationDepth: header.delegationDepth ?? 0,
+		...header.agentPreset !== void 0 ? { agentPreset: header.agentPreset } : {}
+	})];
+	for (const event of events) lines.push(JSON.stringify(event));
+	return `${lines.join("\n")}\n`;
+}
+/**
+* Read one session's complete logical log through a read handle and serialize
+* it. The read observes the committed log only — persistence never returns a
+* torn tail — and a handle read after a resolved flush observes at least the
+* flushed prefix.
+* @param persistence - the mounted persistence backend.
+* @param id - the session to read.
+* @param signal - optional cancellation forwarded to the open and read.
+* @returns the serialized JSONL text, or `undefined` when the session does not exist.
+*/
+async function readSessionLogText(persistence, id, signal) {
+	const options = signal === void 0 ? {} : { signal };
+	let handle;
+	try {
+		handle = await persistence.open(id, "read", options);
+	} catch (error) {
+		if (error instanceof SessionPersistenceNotFoundError) return void 0;
+		throw error;
+	}
+	try {
+		const { events } = await handle.read(0, void 0, options);
+		return serializeSessionLog(handle.header, events);
+	} finally {
+		await handle.close();
+	}
+}
 /** Zip extension for each accepted raster media type. */
 const MEDIA_TYPE_EXTENSIONS = {
 	"image/png": "png",
@@ -71,13 +127,21 @@ const MEDIA_TYPE_EXTENSIONS = {
 function mediaEntryPath(ref) {
 	return `media/${String(ref.attachmentId)}.${MEDIA_TYPE_EXTENSIONS[ref.mediaType]}`;
 }
+/** Archive path that preserves one stored file reference's digest and name. */
+function fileEntryPath(ref) {
+	const digest = String(ref.attachmentId).replace(/^sha256:/u, "");
+	const name = ref.name.replace(/[\\/\u0000-\u001f\u007f]/gu, "_");
+	const safeName = name === "." || name === ".." || name === "" ? "file" : name;
+	return `files/${digest.slice(0, 2)}/${digest}/${safeName}`;
+}
 /**
-* Collect every image reference inside one content array, descending into
+* Collect every attachment reference inside one content array, descending into
 * nested tool results the way the live attachment route does.
 * @param content - an event content array (or nested tool-result content).
-* @param refs - the dedupe map being filled (keyed by attachment id).
+* @param images - image dedupe map keyed by attachment id.
+* @param files - file dedupe map keyed by attachment id and stored name.
 */
-function collectImageRefs(content, refs) {
+function collectAttachmentRefs(content, images, files) {
 	if (!Array.isArray(content)) return;
 	const pending = [];
 	for (const item of content) pending.push(item);
@@ -87,36 +151,44 @@ function collectImageRefs(content, refs) {
 		const block = value;
 		if (block.type === "image" && typeof block.attachment === "object" && block.attachment !== null) {
 			const ref = block.attachment;
-			refs.set(String(ref.attachmentId), ref);
+			images.set(String(ref.attachmentId), ref);
+		}
+		if (block.type === "file" && typeof block.attachment === "object" && block.attachment !== null) {
+			const ref = block.attachment;
+			files.set(`${String(ref.attachmentId)}\u0000${ref.name}`, ref);
 		}
 		if (Array.isArray(block.content)) for (const item of block.content) pending.push(item);
 	}
 }
 /**
-* Collect every image reference one session event carries, across the same
+* Collect every attachment reference one session event carries, across the same
 * carriers the live attachment route scans (direct content, message content,
-* inserted messages, and completed assistant chunk blocks).
+* inserted messages, and completed blocks in embedded Assistant streams).
 * @param event - one parsed JSONL event object.
-* @param refs - the dedupe map being filled (keyed by attachment id).
+* @param images - image dedupe map keyed by attachment id.
+* @param files - file dedupe map keyed by attachment id and stored name.
 */
-function collectEventImageRefs(event, refs) {
+function collectEventAttachmentRefs(event, images, files) {
 	const data = event.data;
 	if (typeof data !== "object" || data === null) return;
 	const carrier = data;
-	collectImageRefs(carrier.content, refs);
-	if (carrier.message !== void 0) collectImageRefs(carrier.message.content, refs);
-	if (carrier.inserted !== void 0) for (const message of carrier.inserted) collectImageRefs(message.content, refs);
-	if (carrier.chunk?.type === "block-end") collectImageRefs([carrier.chunk.block], refs);
+	collectAttachmentRefs(carrier.content, images, files);
+	if (carrier.message !== void 0) collectAttachmentRefs(carrier.message.content, images, files);
+	if (carrier.inserted !== void 0) for (const message of carrier.inserted) collectAttachmentRefs(message.content, images, files);
+	if (carrier.stream !== void 0) {
+		for (const record of carrier.stream) if (record.type === "chunk" && record.chunk?.type === "block-end") collectAttachmentRefs([record.chunk.block], images, files);
+	}
 }
 /**
-* Collect the distinct media references one stored artifact text names.
-* Lines that fail to parse cannot reference media and are skipped (the
+* Collect the distinct attachment references one stored artifact text names.
+* Lines that fail to parse cannot reference attachments and are skipped (the
 * artifact text itself is exported verbatim regardless).
 * @param content - the stored artifact text.
-* @returns the dedupe map keyed by attachment id.
+* @returns image and file dedupe maps.
 */
-function imageRefsInArtifact(content) {
-	const refs = /* @__PURE__ */ new Map();
+function attachmentRefsInArtifact(content) {
+	const images = /* @__PURE__ */ new Map();
+	const files = /* @__PURE__ */ new Map();
 	for (const line of content.split("\n")) {
 		if (line === "") continue;
 		let event;
@@ -125,9 +197,12 @@ function imageRefsInArtifact(content) {
 		} catch {
 			continue;
 		}
-		collectEventImageRefs(event, refs);
+		collectEventAttachmentRefs(event, images, files);
 	}
-	return refs;
+	return {
+		images,
+		files
+	};
 }
 /**
 * One safe zip path segment from an untrusted session id. Session ids are
@@ -150,30 +225,33 @@ function sessionLogZipFilename(sessionId) {
 	return `dsh-session-${safeSessionIdSegment(sessionId)}.zip`;
 }
 /**
-* Yield the export entries in zip order: the preloaded root artifact first,
-* then every subagent descendant in lineage order (each flushed when live,
-* read from the persistence backend right before it is yielded, and dropped
-* after the consumer moves on), then every distinct media object referenced by any of
-* the included logs (read and verified from the attachment store, one archive
-* entry per attachment id). The host holds at most one descendant's artifact
-* text and one media object at a time beyond the root.
+* Yield the export entries in zip order: the preloaded root log first, then
+* every subagent descendant in lineage order (each flushed when live, read
+* through a persistence read handle right before it is yielded, and dropped
+* after the consumer moves on), then every distinct attachment referenced by
+* the included logs. Images are read and verified as bounded stored objects;
+* generic files remain streamed through the ZIP writer. The host holds at most
+* one descendant log, one image, and one file chunk beyond the root.
 * @param deps - the mounted export services (the caller answered 500 before this runs).
-* @param root - the already-read root artifact (read by the caller so the
-* missing-session path can answer cleanly before streaming starts).
+* @param rootContent - the already-serialized root log (read by the caller so
+* the missing-session path can answer cleanly before streaming starts).
 * @param sessionId - the root session id.
 * @param includeDescendants - whether to include every subagent descendant.
 * @param signal - optional cancellation forwarded to lineage, persistence, and attachment reads.
 * @returns the export entries in zip order.
 */
-async function* sessionLogZipEntries(deps, root, sessionId, includeDescendants, signal) {
+async function* sessionLogZipEntries(deps, rootContent, sessionId, includeDescendants, signal) {
 	const media = /* @__PURE__ */ new Map();
-	const rememberMedia = (content) => {
-		for (const [id, ref] of imageRefsInArtifact(content)) media.set(id, ref);
+	const files = /* @__PURE__ */ new Map();
+	const rememberAttachments = (content) => {
+		const refs = attachmentRefsInArtifact(content);
+		for (const [id, ref] of refs.images) media.set(id, ref);
+		for (const [id, ref] of refs.files) files.set(id, ref);
 	};
-	rememberMedia(root.content);
+	rememberAttachments(rootContent);
 	yield {
-		path: root.filename,
-		content: root.content
+		path: SESSION_LOG_FILENAME,
+		content: rootContent
 	};
 	if (includeDescendants) {
 		const seen = new Set([sessionId]);
@@ -184,13 +262,13 @@ async function* sessionLogZipEntries(deps, root, sessionId, includeDescendants,
 				if (seen.has(id)) continue;
 				seen.add(id);
 				await flushLiveSessionLog(deps, id, signal);
-				const raw = await deps.sessionPersistence.readRaw(id, signal);
+				const content = await readSessionLogText(deps.sessionPersistence, id, signal);
 				signal?.throwIfAborted();
-				if (raw === void 0) throw new Error(`subagent "${id}" has no stored log artifact`);
-				rememberMedia(raw.content);
+				if (content === void 0) throw new Error(`subagent "${id}" has no stored log`);
+				rememberAttachments(content);
 				yield {
-					path: `subagents/${safeSessionIdSegment(id)}/${raw.filename}`,
-					content: raw.content
+					path: `subagents/${safeSessionIdSegment(id)}/${SESSION_LOG_FILENAME}`,
+					content
 				};
 				yield* collect(node.descendants);
 			}
@@ -208,8 +286,15 @@ async function* sessionLogZipEntries(deps, root, sessionId, includeDescendants,
 			data: stored.data
 		};
 	}
+	for (const ref of files.values()) {
+		signal?.throwIfAborted();
+		yield {
+			path: fileEntryPath(ref),
+			chunks: deps.attachments.readFileStream(ref, signal)
+		};
+	}
 }
-/** How many code units of artifact text one zip push carries (bounded encode memory). */
+/** How many code units of Session-log text one zip push carries (bounded encode memory). */
 const PUSH_CHUNK_CODE_UNITS = 65536;
 /** How many bytes of media one zip push carries (bounded memory; images are already size-capped). */
 const PUSH_CHUNK_BYTES = 65536;
@@ -262,12 +347,24 @@ async function pushBinaryChunks(deflate, data, controller, capacity, signal) {
 		await capacity.wait(controller, signal);
 	} while (offset < data.byteLength);
 }
+/** Push one streamed file entry without retaining its complete byte sequence. */
+async function pushStreamChunks(deflate, chunks, controller, capacity, signal) {
+	for await (const chunk of chunks) {
+		signal.throwIfAborted();
+		if (chunk.byteLength === 0) continue;
+		deflate.push(chunk, false);
+		await capacity.wait(controller, signal);
+	}
+	signal.throwIfAborted();
+	deflate.push(new Uint8Array(), true);
+	await capacity.wait(controller, signal);
+}
 /**
 * Push one artifact's text into a deflate stream in bounded chunks, never
 * splitting a surrogate pair across a chunk boundary (a lone high surrogate
 * re-encodes as U+FFFD and would silently corrupt the exported artifact).
 * @param deflate - the zip entry's deflate stream.
-* @param content - the artifact text verbatim.
+* @param content - the canonical Session-log text.
 * @param controller - response queue controller.
 * @param capacity - pull-driven response-capacity gate.
 * @param signal - cancellation; throws when aborted.
@@ -290,21 +387,21 @@ async function pushArtifactChunks(deflate, content, controller, capacity, signal
 	} while (!finalChunk);
 }
 /**
-* Stream one session-log ZIP as a WHATWG ReadableStream. The root artifact is
-* read and validated by the caller before this is called (missing root or
+* Stream one session-log ZIP as a WHATWG ReadableStream. The root log is read
+* and serialized by the caller before this is called (a missing root or
 * missing services answer cleanly before any byte is produced); each entry is
 * then encoded and deflated in bounded chunks as it is produced, so the
 * archive bytes arrive incrementally. A descendant that fails to read errors
 * the stream (fail-loud, never silent under-export).
 * @param deps - the mounted export services (the caller answered 500 before this runs).
-* @param root - the already-read root artifact (first zip entry).
+* @param rootContent - the already-serialized root log (first zip entry).
 * @param sessionId - the root session id.
 * @param includeDescendants - whether to include every subagent descendant.
 * @param compressionLevel - validated fflate DEFLATE level for every ZIP entry.
 * @param signal - request cancellation combined with response-consumer cancellation.
 * @returns the zip byte stream.
 */
-function streamSessionLogZip(deps, root, sessionId, includeDescendants, compressionLevel, signal) {
+function streamSessionLogZip(deps, rootContent, sessionId, includeDescendants, compressionLevel, signal) {
 	const consumerAbort = new AbortController();
 	const producerSignal = AbortSignal.any([signal, consumerAbort.signal]);
 	let zip;
@@ -330,11 +427,12 @@ function streamSessionLogZip(deps, root, sessionId, includeDescendants, compress
 			zip = archive;
 			(async () => {
 				try {
-					for await (const entry of sessionLogZipEntries(deps, root, sessionId, includeDescendants, producerSignal)) {
+					for await (const entry of sessionLogZipEntries(deps, rootContent, sessionId, includeDescendants, producerSignal)) {
 						const deflate = new ZipDeflate(entry.path, { level: compressionLevel });
 						archive.add(deflate);
 						if ("content" in entry) await pushArtifactChunks(deflate, entry.content, controller, capacity, producerSignal);
-						else await pushBinaryChunks(deflate, entry.data, controller, capacity, producerSignal);
+						else if ("data" in entry) await pushBinaryChunks(deflate, entry.data, controller, capacity, producerSignal);
+						else await pushStreamChunks(deflate, entry.chunks, controller, capacity, producerSignal);
 					}
 					archive.end();
 				} catch (error) {
@@ -386,6 +484,7 @@ function apply(ctx, config = {}) {
 	connectionOf(ctx).fetch.register({
 		path: SESSION_LOG_EXPORT_PATH,
 		methods: ["GET", "HEAD"],
+		requestBody: "buffered",
 		fetch: async (request) => {
 			const response = await sessionLogExportResponse(ctx, request, config.compressionLevel ?? 6);
 			if (request.method === "GET") return response;
@@ -409,27 +508,26 @@ async function sessionLogExportResponse(ctx, request, compressionLevel) {
 	const sessionId = brandString(sessionIdValue);
 	const deps = sessionLogExportDeps(ctx);
 	if (deps.sessionQuery === void 0 || deps.sessionPersistence === void 0 || deps.attachments === void 0) return new Response("session log export is unavailable: missing session-query, session-persistence, or attachments service", { status: 500 });
-	if (!deps.sessionPersistence.supportsRawArtifacts) return new Response("session log export is unavailable: the persistence backend does not expose per-session raw artifacts", { status: 501 });
 	const ready = {
 		sessionQuery: deps.sessionQuery,
 		sessionPersistence: deps.sessionPersistence,
 		attachments: deps.attachments,
 		sessions: deps.sessions
 	};
-	let root;
+	let rootContent;
 	try {
 		await flushLiveSessionLog(deps, sessionId, request.signal);
-		root = await deps.sessionPersistence.readRaw(sessionId, request.signal);
+		rootContent = await readSessionLogText(deps.sessionPersistence, sessionId, request.signal);
 		request.signal.throwIfAborted();
 	} catch {
 		request.signal.throwIfAborted();
-		return new Response("session log export failed to prepare the stored artifact", { status: 500 });
+		return new Response("session log export failed to read the stored log", { status: 500 });
 	}
-	if (root === void 0) return new Response("session not found", { status: 404 });
-	return new Response(streamSessionLogZip(ready, root, sessionId, descendantsValue === "true", compressionLevel, request.signal), { headers: {
+	if (rootContent === void 0) return new Response("session not found", { status: 404 });
+	return new Response(streamSessionLogZip(ready, rootContent, sessionId, descendantsValue === "true", compressionLevel, request.signal), { headers: {
 		"content-type": "application/zip",
 		"content-disposition": `attachment; filename="${sessionLogZipFilename(sessionId)}"`
 	} });
 }
 //#endregion
-export { Config, DEFAULT_SESSION_LOG_COMPRESSION_LEVEL, SESSION_LOG_EXPORT_PATH, apply, flushLiveSessionLog, inject, name, sessionLogExportDeps, sessionLogZipEntries, sessionLogZipFilename, streamSessionLogZip };
+export { Config, DEFAULT_SESSION_LOG_COMPRESSION_LEVEL, SESSION_LOG_EXPORT_PATH, SESSION_LOG_FILENAME, apply, flushLiveSessionLog, inject, name, readSessionLogText, serializeSessionLog, sessionLogExportDeps, sessionLogZipEntries, sessionLogZipFilename, streamSessionLogZip };

package/lib/types/archive.d.ts

@@ -1,16 +1,18 @@
 /**
  * Host-side session-log download: streams one ZIP archive whose files are the
- * sessions' stored artifact text verbatim plus every referenced media object.
- * The root artifact sits under its original base name (`session.jsonl`); each
- * subagent descendant under `subagents/<id>/<filename>`; each image referenced
- * by any included log under `media/<attachmentId>.<ext>` (content-addressed,
- * so one archive never duplicates a shared image). No manifest is written —
- * every file is byte-identical to the backend's durable artifact or attachment
- * store and self-describing through its own header line or media type. Before
- * each live session's artifact read, the SessionStore flush barrier makes the
- * current in-memory log durable; cold sessions need no barrier. Request abort
- * and response-consumer cancellation share one producer signal and terminate
- * the active compressor.
+ * sessions' logical session logs plus every referenced attachment. Each log
+ * is read through a persistence read handle and serialized here as canonical
+ * JSONL — one header line, then one line per validated event — so every
+ * backend (JSONL, SQLite, future) exports identically. The root log uses the
+ * current generation's canonical `session[.vN].jsonl` name; each subagent
+ * descendant uses `subagents/<id>/session[.vN].jsonl`; each image referenced by any included log
+ * under `media/<attachmentId>.<ext>` (content-addressed, so one archive never
+ * duplicates a shared image); each generic file sits under
+ * `files/<prefix>/<digest>/<name>` and streams from the attachment store. No
+ * manifest is written. Before each live session's log read, the SessionStore
+ * flush barrier makes the current in-memory log durable; cold sessions need no
+ * barrier. Request abort and response-consumer cancellation share one producer
+ * signal and terminate the active compressor.
  * Compression runs on the host with fflate's streaming Zip API, so the archive
  * bytes are produced incrementally and the host never holds the whole archive
  * in one buffer; production waits for consumer pull whenever the response queue
@@ -21,8 +23,8 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
 import type { SessionQueryEngine } from '@deepseek-ai/dsh-session-query';
-import type { SessionId, SessionStore } from '@deepseek-ai/dsh-session';
-import type { SessionPersistence, SessionRawArtifact } from '@deepseek-ai/dsh-session-persistence';
+import type { SessionEvent, SessionHeader, SessionId, SessionStore } from '@deepseek-ai/dsh-session';
+import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence';
 /** Valid fflate DEFLATE levels accepted by session-log export. */
 export type SessionLogCompressionLevel = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
 /** Balanced default used when Session export configuration omits a compression level. */
@@ -49,21 +51,45 @@ export interface SessionLogExportReady {
 export declare function sessionLogExportDeps(ctx: Context): SessionLogExportDeps;
 /**
  * Flush one currently live session through the store's authoritative durability
- * barrier immediately before its raw artifact is read. A cold or absent id has
+ * barrier immediately before its logical log is read. A cold or absent id has
  * no in-memory work to flush.
  * @param deps - export services, including the optional live-session store.
  * @param id - the session whose artifact is about to be read.
  * @param signal - optional cancellation observed around the flush barrier.
  */
 export declare function flushLiveSessionLog(deps: Pick<SessionLogExportDeps, 'sessions'>, id: SessionId, signal?: AbortSignal): Promise<void>;
-/** One exported file: a stored artifact text or one referenced media object. */
+/** One exported file: a serialized session log or one referenced attachment object. */
 export type SessionLogZipEntry = {
     readonly path: string;
     readonly content: string;
 } | {
     readonly path: string;
     readonly data: Uint8Array;
+} | {
+    readonly path: string;
+    readonly chunks: AsyncIterable<Uint8Array>;
 };
+/** The current generation's canonical base filename for every exported session log. */
+export declare const SESSION_LOG_FILENAME: string;
+/**
+ * Serialize one session's logical log as canonical JSONL text: the header
+ * line, then one line per event, with a trailing newline.
+ * @param header - the session's immutable header.
+ * @param events - the validated committed events in seq order.
+ * @returns the JSONL text.
+ */
+export declare function serializeSessionLog(header: SessionHeader, events: readonly SessionEvent[]): string;
+/**
+ * Read one session's complete logical log through a read handle and serialize
+ * it. The read observes the committed log only — persistence never returns a
+ * torn tail — and a handle read after a resolved flush observes at least the
+ * flushed prefix.
+ * @param persistence - the mounted persistence backend.
+ * @param id - the session to read.
+ * @param signal - optional cancellation forwarded to the open and read.
+ * @returns the serialized JSONL text, or `undefined` when the session does not exist.
+ */
+export declare function readSessionLogText(persistence: SessionPersistence, id: SessionId, signal?: AbortSignal): Promise<string | undefined>;
 /**
  * The export archive filename for one root session.
  * @param sessionId - the root session id (sanitized to one safe path segment).
@@ -71,36 +97,36 @@ export type SessionLogZipEntry = {
  */
 export declare function sessionLogZipFilename(sessionId: string): string;
 /**
- * Yield the export entries in zip order: the preloaded root artifact first,
- * then every subagent descendant in lineage order (each flushed when live,
- * read from the persistence backend right before it is yielded, and dropped
- * after the consumer moves on), then every distinct media object referenced by any of
- * the included logs (read and verified from the attachment store, one archive
- * entry per attachment id). The host holds at most one descendant's artifact
- * text and one media object at a time beyond the root.
+ * Yield the export entries in zip order: the preloaded root log first, then
+ * every subagent descendant in lineage order (each flushed when live, read
+ * through a persistence read handle right before it is yielded, and dropped
+ * after the consumer moves on), then every distinct attachment referenced by
+ * the included logs. Images are read and verified as bounded stored objects;
+ * generic files remain streamed through the ZIP writer. The host holds at most
+ * one descendant log, one image, and one file chunk beyond the root.
  * @param deps - the mounted export services (the caller answered 500 before this runs).
- * @param root - the already-read root artifact (read by the caller so the
- * missing-session path can answer cleanly before streaming starts).
+ * @param rootContent - the already-serialized root log (read by the caller so
+ * the missing-session path can answer cleanly before streaming starts).
  * @param sessionId - the root session id.
  * @param includeDescendants - whether to include every subagent descendant.
  * @param signal - optional cancellation forwarded to lineage, persistence, and attachment reads.
  * @returns the export entries in zip order.
  */
-export declare function sessionLogZipEntries(deps: SessionLogExportReady, root: SessionRawArtifact, sessionId: SessionId, includeDescendants: boolean, signal?: AbortSignal): AsyncGenerator<SessionLogZipEntry>;
+export declare function sessionLogZipEntries(deps: SessionLogExportReady, rootContent: string, sessionId: SessionId, includeDescendants: boolean, signal?: AbortSignal): AsyncGenerator<SessionLogZipEntry>;
 /**
- * Stream one session-log ZIP as a WHATWG ReadableStream. The root artifact is
- * read and validated by the caller before this is called (missing root or
+ * Stream one session-log ZIP as a WHATWG ReadableStream. The root log is read
+ * and serialized by the caller before this is called (a missing root or
  * missing services answer cleanly before any byte is produced); each entry is
  * then encoded and deflated in bounded chunks as it is produced, so the
  * archive bytes arrive incrementally. A descendant that fails to read errors
  * the stream (fail-loud, never silent under-export).
  * @param deps - the mounted export services (the caller answered 500 before this runs).
- * @param root - the already-read root artifact (first zip entry).
+ * @param rootContent - the already-serialized root log (first zip entry).
  * @param sessionId - the root session id.
  * @param includeDescendants - whether to include every subagent descendant.
  * @param compressionLevel - validated fflate DEFLATE level for every ZIP entry.
  * @param signal - request cancellation combined with response-consumer cancellation.
  * @returns the zip byte stream.
  */
-export declare function streamSessionLogZip(deps: SessionLogExportReady, root: SessionRawArtifact, sessionId: SessionId, includeDescendants: boolean, compressionLevel: SessionLogCompressionLevel, signal: AbortSignal): ReadableStream<Uint8Array>;
+export declare function streamSessionLogZip(deps: SessionLogExportReady, rootContent: string, sessionId: SessionId, includeDescendants: boolean, compressionLevel: SessionLogCompressionLevel, signal: AbortSignal): ReadableStream<Uint8Array>;
 //# sourceMappingURL=archive.d.ts.map

package/lib/types/index.d.ts

@@ -2,7 +2,7 @@
 import type { Context } from '@deepseek-ai/cordis';
 import Schema from '@deepseek-ai/schemastery';
 import { type SessionLogCompressionLevel } from './archive.ts';
-export { DEFAULT_SESSION_LOG_COMPRESSION_LEVEL, flushLiveSessionLog, sessionLogExportDeps, sessionLogZipEntries, sessionLogZipFilename, streamSessionLogZip, } from './archive.ts';
+export { DEFAULT_SESSION_LOG_COMPRESSION_LEVEL, flushLiveSessionLog, readSessionLogText, serializeSessionLog, SESSION_LOG_FILENAME, sessionLogExportDeps, sessionLogZipEntries, sessionLogZipFilename, streamSessionLogZip, } from './archive.ts';
 export type { SessionLogCompressionLevel, SessionLogExportDeps, SessionLogExportReady, SessionLogZipEntry, } from './archive.ts';
 export declare const name = "session-log-download";
 export declare const inject: string[];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-log-export",
   "description": "Web Session-log export command and shared download dialog",
-  "version": "0.1.2-alpha.5",
+  "version": "0.1.3-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -33,32 +33,35 @@
   "license": "MIT",
   "dependencies": {
     "fflate": "^0.8.2",
+    "@deepseek-ai/dsh-session-format": "^0.1.3-alpha.2",
     "@deepseek-ai/schemastery": "^3.18.2",
-    "@deepseek-ai/dsh-brand": "^0.1.2-alpha.5"
+    "@deepseek-ai/dsh-brand": "^0.1.3-alpha.2"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-session": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.3-alpha.2"
   },
   "devDependencies": {
     "@types/react": "~18.3.1",
     "react": "^18.2.0",
     "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": "^0.1.3-alpha.2",
     "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
-    "@deepseek-ai/dsh-agent": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-client-connection": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-client-store": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-attachment": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-client-ui-commands": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-client-ui-session": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-commands": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-session-query": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-session": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-client-locale": "^0.1.2-alpha.5"
+    "@deepseek-ai/dsh-client-connection": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-attachment": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-client-store": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-client-ui-commands": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-client-locale": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-client-ui-session": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-commands": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-session-query": "^0.1.3-alpha.2"
   },
   "dsh": {
     "client": {