@lingxi-ai-cn/dsh-session-export 0.1.0-rc.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+# `@lingxi-ai-cn/dsh-session-export`
+
+English | [中文](README.zh.md)
+
+Host-owned Session-log ZIP producer and native path writer. The `SessionLogExporter` service (`ctx.sessionLogExporter`) flushes each live Session before reading its persistence backend's raw artifact, streams the root artifact, optional descendants, and referenced images through bounded fflate compression, and never reconstructs stored logs from parsed events. `stream()` exposes the archive to a host transport; `writeToDirectory()` writes the same archive to an existing absolute directory and returns its exact final path.
+
+The native writer creates an owner-only random sibling, forwards cancellation through root preparation, lineage, persistence, attachment reads, compression, and file writes, syncs and closes the complete file, then publishes it with an exclusive hard link. Existing exports are never overwritten: the first collision uses `-2`, followed by increasing suffixes. A failure before publication removes the partial sibling and leaves no final archive. The destination filesystem must support same-directory hard links.
+
+Expected preparation failures use `SessionLogExportError`: `services-unavailable`, `raw-artifacts-unsupported`, `session-not-found`, and `prepare-failed`. Destination and output failures use `destination-invalid` and `write-failed`. The operator-facing messages do not expose backend preparation errors; the original error remains attached as `cause` for host diagnostics. Signal cancellation preserves the signal's reason instead of becoming an export failure.
+
+The archive is diagnostic material containing the stored Session artifacts verbatim. Provider credential stores and transient OAuth progress are outside Session persistence and are never included, but prompts and tool arguments already present in the durable log remain present; consumers must choose an operator-controlled destination and treat the result as sensitive.
+
+## Configuration
+
+| Key | Default | Behavior |
+|---|---:|---|
+| `compressionLevel` | `6` | Integer fflate DEFLATE level from `0` (store) through `9` (smallest archive). |
+
+## Model Experience
+
+None, as export reads durable artifacts and writes a host file without adding Session events or model-visible content.
+
+#### KV Cache effect
+
+None. Export does not assemble or send provider requests.
+
+## Known Limitations and Deferred Work
+
+- Persistence backends that do not expose per-Session raw artifacts cannot export; the shipped JSONL backend supports plaintext and zstd artifacts, while SQLite does not.
+- A tree export is a sequence of per-Session durability barriers and reads, not one atomic snapshot across the whole lineage; a live descendant may append after its artifact was read.
+- Native publication requires hard-link support in the selected directory. The service fails without publishing a partial final file when the filesystem rejects that operation.

package/README.zh.md

@@ -0,0 +1,31 @@
+# `@lingxi-ai-cn/dsh-session-export`
+
+[English](README.md) | 中文
+
+宿主侧拥有的 Session 日志 ZIP 生产器与原生路径写入器。`SessionLogExporter` 服务（`ctx.sessionLogExporter`）会在读取持久化后端的原始工件前 flush 每个实时 Session，通过有界 fflate 压缩流式输出根工件、可选后代和引用的图片，并且绝不从解析后的事件重建存储日志。`stream()` 向宿主传输层提供归档；`writeToDirectory()` 把同一归档写入一个既有的绝对目录，并返回精确的最终路径。
+
+原生写入器先创建一个仅所有者可读写的随机同级文件，把取消转发到根工件准备、血缘、持久化、附件读取、压缩和文件写入，随后同步并关闭完整文件，最后通过排他硬链接发布。既有导出永远不会被覆盖：第一次冲突使用 `-2`，随后递增后缀。发布前的失败会删除局部同级文件，不留下最终归档。目标文件系统必须支持同目录硬链接。
+
+预期的准备失败使用 `SessionLogExportError`：`services-unavailable`、`raw-artifacts-unsupported`、`session-not-found` 和 `prepare-failed`。目标与输出失败使用 `destination-invalid` 和 `write-failed`。面向操作者的消息不会泄露后端准备错误；原始错误保留为 `cause`，供宿主诊断。signal 取消会保留 signal 的 reason，而不会改写成导出失败。
+
+该归档是逐字包含所存 Session 工件的诊断材料。提供方凭据存储和 transient OAuth 进度位于 Session 持久化之外，绝不会包含在内；但已经进入持久日志的 prompt 与工具参数仍会保留，因此 Consumer 必须选择由操作者控制的目标位置，并把结果视为敏感材料。
+
+## 配置
+
+| 键 | 默认值 | 行为 |
+|---|---:|---|
+| `compressionLevel` | `6` | 从 `0`（仅存储）到 `9`（最小归档）的整数 fflate DEFLATE 级别。 |
+
+## 模型体验
+
+无，因为导出只读取持久工件并写入宿主文件，不增加 Session 事件或模型可见内容。
+
+#### KV Cache 影响
+
+无。导出不会组装或发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- 不提供逐 Session 原始工件的持久化后端无法导出；随附的 JSONL 后端支持明文与 zstd 工件，SQLite 尚不支持。
+- 树导出是一系列逐 Session 的持久性屏障与读取，并非覆盖整条血缘的一次原子快照；实时后代可能在自身工件被读取后继续追加。
+- 原生发布要求所选目录支持硬链接。文件系统拒绝该操作时，服务会失败且不会发布局部最终文件。

package/lib/index.js

@@ -0,0 +1,536 @@
+import { randomUUID } from "node:crypto";
+import { link, open, rm, stat } from "node:fs/promises";
+import { basename, extname, isAbsolute, join } from "node:path";
+import { Service } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import { Zip, ZipDeflate } from "fflate";
+//#region lib/types/zip.js
+/**
+* Host-side Session ZIP producer: streams one 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.
+* 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
+* reaches its byte high-water mark, so a slow consumer bounds accumulation to
+* the fixed 64 KiB response queue plus one synchronous fflate push.
+* @module @lingxi-ai-cn/dsh-session-export/zip
+*/
+/** Balanced default used when a deployment omits compression config. */
+const DEFAULT_SESSION_LOG_COMPRESSION_LEVEL = 6;
+/**
+* Resolve the persistence, session-query, and attachment services a log export needs.
+* @param ctx - the composed host context.
+* @returns the export services (absent when the deployment does not mount them).
+*/
+function sessionLogExportDeps(ctx) {
+	return {
+		sessionQuery: ctx.get("sessionQuery"),
+		sessionPersistence: ctx.get("sessionPersistence"),
+		attachments: ctx.get("attachments"),
+		sessions: ctx.get("sessions")
+	};
+}
+/**
+* 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
+* 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.
+*/
+async function flushLiveSessionLog(deps, id, signal) {
+	signal?.throwIfAborted();
+	const sessions = deps.sessions;
+	if (sessions === void 0) return;
+	const session = sessions.get(id);
+	if (session === void 0) return;
+	await sessions.flush(session);
+	signal?.throwIfAborted();
+}
+/** Zip extension for each accepted raster media type. */
+const MEDIA_TYPE_EXTENSIONS = {
+	"image/png": "png",
+	"image/jpeg": "jpg",
+	"image/webp": "webp",
+	"image/gif": "gif"
+};
+/**
+* The zip path for one media object: content-addressed by the opaque
+* attachment id so shared images land once and the id in the log maps back to
+* the archive entry without a manifest.
+* @param ref - the durable reference from a session log.
+* @returns the archive path.
+*/
+function mediaEntryPath(ref) {
+	return `media/${String(ref.attachmentId)}.${MEDIA_TYPE_EXTENSIONS[ref.mediaType]}`;
+}
+/**
+* Collect every image 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).
+*/
+function collectImageRefs(content, refs) {
+	if (!Array.isArray(content)) return;
+	const pending = [];
+	for (const item of content) pending.push(item);
+	while (pending.length > 0) {
+		const value = pending.pop();
+		if (typeof value !== "object" || value === null || Array.isArray(value)) continue;
+		const block = value;
+		if (block.type === "image" && typeof block.attachment === "object" && block.attachment !== null) {
+			const ref = block.attachment;
+			refs.set(String(ref.attachmentId), 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
+* carriers the live attachment route scans (direct content, message content,
+* inserted messages, and completed assistant chunk blocks).
+* @param event - one parsed JSONL event object.
+* @param refs - the dedupe map being filled (keyed by attachment id).
+*/
+function collectEventImageRefs(event, refs) {
+	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);
+}
+/**
+* Collect the distinct media references one stored artifact text names.
+* Lines that fail to parse cannot reference media 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.
+*/
+function imageRefsInArtifact(content) {
+	const refs = /* @__PURE__ */ new Map();
+	for (const line of content.split("\n")) {
+		if (line === "") continue;
+		let event;
+		try {
+			event = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		collectEventImageRefs(event, refs);
+	}
+	return refs;
+}
+/**
+* One safe zip path segment from an untrusted session id. Session ids are
+* host-controlled, but the brand allows any non-empty string, so `../`, dot
+* segments, and separator characters are neutralized before they can shape
+* archive entries. Distinct ids may collapse onto one segment (id collision
+* is impossible for the host-minted UUIDs, so no uniqueness suffix is kept).
+* @param id - the raw session id.
+* @returns a filesystem-safe single path segment.
+*/
+function safeSessionIdSegment(id) {
+	return id.replace(/[^A-Za-z0-9_-]/g, "_");
+}
+/**
+* The export archive filename for one root session.
+* @param sessionId - the root session id (sanitized to one safe path segment).
+* @returns the attachment filename for the session's export archive.
+*/
+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.
+* @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 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) {
+	const media = /* @__PURE__ */ new Map();
+	const rememberMedia = (content) => {
+		for (const [id, ref] of imageRefsInArtifact(content)) media.set(id, ref);
+	};
+	rememberMedia(root.content);
+	yield {
+		path: root.filename,
+		content: root.content
+	};
+	if (includeDescendants) {
+		const seen = /* @__PURE__ */ new Set([sessionId]);
+		const collect = async function* (nodes) {
+			for (const node of nodes) {
+				signal?.throwIfAborted();
+				const id = node.session.header.id;
+				if (seen.has(id)) continue;
+				seen.add(id);
+				await flushLiveSessionLog(deps, id, signal);
+				const raw = await deps.sessionPersistence.readRaw(id, signal);
+				signal?.throwIfAborted();
+				if (raw === void 0) throw new Error(`subagent "${id}" has no stored log artifact`);
+				rememberMedia(raw.content);
+				yield {
+					path: `subagents/${safeSessionIdSegment(id)}/${raw.filename}`,
+					content: raw.content
+				};
+				yield* collect(node.descendants);
+			}
+		};
+		const lineage = await deps.sessionQuery.traceSession(sessionId, signal);
+		signal?.throwIfAborted();
+		yield* collect(lineage.descendants);
+	}
+	for (const ref of media.values()) {
+		signal?.throwIfAborted();
+		const stored = await deps.attachments.readImage(ref, signal);
+		signal?.throwIfAborted();
+		yield {
+			path: mediaEntryPath(ref),
+			data: stored.data
+		};
+	}
+}
+/** How many code units of artifact 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;
+/** Byte capacity retained by the response stream before ZIP production waits for pull. */
+const RESPONSE_HIGH_WATER_MARK_BYTES = 65536;
+/** One producer waiter released only when ReadableStream pull restores capacity. */
+var ResponseCapacityGate = class {
+	releasePending;
+	/**
+	* Wait until the response queue has positive byte capacity or cancellation wins.
+	* @param controller - response controller whose desired size owns capacity.
+	* @param signal - combined request/consumer cancellation.
+	*/
+	async wait(controller, signal) {
+		signal.throwIfAborted();
+		if (controller.desiredSize === null || controller.desiredSize > 0) return;
+		await new Promise((resolve) => {
+			const release = () => {
+				this.releasePending = void 0;
+				signal.removeEventListener("abort", release);
+				resolve();
+			};
+			this.releasePending = release;
+			signal.addEventListener("abort", release, { once: true });
+		});
+		signal.throwIfAborted();
+	}
+	/** Release the current producer waiter after a consumer pull. */
+	pulled() {
+		this.releasePending?.();
+	}
+};
+/**
+* Push one media object's bytes into a deflate stream in bounded chunks,
+* waiting for consumer capacity between chunks like the artifact path does.
+* @param deflate - the zip entry's deflate stream.
+* @param data - the stored image bytes.
+* @param controller - response queue controller.
+* @param capacity - pull-driven response-capacity gate.
+* @param signal - cancellation; throws when aborted.
+*/
+async function pushBinaryChunks(deflate, data, controller, capacity, signal) {
+	let offset = 0;
+	do {
+		signal.throwIfAborted();
+		const end = Math.min(offset + PUSH_CHUNK_BYTES, data.byteLength);
+		const finalChunk = end >= data.byteLength;
+		deflate.push(data.subarray(offset, end), finalChunk);
+		offset = end;
+		await capacity.wait(controller, signal);
+	} while (offset < data.byteLength);
+}
+/**
+* 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 controller - response queue controller.
+* @param capacity - pull-driven response-capacity gate.
+* @param signal - cancellation; throws when aborted.
+*/
+async function pushArtifactChunks(deflate, content, controller, capacity, signal) {
+	const encoder = new TextEncoder();
+	let offset = 0;
+	let finalChunk;
+	do {
+		signal.throwIfAborted();
+		let end = Math.min(offset + PUSH_CHUNK_CODE_UNITS, content.length);
+		if (end < content.length && end - offset > 1) {
+			const last = content.charCodeAt(end - 1);
+			if (last >= 55296 && last <= 56319) end -= 1;
+		}
+		finalChunk = end >= content.length;
+		deflate.push(encoder.encode(content.slice(offset, end)), finalChunk);
+		offset = end;
+		await capacity.wait(controller, 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
+* 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 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) {
+	const consumerAbort = new AbortController();
+	const producerSignal = AbortSignal.any([signal, consumerAbort.signal]);
+	let zip;
+	let zipTerminated = false;
+	const capacity = new ResponseCapacityGate();
+	const terminateZip = () => {
+		if (zip === void 0 || zipTerminated) return;
+		zipTerminated = true;
+		zip.terminate();
+	};
+	return new ReadableStream({
+		start(controller) {
+			const archive = new Zip((error, data, final) => {
+				/* v8 ignore next 3 -- fflate reports only internal zip failures, unreachable for valid inputs */
+				if (error) {
+					controller.error(error);
+					return;
+				}
+				/* v8 ignore next -- fflate may emit empty chunks; not controllable from tests */
+				if (data.byteLength > 0) controller.enqueue(data);
+				if (final) controller.close();
+			});
+			zip = archive;
+			(async () => {
+				try {
+					for await (const entry of sessionLogZipEntries(deps, root, 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);
+					}
+					archive.end();
+				} catch (error) {
+					/* v8 ignore next -- typed backends reject with Error, and DOMException is one in Node */
+					terminateZip();
+					controller.error(error instanceof Error ? error : new Error(String(error)));
+				}
+			})();
+		},
+		pull() {
+			capacity.pulled();
+		},
+		cancel(reason) {
+			consumerAbort.abort(reason instanceof Error ? reason : /* @__PURE__ */ new Error("session log export stream cancelled"));
+			terminateZip();
+		}
+	}, {
+		highWaterMark: RESPONSE_HIGH_WATER_MARK_BYTES,
+		size: (chunk) => chunk.byteLength
+	});
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Host session-log export service: prepares the canonical stored-artifact ZIP,
+* exposes it as a bounded byte stream, and publishes complete archives into a
+* host directory without exposing a partial final file.
+* @module @lingxi-ai-cn/dsh-session-export
+*/
+/** Typed session-log export failure with a consumer-safe message. */
+var SessionLogExportError = class extends Error {
+	code;
+	/**
+	* @param code - stable failure category.
+	* @param message - safe operator-facing description.
+	* @param options - optional private cause retained for host diagnostics.
+	*/
+	constructor(code, message, options) {
+		super(message, options);
+		this.code = code;
+		this.name = "SessionLogExportError";
+	}
+};
+/**
+* Flush and read the root artifact before any ZIP byte is produced. Expected
+* capability and persistence failures use {@link SessionLogExportError}; an
+* aborted signal preserves its original reason.
+* @param ctx - composed host context.
+* @param sessionId - root Session identity.
+* @param signal - operation cancellation.
+* @returns the mounted services and root artifact ready for streaming.
+*/
+async function prepareSessionLogExport(ctx, sessionId, signal) {
+	signal.throwIfAborted();
+	const deps = sessionLogExportDeps(ctx);
+	if (deps.sessionQuery === void 0 || deps.sessionPersistence === void 0 || deps.attachments === void 0) throw new SessionLogExportError("services-unavailable", "session log export is unavailable: missing session-query, session-persistence, or attachments service");
+	if (!deps.sessionPersistence.supportsRawArtifacts) throw new SessionLogExportError("raw-artifacts-unsupported", "session log export is unavailable: the persistence backend does not expose per-session raw artifacts");
+	const ready = {
+		sessionQuery: deps.sessionQuery,
+		sessionPersistence: deps.sessionPersistence,
+		attachments: deps.attachments,
+		sessions: deps.sessions
+	};
+	let root;
+	try {
+		await flushLiveSessionLog(deps, sessionId, signal);
+		root = await deps.sessionPersistence.readRaw(sessionId, signal);
+		signal.throwIfAborted();
+	} catch (error) {
+		signal.throwIfAborted();
+		throw new SessionLogExportError("prepare-failed", "session log export failed to prepare the stored artifact", { cause: error });
+	}
+	if (root === void 0) throw new SessionLogExportError("session-not-found", "session not found");
+	return {
+		ready,
+		root
+	};
+}
+/** Write a complete chunk even when the host returns a short write. */
+async function writeChunk(file, chunk, signal) {
+	let offset = 0;
+	while (offset < chunk.byteLength) {
+		signal.throwIfAborted();
+		const { bytesWritten } = await file.write(chunk, offset, chunk.byteLength - offset);
+		if (bytesWritten === 0) throw new Error("session log export made no progress writing the archive");
+		offset += bytesWritten;
+	}
+}
+/** Candidate filename that retains the extension while avoiding an existing export. */
+function collisionFilename(filename, collision) {
+	if (collision === 0) return filename;
+	const extension = extname(filename);
+	return `${basename(filename, extension)}-${collision + 1}${extension}`;
+}
+/** Publish a completed private temp inode under the first available final name. */
+async function publishExclusive(tempPath, directory, filename, signal) {
+	for (let collision = 0; collision < 1e4; collision += 1) {
+		signal.throwIfAborted();
+		const candidate = collisionFilename(filename, collision);
+		const target = join(directory, candidate);
+		try {
+			await link(tempPath, target);
+			try {
+				await rm(tempPath);
+			} catch {}
+			return {
+				path: target,
+				filename: candidate
+			};
+		} catch (error) {
+			if (error.code === "EEXIST") continue;
+			throw error;
+		}
+	}
+	throw new Error(`session log export exhausted collision suffixes for ${filename}`);
+}
+/** Host service shared by terminal and programmatic Session export consumers. */
+var SessionLogExporter = class extends Service {
+	static inject = [
+		"attachments",
+		"sessionPersistence",
+		"sessionQuery",
+		"sessions"
+	];
+	static Config = z.object({ compressionLevel: z.number().step(1).min(0).max(9).default(6) });
+	compressionLevel;
+	constructor(ctx, config) {
+		super(ctx, "sessionLogExporter");
+		this.compressionLevel = config.compressionLevel ?? 6;
+	}
+	/**
+	* Prepare and expose one bounded ZIP byte stream.
+	* @param request - root identity and descendant policy.
+	* @param signal - producer lifetime; consumer cancellation is combined with it.
+	* @returns suggested filename and archive stream after root preflight succeeds.
+	*/
+	async stream(request, signal) {
+		const prepared = await prepareSessionLogExport(this.ctx, request.sessionId, signal);
+		return {
+			filename: sessionLogZipFilename(request.sessionId),
+			stream: streamSessionLogZip(prepared.ready, prepared.root, request.sessionId, request.includeDescendants, this.compressionLevel, signal)
+		};
+	}
+	/**
+	* Stream one archive to a private sibling file and publish it atomically under
+	* the first available safe filename. Existing exports are never overwritten.
+	* The destination must be an existing absolute directory. Cancellation or a
+	* producer/write failure removes the partial file and publishes nothing.
+	* @param request - root identity and descendant policy.
+	* @param directory - existing absolute host directory chosen by the operator.
+	* @param signal - complete preparation, streaming, and publication lifetime.
+	* @returns the exact published path and filename.
+	*/
+	async writeToDirectory(request, directory, signal) {
+		signal.throwIfAborted();
+		if (!isAbsolute(directory)) throw new SessionLogExportError("destination-invalid", "session log export destination must be an absolute directory");
+		try {
+			if (!(await stat(directory)).isDirectory()) throw new Error("destination is not a directory");
+		} catch (error) {
+			throw new SessionLogExportError("destination-invalid", `session log export destination is not an accessible directory: ${directory}`, { cause: error });
+		}
+		const prepared = await this.stream(request, signal);
+		const tempPath = join(directory, `.${prepared.filename}.${randomUUID()}.tmp`);
+		let file;
+		const reader = prepared.stream.getReader();
+		try {
+			file = await open(tempPath, "wx", 384);
+			for (;;) {
+				signal.throwIfAborted();
+				const chunk = await reader.read();
+				if (chunk.done) break;
+				await writeChunk(file, chunk.value, signal);
+			}
+			signal.throwIfAborted();
+			await file.sync();
+			await file.close();
+			file = void 0;
+			return await publishExclusive(tempPath, directory, prepared.filename, signal);
+		} catch (error) {
+			try {
+				await reader.cancel(error);
+			} catch {}
+			try {
+				await file?.close();
+			} catch {}
+			await rm(tempPath, { force: true });
+			signal.throwIfAborted();
+			if (error instanceof SessionLogExportError) throw error;
+			throw new SessionLogExportError("write-failed", "session log export failed while writing the archive", { cause: error });
+		} finally {
+			reader.releaseLock();
+		}
+	}
+};
+//#endregion
+export { DEFAULT_SESSION_LOG_COMPRESSION_LEVEL, SessionLogExportError, SessionLogExporter as default, flushLiveSessionLog, prepareSessionLogExport, sessionLogExportDeps, sessionLogZipEntries, sessionLogZipFilename, streamSessionLogZip };

package/lib/invariant.js

@@ -0,0 +1,20 @@
+//#region lib/types/invariant.js
+/** Package-owned invariant companion for host Session export. @module @lingxi-ai-cn/dsh-session-export/invariant */
+const PACKAGE_NAME = "@lingxi-ai-cn/dsh-session-export";
+/** Cordis companion plugin name. */
+const name = "host-session-export-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: export observes owning persistence, lineage, attachment,
+* and Session flush APIs and emits no durable or live events of its own.
+*/
+const install = () => {};
+/**
+* Register the package invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Host session-log export service: prepares the canonical stored-artifact ZIP,
+ * exposes it as a bounded byte stream, and publishes complete archives into a
+ * host directory without exposing a partial final file.
+ * @module @lingxi-ai-cn/dsh-session-export
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { SessionRawArtifact } from '@deepseek-ai/dsh-session-persistence';
+import { type SessionLogCompressionLevel, type SessionLogExportReady } from './zip.ts';
+export { DEFAULT_SESSION_LOG_COMPRESSION_LEVEL, flushLiveSessionLog, sessionLogExportDeps, sessionLogZipEntries, sessionLogZipFilename, streamSessionLogZip, } from './zip.ts';
+export type { SessionLogCompressionLevel, SessionLogExportDeps, SessionLogExportReady, SessionLogZipEntry, } from './zip.ts';
+/** Stable failure categories shared by the native writer and host transports. */
+export type SessionLogExportErrorCode = 'services-unavailable' | 'raw-artifacts-unsupported' | 'session-not-found' | 'prepare-failed' | 'destination-invalid' | 'write-failed';
+/** Typed session-log export failure with a consumer-safe message. */
+export declare class SessionLogExportError extends Error {
+    readonly code: SessionLogExportErrorCode;
+    /**
+     * @param code - stable failure category.
+     * @param message - safe operator-facing description.
+     * @param options - optional private cause retained for host diagnostics.
+     */
+    constructor(code: SessionLogExportErrorCode, message: string, options?: ErrorOptions);
+}
+/** Prepared root artifact and mounted services for one export operation. */
+export interface PreparedSessionLogExport {
+    /** Mounted services used while descendant and attachment entries stream. */
+    readonly ready: SessionLogExportReady;
+    /** Root artifact already flushed and read for the first ZIP entry. */
+    readonly root: SessionRawArtifact;
+}
+/** One export request independent of its transport or destination. */
+export interface SessionLogExportRequest {
+    /** Root Session whose stored artifact is exported. */
+    readonly sessionId: SessionId;
+    /** Whether all durable descendant artifacts are included. */
+    readonly includeDescendants: boolean;
+}
+/** Prepared streaming result for a transport consumer. */
+export interface SessionLogExportStream {
+    /** Safe suggested archive filename. */
+    readonly filename: string;
+    /** Bounded ZIP byte stream; cancellation aborts the producer. */
+    readonly stream: ReadableStream<Uint8Array>;
+}
+/** Completed native export result. */
+export interface SessionLogExportFile {
+    /** Absolute path atomically published after the ZIP completed. */
+    readonly path: string;
+    /** Published base filename, including a collision suffix when required. */
+    readonly filename: string;
+}
+/** Host session-log exporter configuration. */
+export interface Config {
+    /**
+     * DEFLATE level for ZIP entries. Zero stores, one favors latency, and nine
+     * favors archive size.
+     * @default 6
+     */
+    readonly compressionLevel?: SessionLogCompressionLevel;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Host-owned Session ZIP stream and native file writer. */
+        sessionLogExporter: SessionLogExporter;
+    }
+}
+/**
+ * Flush and read the root artifact before any ZIP byte is produced. Expected
+ * capability and persistence failures use {@link SessionLogExportError}; an
+ * aborted signal preserves its original reason.
+ * @param ctx - composed host context.
+ * @param sessionId - root Session identity.
+ * @param signal - operation cancellation.
+ * @returns the mounted services and root artifact ready for streaming.
+ */
+export declare function prepareSessionLogExport(ctx: Context, sessionId: SessionId, signal: AbortSignal): Promise<PreparedSessionLogExport>;
+/** Host service shared by terminal and programmatic Session export consumers. */
+export default class SessionLogExporter extends Service {
+    static inject: string[];
+    static Config: z<Config>;
+    private readonly compressionLevel;
+    constructor(ctx: Context, config: Config);
+    /**
+     * Prepare and expose one bounded ZIP byte stream.
+     * @param request - root identity and descendant policy.
+     * @param signal - producer lifetime; consumer cancellation is combined with it.
+     * @returns suggested filename and archive stream after root preflight succeeds.
+     */
+    stream(request: SessionLogExportRequest, signal: AbortSignal): Promise<SessionLogExportStream>;
+    /**
+     * Stream one archive to a private sibling file and publish it atomically under
+     * the first available safe filename. Existing exports are never overwritten.
+     * The destination must be an existing absolute directory. Cancellation or a
+     * producer/write failure removes the partial file and publishes nothing.
+     * @param request - root identity and descendant policy.
+     * @param directory - existing absolute host directory chosen by the operator.
+     * @param signal - complete preparation, streaming, and publication lifetime.
+     * @returns the exact published path and filename.
+     */
+    writeToDirectory(request: SessionLogExportRequest, directory: string, signal: AbortSignal): Promise<SessionLogExportFile>;
+}
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,13 @@
+/** Package-owned invariant companion for host Session export. @module @lingxi-ai-cn/dsh-session-export/invariant */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "host-session-export-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register the package invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/zip.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Host-side Session ZIP producer: streams one 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.
+ * 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
+ * reaches its byte high-water mark, so a slow consumer bounds accumulation to
+ * the fixed 64 KiB response queue plus one synchronous fflate push.
+ * @module @lingxi-ai-cn/dsh-session-export/zip
+ */
+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';
+/** 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 a deployment omits compression config. */
+export declare const DEFAULT_SESSION_LOG_COMPRESSION_LEVEL: SessionLogCompressionLevel;
+/** The services a session-log export needs (the live-session store is optional). */
+export interface SessionLogExportDeps {
+    readonly sessionQuery: SessionQueryEngine | undefined;
+    readonly sessionPersistence: SessionPersistence | undefined;
+    readonly attachments: AttachmentStore | undefined;
+    readonly sessions: SessionStore | undefined;
+}
+/** The export services narrowed to the mounted ones streaming actually reads. */
+export interface SessionLogExportReady {
+    readonly sessionQuery: SessionQueryEngine;
+    readonly sessionPersistence: SessionPersistence;
+    readonly attachments: AttachmentStore;
+    readonly sessions: SessionStore | undefined;
+}
+/**
+ * Resolve the persistence, session-query, and attachment services a log export needs.
+ * @param ctx - the composed host context.
+ * @returns the export services (absent when the deployment does not mount them).
+ */
+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
+ * 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. */
+export type SessionLogZipEntry = {
+    readonly path: string;
+    readonly content: string;
+} | {
+    readonly path: string;
+    readonly data: Uint8Array;
+};
+/**
+ * The export archive filename for one root session.
+ * @param sessionId - the root session id (sanitized to one safe path segment).
+ * @returns the attachment filename for the session's export archive.
+ */
+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.
+ * @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 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>;
+/**
+ * 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
+ * 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 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>;
+//# sourceMappingURL=zip.d.ts.map

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@lingxi-ai-cn/dsh-session-export",
+  "description": "Host-owned streaming Session ZIP producer and atomic path writer",
+  "version": "0.1.0-rc.8",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lingxi-AI-cn/dsh-tui-plugin.git",
+    "directory": "packages/host/session-export"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "fflate": "^0.8.2"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-attachment": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-invariants": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-session": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-session-persistence": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-session-query": "0.1.0-rc.8",
+    "@deepseek-ai/schemastery": "3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-attachment": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-invariants": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-session": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-session-persistence": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-session-query": "0.1.0-rc.8",
+    "@deepseek-ai/schemastery": "3.18.1"
+  }
+}