@xopcai/xopc 0.0.230 → 0.0.232

package/dist/src/share/session-share-service.js

@@ -0,0 +1,325 @@
+import { resolveStateDir } from "../config/paths-state.js";
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+import { init_paths } from "../config/paths.js";
+import { resolveMediaReference } from "../media/media-reference.js";
+import { projectSessionShare } from "./session-share-projector.js";
+import { issueShareAssetTicket, verifyShareAssetTicket } from "./share-asset-ticket.js";
+import { basename, join } from "node:path";
+import { createReadStream } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { copyFile, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+//#region src/share/session-share-service.ts
+init_paths();
+init_logger();
+const log = createLogger("SessionShareService");
+const MANIFEST_SCHEMA_VERSION = 1;
+const MAX_SHARE_MESSAGES = 1e4;
+const MAX_MANIFEST_BYTES = 10 * 1024 * 1024;
+const MAX_ATTACHMENT_COUNT = 20;
+const MAX_ATTACHMENT_BYTES = 32 * 1024 * 1024;
+const MAX_TOTAL_ATTACHMENT_BYTES = 100 * 1024 * 1024;
+const ASSET_TICKET_TTL_MS = 10 * 6e4;
+var SessionShareSnapshotConflictError = class extends Error {
+	constructor() {
+		super("Session changed after the share preview was reviewed");
+		this.name = "SessionShareSnapshotConflictError";
+	}
+};
+var SessionShareService = class {
+	constructor(store, source) {
+		this.store = store;
+		this.source = source;
+	}
+	async preview(sessionKey) {
+		const source = await this.loadSource(sessionKey);
+		const projection = projectSessionShare(source.snapshot.entries);
+		this.validateMessages(projection.messages);
+		return {
+			sessionId: source.snapshot.sessionId,
+			cutoffSeq: source.snapshot.lastSeq,
+			metadataUpdatedAt: source.metadata.updatedAt,
+			title: source.metadata.name?.trim() || "Shared conversation",
+			snapshotAt: (/* @__PURE__ */ new Date()).toISOString(),
+			messageCount: projection.messages.length,
+			messages: projection.messages,
+			toolActivities: projection.toolActivities,
+			attachmentCandidates: projection.attachmentCandidates
+		};
+	}
+	async create(sessionKey, input) {
+		const source = await this.loadExpectedSource(sessionKey, input);
+		const id = randomUUID();
+		const projection = projectSessionShare(source.snapshot.entries);
+		const includeToolActivities = input.includeToolActivities === true;
+		const manifestBase = this.buildManifestBase(id, source, projection, {
+			includeToolActivities,
+			selectedAttachmentIds: input.attachmentIds ?? []
+		});
+		const built = await this.createArtifact(id, manifestBase, projection, input.attachmentIds ?? []);
+		try {
+			return this.store.createSessionShare({
+				id,
+				sourceSessionId: built.manifest.source.sessionId,
+				cutoffSeq: built.manifest.source.cutoffSeq,
+				artifactRelativePath: this.artifactRelativePath(id),
+				artifactSize: built.totalSize,
+				messageCount: built.manifest.messages.length,
+				attachmentCount: built.manifest.attachments.length,
+				includeToolActivities,
+				fileName: built.manifest.title,
+				ttlMs: input.ttlMs,
+				maxViews: input.maxViews,
+				description: input.description,
+				gatewayTokenHash: input.gatewayTokenHash
+			});
+		} catch (error) {
+			await this.removeArtifact(id);
+			throw error;
+		}
+	}
+	async refresh(sessionKey, shareId, input) {
+		const record = this.store.getById(shareId);
+		if (!record || record.kind !== "session") throw new Error("Session share not found");
+		const source = await this.loadExpectedSource(sessionKey, input);
+		if (source.snapshot.sessionId !== record.sourceSessionId) throw new Error("Session share belongs to a previous session");
+		const previous = await this.readManifest(record);
+		const includeToolActivities = input.includeToolActivities ?? record.includeToolActivities;
+		const attachmentIds = input.attachmentIds ?? previous.attachments.map((attachment) => attachment.id);
+		const projection = projectSessionShare(source.snapshot.entries);
+		const manifestBase = this.buildManifestBase(shareId, source, projection, {
+			includeToolActivities,
+			selectedAttachmentIds: attachmentIds
+		});
+		const finalDir = this.artifactDir(shareId);
+		const stagedDir = `${finalDir}.refresh-${randomUUID()}`;
+		const backupDir = `${finalDir}.backup-${randomUUID()}`;
+		const built = await this.writeArtifact(stagedDir, manifestBase, projection, attachmentIds);
+		let movedOld = false;
+		try {
+			await rename(finalDir, backupDir);
+			movedOld = true;
+			await rename(stagedDir, finalDir);
+			const updated = this.store.updateSessionSnapshot(shareId, {
+				cutoffSeq: built.manifest.source.cutoffSeq,
+				artifactSize: built.totalSize,
+				messageCount: built.manifest.messages.length,
+				attachmentCount: built.manifest.attachments.length,
+				includeToolActivities,
+				fileName: built.manifest.title
+			});
+			if (!updated) throw new Error("Session share not found");
+			await rm(backupDir, {
+				recursive: true,
+				force: true
+			}).catch((err) => {
+				log.warn({
+					err,
+					shareId
+				}, "Failed to remove previous Session share artifact");
+			});
+			return updated;
+		} catch (error) {
+			await rm(stagedDir, {
+				recursive: true,
+				force: true
+			});
+			if (movedOld) {
+				await rm(finalDir, {
+					recursive: true,
+					force: true
+				});
+				await rename(backupDir, finalDir).catch(() => void 0);
+			}
+			throw error;
+		}
+	}
+	list(sessionId) {
+		return this.store.getSessionShares(sessionId);
+	}
+	async readManifest(record) {
+		const path = join(resolveStateDir(), record.artifactRelativePath, "manifest.json");
+		const file = await stat(path);
+		if (!file.isFile() || file.size > MAX_MANIFEST_BYTES) throw new Error("Invalid Session share artifact");
+		const manifest = JSON.parse(await readFile(path, "utf8"));
+		if (manifest.schemaVersion !== MANIFEST_SCHEMA_VERSION || manifest.shareId !== record.id || typeof manifest.title !== "string" || typeof manifest.snapshotAt !== "string" || !manifest.source || manifest.source.sessionId !== record.sourceSessionId || manifest.source.cutoffSeq !== record.cutoffSeq || !Array.isArray(manifest.messages) || !manifest.messages.every(isSessionShareMessage) || !Array.isArray(manifest.toolActivities) || !manifest.toolActivities.every(isSessionShareToolActivity) || !Array.isArray(manifest.attachments) || !manifest.attachments.every(isSessionShareAttachment)) throw new Error("Invalid Session share artifact");
+		this.validateMessages(manifest.messages);
+		this.validateManifestRelations(record, manifest);
+		return manifest;
+	}
+	issueAssetTicket(record) {
+		return issueShareAssetTicket(record, ASSET_TICKET_TTL_MS);
+	}
+	verifyAssetTicket(record, ticket) {
+		return verifyShareAssetTicket(record, ticket);
+	}
+	async resolveAsset(record, attachmentId) {
+		const attachment = (await this.readManifest(record)).attachments.find((item) => item.id === attachmentId);
+		if (!attachment || attachment.artifactFileName !== attachment.id) return null;
+		const path = join(resolveStateDir(), record.artifactRelativePath, "assets", attachment.id);
+		if (await checksumFile(path).catch(() => "") !== attachment.checksum) return null;
+		return {
+			path,
+			attachment
+		};
+	}
+	async removeArtifact(shareId) {
+		await rm(this.artifactDir(shareId), {
+			recursive: true,
+			force: true
+		}).catch((err) => {
+			log.warn({
+				err,
+				shareId
+			}, "Failed to remove Session share artifact");
+		});
+	}
+	async loadExpectedSource(sessionKey, expected) {
+		const source = await this.loadSource(sessionKey);
+		if (source.snapshot.sessionId !== expected.expectedSessionId || source.snapshot.lastSeq !== expected.expectedCutoffSeq || source.metadata.updatedAt !== expected.expectedMetadataUpdatedAt) throw new SessionShareSnapshotConflictError();
+		return source;
+	}
+	async loadSource(sessionKey) {
+		const [metadata, snapshot] = await Promise.all([this.source.getMetadata(sessionKey), this.source.getSnapshot(sessionKey)]);
+		if (!metadata || !snapshot || !metadata.sessionId || metadata.sessionId !== snapshot.sessionId) throw new Error("Session not found");
+		return {
+			metadata,
+			snapshot
+		};
+	}
+	buildManifestBase(shareId, source, projection, options) {
+		this.validateMessages(projection.messages);
+		const selected = new Set(options.selectedAttachmentIds);
+		return {
+			schemaVersion: MANIFEST_SCHEMA_VERSION,
+			shareId,
+			source: {
+				sessionId: source.snapshot.sessionId,
+				cutoffSeq: source.snapshot.lastSeq
+			},
+			title: source.metadata.name?.trim() || "Shared conversation",
+			snapshotAt: (/* @__PURE__ */ new Date()).toISOString(),
+			messages: projection.messages.map((message) => ({
+				...message,
+				attachmentIds: message.attachmentIds.filter((id) => selected.has(id))
+			})),
+			toolActivities: options.includeToolActivities ? projection.toolActivities : []
+		};
+	}
+	async createArtifact(shareId, manifestBase, projection, attachmentIds) {
+		const finalDir = this.artifactDir(shareId);
+		const stagedDir = `${finalDir}.staged-${randomUUID()}`;
+		const built = await this.writeArtifact(stagedDir, manifestBase, projection, attachmentIds);
+		try {
+			await rename(stagedDir, finalDir);
+			return built;
+		} catch (error) {
+			await rm(stagedDir, {
+				recursive: true,
+				force: true
+			});
+			throw error;
+		}
+	}
+	async writeArtifact(targetDir, manifestBase, projection, attachmentIds) {
+		const selected = [...new Set(attachmentIds)];
+		if (selected.length > MAX_ATTACHMENT_COUNT) throw new Error(`Select at most ${MAX_ATTACHMENT_COUNT} attachments`);
+		const candidates = new Map(projection.attachmentCandidates.map((candidate) => [candidate.id, candidate]));
+		for (const id of selected) if (!candidates.has(id) || !projection.attachmentUris.has(id)) throw new Error(`Attachment is not part of this session snapshot: ${id}`);
+		await mkdir(join(targetDir, "assets"), { recursive: true });
+		const attachments = [];
+		let totalAttachmentSize = 0;
+		try {
+			for (const id of selected) {
+				const candidate = candidates.get(id);
+				const source = await resolveMediaReference(projection.attachmentUris.get(id));
+				const sourceStat = await stat(source.path);
+				if (!sourceStat.isFile()) throw new Error(`Attachment is not a file: ${candidate.fileName}`);
+				if (sourceStat.size > MAX_ATTACHMENT_BYTES) throw new Error(`Attachment is too large: ${candidate.fileName}`);
+				totalAttachmentSize += sourceStat.size;
+				if (totalAttachmentSize > MAX_TOTAL_ATTACHMENT_BYTES) throw new Error("Selected attachments are too large");
+				const target = join(targetDir, "assets", id);
+				await copyFile(source.path, target);
+				const copied = await stat(target);
+				if (!copied.isFile() || copied.size !== sourceStat.size) throw new Error(`Attachment changed while copying: ${candidate.fileName}`);
+				attachments.push({
+					id,
+					messageId: candidate.messageId,
+					mimeType: publicMimeType(candidate.mimeType),
+					fileName: publicFileName(candidate.fileName),
+					size: copied.size,
+					artifactFileName: id,
+					checksum: await checksumFile(target)
+				});
+			}
+			const manifest = {
+				...manifestBase,
+				attachments
+			};
+			const bytes = Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+			if (bytes.length > MAX_MANIFEST_BYTES) throw new Error("Session share is too large");
+			await writeFile(join(targetDir, "manifest.json"), bytes, { mode: 384 });
+			return {
+				manifest,
+				totalSize: bytes.length + totalAttachmentSize
+			};
+		} catch (error) {
+			await rm(targetDir, {
+				recursive: true,
+				force: true
+			});
+			throw error;
+		}
+	}
+	artifactRelativePath(shareId) {
+		return join("share-artifacts", shareId);
+	}
+	artifactDir(shareId) {
+		return join(resolveStateDir(), this.artifactRelativePath(shareId));
+	}
+	validateMessages(messages) {
+		if (messages.length === 0) throw new Error("Session has no shareable messages");
+		if (messages.length > MAX_SHARE_MESSAGES) throw new Error(`Session has more than ${MAX_SHARE_MESSAGES} shareable messages`);
+	}
+	validateManifestRelations(record, manifest) {
+		if (manifest.messages.length !== record.messageCount || manifest.attachments.length !== record.attachmentCount) throw new Error("Invalid Session share artifact");
+		if (!record.includeToolActivities && manifest.toolActivities.length > 0) throw new Error("Invalid Session share artifact");
+		const attachments = new Map(manifest.attachments.map((attachment) => [attachment.id, attachment]));
+		if (attachments.size !== manifest.attachments.length) throw new Error("Invalid Session share artifact");
+		const messages = new Set(manifest.messages.map((message) => message.id));
+		for (const message of manifest.messages) for (const attachmentId of message.attachmentIds) {
+			const attachment = attachments.get(attachmentId);
+			if (!attachment || attachment.messageId !== message.id) throw new Error("Invalid Session share artifact");
+		}
+		if (manifest.attachments.some((attachment) => !messages.has(attachment.messageId))) throw new Error("Invalid Session share artifact");
+	}
+};
+function publicFileName(value) {
+	return basename(value.replaceAll("\\", "/")).replace(/[\u0000-\u001f\u007f]/g, "_").trim().slice(0, 200) || "attachment";
+}
+function publicMimeType(value) {
+	const normalized = value.split(";")[0]?.trim().toLowerCase() ?? "";
+	return /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/.test(normalized) ? normalized : "application/octet-stream";
+}
+async function checksumFile(path) {
+	const hash = createHash("sha256");
+	for await (const chunk of createReadStream(path)) hash.update(chunk);
+	return hash.digest("hex");
+}
+function isSessionShareMessage(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const message = value;
+	return typeof message.id === "string" && (message.role === "user" || message.role === "assistant") && typeof message.markdown === "string" && typeof message.createdAt === "string" && Array.isArray(message.attachmentIds) && message.attachmentIds.every((id) => typeof id === "string");
+}
+function isSessionShareToolActivity(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const activity = value;
+	return typeof activity.id === "string" && (activity.messageId === void 0 || typeof activity.messageId === "string") && typeof activity.toolName === "string" && (activity.status === "completed" || activity.status === "failed") && typeof activity.createdAt === "string";
+}
+function isSessionShareAttachment(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const attachment = value;
+	return typeof attachment.id === "string" && /^attachment-[a-f0-9]{24}$/.test(attachment.id) && typeof attachment.messageId === "string" && typeof attachment.mimeType === "string" && typeof attachment.fileName === "string" && typeof attachment.size === "number" && attachment.artifactFileName === attachment.id && typeof attachment.checksum === "string" && /^[a-f0-9]{64}$/.test(attachment.checksum);
+}
+//#endregion
+export { SessionShareService, SessionShareSnapshotConflictError };

package/dist/src/share/share-asset-ticket.d.ts

@@ -0,0 +1,7 @@
+export interface TicketedShareRecord {
+    id: string;
+    snapshotRevision: number;
+    assetTicketSecret: string;
+}
+export declare function issueShareAssetTicket(record: TicketedShareRecord, ttlMs: number): string;
+export declare function verifyShareAssetTicket(record: TicketedShareRecord, ticket: string): boolean;

package/dist/src/share/share-asset-ticket.js

@@ -0,0 +1,30 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+//#region src/share/share-asset-ticket.ts
+function issueShareAssetTicket(record, ttlMs) {
+	const payload = Buffer.from(JSON.stringify({
+		shareId: record.id,
+		revision: record.snapshotRevision,
+		expiresAt: Date.now() + ttlMs
+	})).toString("base64url");
+	return `${payload}.${createHmac("sha256", record.assetTicketSecret).update(payload).digest("base64url")}`;
+}
+function verifyShareAssetTicket(record, ticket) {
+	const [payload, signature] = ticket.split(".");
+	if (!payload || !signature) return false;
+	const expected = createHmac("sha256", record.assetTicketSecret).update(payload).digest();
+	let actual;
+	try {
+		actual = Buffer.from(signature, "base64url");
+	} catch {
+		return false;
+	}
+	if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) return false;
+	try {
+		const value = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+		return value.shareId === record.id && value.revision === record.snapshotRevision && typeof value.expiresAt === "number" && Date.now() < value.expiresAt;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { issueShareAssetTicket, verifyShareAssetTicket };

package/dist/src/share/share-landing.d.ts

@@ -1,5 +1,5 @@
 import type { DirectoryListing } from './share-store.js';
-import type { NoteShareRecord, ShareRecord } from './share-types.js';
+import type { NoteShareRecord, SessionShareRecord, ShareRecord } from './share-types.js';
 export interface ShareLandingOgOptions {
     /** Absolute https/http URL of this landing page (for og:url). Omit if non-public. */
     absoluteShareUrl?: string | null;
@@ -10,8 +10,9 @@ export interface ShareLandingOgOptions {
     /** Description override (default: type + size). */
     description?: string;
 }
-/** Lightweight public shell for Note shares. Crawlers get metadata; browsers continue to the SPA preview. */
-export declare function renderNoteShareLandingPage(record: NoteShareRecord, previewUrl: string, options?: {
+/** Lightweight public shell for state-owned snapshots. Crawlers get metadata; browsers continue to the SPA preview. */
+export declare function renderSnapshotShareLandingPage(record: NoteShareRecord | SessionShareRecord, previewUrl: string, options: {
+    label: 'Note' | 'conversation';
     og?: ShareLandingOgOptions;
 }): string;
 /** Render the file download confirmation landing page (does not consume downloadCount). */

package/dist/src/share/share-landing.js

@@ -35,10 +35,10 @@ body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;b
 .empty{text-align:center;color:#94a3b8;padding:2rem}
 `;
 }
-/** Lightweight public shell for Note shares. Crawlers get metadata; browsers continue to the SPA preview. */
-function renderNoteShareLandingPage(record, previewUrl, options) {
+/** Lightweight public shell for state-owned snapshots. Crawlers get metadata; browsers continue to the SPA preview. */
+function renderSnapshotShareLandingPage(record, previewUrl, options) {
 	const title = escapeHtml(record.fileName);
-	const description = escapeHtml(record.description ?? "A Note shared via xopc");
+	const description = escapeHtml(record.description ?? `A ${options.label} shared via xopc`);
 	const target = escapeHtml(previewUrl);
 	return `<!DOCTYPE html>
 <html lang="zh">
@@ -57,7 +57,7 @@ ${renderOgTags({
 <meta http-equiv="refresh" content="0;url=${target}">
 </head>
 <body>
-<p><a href="${target}">Open shared Note</a></p>
+<p><a href="${target}">Open shared ${options.label}</a></p>
 <script>location.replace(${JSON.stringify(previewUrl)})<\/script>
 </body>
 </html>`;
@@ -239,4 +239,4 @@ function renderShareExpiredPage(reason) {
 </html>`;
 }
 //#endregion
-export { renderFolderLandingPage, renderNoteShareLandingPage, renderShareExpiredPage, renderShareLandingPage };
+export { renderFolderLandingPage, renderShareExpiredPage, renderShareLandingPage, renderSnapshotShareLandingPage };

package/dist/src/share/share-store.d.ts

@@ -1,4 +1,4 @@
-import type { ShareRecord, ShareConfig, CreateShareParams, WorkspaceShareRecord, NoteShareRecord, DirectoryShareRecord } from './share-types.js';
+import type { ShareRecord, ShareConfig, CreateShareParams, WorkspaceShareRecord, NoteShareRecord, SessionShareRecord, DirectoryShareRecord } from './share-types.js';
 export interface DirectoryListingEntry {
     name: string;
     /** Workspace/share-relative POSIX path. */
@@ -57,6 +57,31 @@ export declare class ShareStore {
         fileName: string;
     }): NoteShareRecord | null;
     getNoteShares(noteId: string): NoteShareRecord[];
+    createSessionShare(input: {
+        id: string;
+        sourceSessionId: string;
+        cutoffSeq: number;
+        artifactRelativePath: string;
+        artifactSize: number;
+        messageCount: number;
+        attachmentCount?: number;
+        includeToolActivities?: boolean;
+        snapshotRevision?: number;
+        fileName: string;
+        ttlMs?: number;
+        maxViews?: number | null;
+        description?: string;
+        gatewayTokenHash: string;
+    }): SessionShareRecord;
+    getSessionShares(sessionId: string): SessionShareRecord[];
+    updateSessionSnapshot(id: string, patch: {
+        cutoffSeq: number;
+        artifactSize: number;
+        messageCount: number;
+        attachmentCount: number;
+        includeToolActivities: boolean;
+        fileName: string;
+    }): SessionShareRecord | null;
     private persistAndAudit;
     getById(id: string): ShareRecord | null;
     getByToken(token: string): ShareRecord | null;
@@ -112,7 +137,7 @@ export declare class ShareStore {
     private cleanupExpired;
     shutdown(): void;
     private resolveAndValidatePath;
-    private cleanupNoteArtifact;
+    private cleanupStateArtifact;
 }
 export declare function resolveMimeType(fileName: string): string;
 /** HTTP Content-Type with charset for text-like bodies (browser inline preview). */

package/dist/src/share/share-store.js

@@ -254,6 +254,69 @@ var ShareStore = class {
 	getNoteShares(noteId) {
 		return this.getAllShares().filter((record) => record.kind === "note" && record.sourceNoteId === noteId);
 	}
+	createSessionShare(input) {
+		if (!this.config.enabled) throw new Error("Session sharing is disabled");
+		if (this.getActiveShares().length >= this.config.maxActiveShares) throw new Error(`Maximum active shares reached (${this.config.maxActiveShares})`);
+		const ttlMs = input.ttlMs ?? this.config.defaultTtlMs;
+		if (ttlMs < 6e4 || ttlMs > this.config.maxTtlMs) throw new Error(`TTL must be between 60s and ${this.config.maxTtlMs / 1e3}s`);
+		if (input.maxViews !== void 0 && input.maxViews !== null && (input.maxViews < 1 || input.maxViews > 1e3)) throw new Error("maxViews must be between 1 and 1000");
+		const now = /* @__PURE__ */ new Date();
+		const record = {
+			id: input.id,
+			token: randomBytes(32).toString("base64url"),
+			kind: "session",
+			fileName: input.fileName,
+			fileSize: input.artifactSize,
+			mimeType: "application/x-xopc-session",
+			workspaceRelativePath: "",
+			sourceSessionId: input.sourceSessionId,
+			cutoffSeq: input.cutoffSeq,
+			artifactRelativePath: input.artifactRelativePath,
+			messageCount: input.messageCount,
+			attachmentCount: input.attachmentCount ?? 0,
+			includeToolActivities: input.includeToolActivities ?? false,
+			snapshotRevision: input.snapshotRevision ?? 1,
+			assetTicketSecret: randomBytes(32).toString("base64url"),
+			createdAt: now.toISOString(),
+			expiresAt: new Date(now.getTime() + ttlMs).toISOString(),
+			maxViews: input.maxViews ?? null,
+			downloadCount: 0,
+			revoked: false,
+			createdByTokenHash: input.gatewayTokenHash,
+			description: input.description
+		};
+		this.shares.set(record.id, record);
+		this.tokenIndex.set(record.token, record.id);
+		this.persistAndAudit(record, "share.create", `Session share created: ${record.fileName}`, {
+			sourceSessionId: record.sourceSessionId,
+			cutoffSeq: record.cutoffSeq,
+			messageCount: record.messageCount,
+			ttlMs
+		});
+		return record;
+	}
+	getSessionShares(sessionId) {
+		return this.getAllShares().filter((record) => record.kind === "session" && record.sourceSessionId === sessionId);
+	}
+	updateSessionSnapshot(id, patch) {
+		const record = this.shares.get(id);
+		if (!record || record.kind !== "session") return null;
+		record.cutoffSeq = patch.cutoffSeq;
+		record.fileSize = patch.artifactSize;
+		record.messageCount = patch.messageCount;
+		record.attachmentCount = patch.attachmentCount;
+		record.includeToolActivities = patch.includeToolActivities;
+		record.fileName = patch.fileName;
+		record.snapshotRevision += 1;
+		this.persistSync();
+		logShareAudit("share.update", {
+			shareId: id,
+			sourceSessionId: record.sourceSessionId,
+			cutoffSeq: record.cutoffSeq,
+			snapshotRevision: record.snapshotRevision
+		}, `Session share snapshot updated: ${record.fileName}`);
+		return record;
+	}
 	persistAndAudit(record, event, message, extra) {
 		this.persistSync();
 		logShareAudit(event, {
@@ -455,7 +518,7 @@ var ShareStore = class {
 		const record = this.shares.get(id);
 		if (!record) return false;
 		record.revoked = true;
-		this.cleanupNoteArtifact(record);
+		this.cleanupStateArtifact(record);
 		this.invalidateListingCache(id);
 		this.persistSync();
 		logShareAudit("share.revoke", {
@@ -471,7 +534,7 @@ var ShareStore = class {
 			const record = this.shares.get(id);
 			if (record && !record.revoked) {
 				record.revoked = true;
-				this.cleanupNoteArtifact(record);
+				this.cleanupStateArtifact(record);
 				this.invalidateListingCache(id);
 				count++;
 				logShareAudit("share.revoke", {
@@ -489,7 +552,7 @@ var ShareStore = class {
 		let count = 0;
 		for (const record of this.shares.values()) if (!record.revoked && now >= new Date(record.expiresAt).getTime()) {
 			record.revoked = true;
-			this.cleanupNoteArtifact(record);
+			this.cleanupStateArtifact(record);
 			this.invalidateListingCache(record.id);
 			count++;
 		}
@@ -583,7 +646,7 @@ var ShareStore = class {
 		let removed = 0;
 		for (const [id, record] of this.shares) {
 			const expiredMs = now - new Date(record.expiresAt).getTime();
-			if (expiredMs >= 0) this.cleanupNoteArtifact(record);
+			if (expiredMs >= 0) this.cleanupStateArtifact(record);
 			if (expiredMs > EXPIRED_RETENTION_MS) {
 				this.shares.delete(id);
 				this.tokenIndex.delete(record.token);
@@ -629,14 +692,14 @@ var ShareStore = class {
 		if (relToRoot.startsWith("..") || relToRoot.split(/[/\\]/).includes("..")) throw new Error("Path is outside workspace");
 		return abs;
 	}
-	cleanupNoteArtifact(record) {
-		if (record.kind !== "note") return;
+	cleanupStateArtifact(record) {
+		if (record.kind !== "note" && record.kind !== "session") return;
 		const expected = join("share-artifacts", record.id);
 		if (record.artifactRelativePath !== expected) {
 			log.warn({
 				shareId: record.id,
 				artifactRelativePath: record.artifactRelativePath
-			}, "Skipped unsafe Note share artifact cleanup path");
+			}, "Skipped unsafe share artifact cleanup path");
 			return;
 		}
 		rm(join(resolveStateDir(), expected), {
@@ -646,7 +709,7 @@ var ShareStore = class {
 			log.warn({
 				err,
 				shareId: record.id
-			}, "Failed to clean Note share artifact");
+			}, "Failed to clean share artifact");
 		});
 	}
 };

package/dist/src/share/share-types.d.ts

@@ -1,5 +1,5 @@
 export type WorkspaceShareKind = 'file' | 'directory';
-export type ShareKind = WorkspaceShareKind | 'note';
+export type ShareKind = WorkspaceShareKind | 'note' | 'session';
 export interface ShareDirectoryMeta {
     /** 'browse' shows a file tree; 'zip-only' hides structure and only offers ZIP. */
     mode: 'browse' | 'zip-only';
@@ -81,8 +81,23 @@ export interface NoteShareRecord extends ShareRecordBase {
     assetTicketSecret: string;
     directory?: undefined;
 }
+export interface SessionShareRecord extends ShareRecordBase {
+    kind: 'session';
+    /** Sessions are state-owned objects, not workspace paths. */
+    workspaceRelativePath: '';
+    sourceSessionId: string;
+    cutoffSeq: number;
+    artifactRelativePath: string;
+    messageCount: number;
+    attachmentCount: number;
+    includeToolActivities: boolean;
+    snapshotRevision: number;
+    /** Private HMAC key for short-lived public asset tickets. */
+    assetTicketSecret: string;
+    directory?: undefined;
+}
 export type WorkspaceShareRecord = FileShareRecord | DirectoryShareRecord;
-export type ShareRecord = WorkspaceShareRecord | NoteShareRecord;
+export type ShareRecord = WorkspaceShareRecord | NoteShareRecord | SessionShareRecord;
 export interface CreateShareParams {
     /** Workspace-relative file path. */
     path: string;

package/dist/src/share/share-url.js

@@ -1,5 +1,5 @@
+import { enumerateLanGatewayCandidates } from "../gateway/host.js";
 import { loadTunnelState } from "../tunnel/tunnel-state.js";
-import { resolveLanGatewayUrl } from "../tunnel/tunnel-qr.js";
 //#region src/share/share-url.ts
 function resolveShareUrl(token, ctx) {
 	const tunnelState = loadTunnelState();
@@ -32,7 +32,7 @@ function resolveShareUrl(token, ctx) {
 	};
 }
 function buildLanUrl(host, port, path) {
-	const lanBase = resolveLanGatewayUrl(host, port);
+	const lanBase = isLoopbackHost(host) ? null : enumerateLanGatewayCandidates(port).find((candidate) => candidate.address === host)?.url ?? `http://${host.includes(":") ? `[${host}]` : host}:${port}`;
 	if (!lanBase) return null;
 	return `${lanBase.replace(/\/+$/, "")}${path}`;
 }