@sparkelf/dsh-group-chat 0.5.0 → 0.5.1

package/lib/index.js

@@ -601,6 +601,173 @@ const textOfContent = (content) => {
 	if (!Array.isArray(content)) return "";
 	return content.filter((block) => typeof block === "object" && block !== null).filter((block) => block.type === "text" && typeof block.text === "string").map((block) => block.text).join("");
 };
+//#endregion
+//#region src/session-id.ts
+/**
+* The room/session binding, shared by both halves of the plugin.
+*
+* The browser half needs it to open a room's Session; the host half needs it to create and
+* recognize one. It lives in its own module because the two halves are built for different
+* runtimes: importing it from the host entry would drag the whole server side into the client
+* bundle, which the build's platform guard refuses — correctly, since none of it can run there.
+*
+* @module @sparkelf/dsh-group-chat/session-id
+*/
+/**
+* Every room session id starts with this, so a room's session is recognizable after a restart
+* and an ordinary session never matches.
+*
+* The binding lives in the id rather than in `SessionHeader` because the header carries no
+* free-form metadata field.
+*/
+const ROOM_SESSION_PREFIX = "group-room-";
+/** Deterministic session id for a room. */
+const roomSessionId = (roomId) => `${ROOM_SESSION_PREFIX}${roomId}`;
+/** Reads the room a session is bound to, or `undefined` for an ordinary session. */
+const roomIdOfSession = (session) => {
+	if (typeof session !== "object" || session === null) return void 0;
+	const id = session.id;
+	if (typeof id !== "string" || !id.startsWith("group-room-")) return void 0;
+	const roomId = id.slice(11);
+	return roomId.length > 0 ? roomId : void 0;
+};
+//#endregion
+//#region src/session-maintenance.ts
+/**
+* Maintenance for the sessions a room owns in one workspace.
+*
+* A room has exactly one canonical Session, addressed by {@link roomSessionId}. Before
+* this module existed, a host restart could instead leave behind throwaway
+* `session-<uuid>` records in the room's project directory: the controller's
+* `create({ sessionId })` mints a new Session whenever the named one has already
+* started a turn, and the room code treated that minted identity as a failed open and
+* retried on every discovery poll. The result was thousands of idle Session
+* directories, all with the same `cwd`, which slowed every `session/list`.
+*
+* The cleanup endpoint therefore works on the *physical* project directory rather
+* than on a plugin-owned index: legacy garbage was never indexed, and a workspace
+* upgraded from an affected build must be able to find it. Candidate selection is
+* intentionally narrow — only minted `session-<uuid>` records, only in the named
+* directory, never the canonical room Session, never another room's Session, and
+* never a subagent child. A cleanup run cannot delete an ordinary named Session or a
+* conversation someone deliberately created.
+*
+* @module @sparkelf/dsh-group-chat/session-maintenance
+*/
+/**
+* A Session identity minted by the controller for a conversation that asked for a
+* different named id. Only this shape is ever a cleanup candidate.
+*/
+const isMintedSessionId = (sessionId) => /^session-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u.test(sessionId);
+/** Whether a stored Session is a throwaway record this room's cleanup may touch. */
+const isRoomSubSession = (record, directory, primarySessionId, protectedSessionIds = /* @__PURE__ */ new Set()) => {
+	const header = record.header;
+	if (header.cwd !== directory) return false;
+	if (header.id === primarySessionId) return false;
+	if (protectedSessionIds.has(header.id)) return false;
+	if (header.id.startsWith("group-room-")) return false;
+	if (header.origin === "subagent" || header.parentSession !== void 0) return false;
+	return isMintedSessionId(header.id);
+};
+/**
+* The JSONL backend's readable project directory name.
+*
+* Mirrors the storage layout documented by `dsh-session-persistence-jsonl`: separators
+* collapse to one `-`, unsafe code units use `~XXXX`, and the result is bounded for
+* filesystem component limits. The plugin needs the physical directory only to purge;
+* a backend whose layout differs must keep its `root` unset so purge is refused.
+*/
+const roomProjectKey = (cwd) => {
+	if (cwd.length === 0) throw new Error("cannot encode an empty project path");
+	let readable = "";
+	let separatorRun = false;
+	for (let index = 0; index < cwd.length; index += 1) {
+		const code = cwd.charCodeAt(index);
+		const character = String.fromCharCode(code);
+		if (character === "/" || character === "\\" || character === ":") {
+			if (!separatorRun) readable += "-";
+			separatorRun = true;
+		} else if (character !== "~" && /^[A-Za-z0-9._-]$/u.test(character)) {
+			readable += character;
+			separatorRun = false;
+		} else {
+			readable += `~${code.toString(16).toUpperCase().padStart(4, "0")}`;
+			separatorRun = false;
+		}
+	}
+	return `--${(readable.replace(/^-+/u, "") || "root").slice(0, 251)}--`;
+};
+/** The JSONL backend's escaped single path segment. */
+const sessionIdSegment = (sessionId) => {
+	if (sessionId.length === 0) throw new Error("cannot encode an empty session id");
+	if (sessionId === ".") return "~002E";
+	if (sessionId === "..") return "~002E~002E";
+	let out = "";
+	for (let index = 0; index < sessionId.length; index += 1) {
+		const code = sessionId.charCodeAt(index);
+		const character = String.fromCharCode(code);
+		if (character !== "~" && /^[A-Za-z0-9._-]$/u.test(character)) out += character;
+		else out += `~${code.toString(16).toUpperCase().padStart(4, "0")}`;
+	}
+	return out;
+};
+/** The physical directory one stored Session owns, validated to stay under `root`. */
+const roomSessionDirectory = (root, directory, sessionId) => {
+	const rootPath = resolve(root);
+	const target = resolve(join(rootPath, roomProjectKey(directory), sessionIdSegment(sessionId)));
+	if (target === rootPath || !target.startsWith(`${rootPath}${sep}`)) throw new Error(`session directory escapes the configured root: ${sessionId}`);
+	return target;
+};
+/**
+* Find and, when asked, archive or delete a room's throwaway Sessions.
+*
+* `dryRun` defaults to true and `purge` to false, so the safe call reports before it
+* changes anything. An archive run writes DSH's official archive marker, which removes
+* the Sessions from grouping surfaces without touching their files; a purge run removes
+* the physical directories and leaves the canonical room Session alone.
+*/
+const cleanupRoomSessions = async (input) => {
+	const dryRun = input.dryRun !== false;
+	const purge = !dryRun && input.purge === true;
+	const mode = dryRun ? "report" : purge ? "purge" : "archive";
+	if (purge && (input.persistence.root === void 0 || input.persistence.root.length === 0)) throw new Error("the session backend exposes no physical root; purge is unavailable");
+	const protectedIds = new Set(input.protectedSessionIds ?? []);
+	const records = await input.persistence.list();
+	const candidates = records.filter((record) => isRoomSubSession(record, input.directory, input.primarySessionId, protectedIds)).map((record) => record.header.id);
+	if (mode === "archive" && input.archive === void 0) throw new Error("the workspace registry exposes no archive marker; archive is unavailable");
+	const archived = [];
+	const removed = [];
+	const errors = [];
+	if (mode !== "report") for (const sessionId of candidates) try {
+		if (mode === "archive") {
+			await input.archive?.archiveSession(sessionId, { stopActivity: true });
+			archived.push(sessionId);
+			continue;
+		}
+		const target = roomSessionDirectory(input.persistence.root, input.directory, sessionId);
+		await rm(target, {
+			recursive: true,
+			force: true
+		});
+		removed.push(sessionId);
+	} catch (error) {
+		errors.push({
+			sessionId,
+			message: error instanceof Error ? error.message : String(error)
+		});
+	}
+	return {
+		roomId: input.roomId,
+		directory: input.directory,
+		primarySessionId: input.primarySessionId,
+		mode,
+		scanned: records.length,
+		candidates,
+		archived,
+		removed,
+		errors
+	};
+};
 /**
 * Wrapper for built-in http.js to emulate the browser XMLHttpRequest object.
 *
@@ -8841,36 +9008,6 @@ const openRoomStream = (options) => {
 	};
 };
 //#endregion
-//#region src/session-id.ts
-/**
-* The room/session binding, shared by both halves of the plugin.
-*
-* The browser half needs it to open a room's Session; the host half needs it to create and
-* recognize one. It lives in its own module because the two halves are built for different
-* runtimes: importing it from the host entry would drag the whole server side into the client
-* bundle, which the build's platform guard refuses — correctly, since none of it can run there.
-*
-* @module @sparkelf/dsh-group-chat/session-id
-*/
-/**
-* Every room session id starts with this, so a room's session is recognizable after a restart
-* and an ordinary session never matches.
-*
-* The binding lives in the id rather than in `SessionHeader` because the header carries no
-* free-form metadata field.
-*/
-const ROOM_SESSION_PREFIX = "group-room-";
-/** Deterministic session id for a room. */
-const roomSessionId = (roomId) => `${ROOM_SESSION_PREFIX}${roomId}`;
-/** Reads the room a session is bound to, or `undefined` for an ordinary session. */
-const roomIdOfSession = (session) => {
-	if (typeof session !== "object" || session === null) return void 0;
-	const id = session.id;
-	if (typeof id !== "string" || !id.startsWith("group-room-")) return void 0;
-	const roomId = id.slice(11);
-	return roomId.length > 0 ? roomId : void 0;
-};
-//#endregion
 //#region src/index.ts
 const name = "group-chat";
 /**
@@ -8987,8 +9124,99 @@ const modelKeyOf = (room) => [
 	room.model ?? "",
 	room.reasoningEffort ?? ""
 ].join("|");
+/** Whether two selections address the same route and effort. */
+const sameModelSelection = (left, right) => left.provider === right.provider && left.model === right.model && (left.reasoningEffort ?? "") === (right.reasoningEffort ?? "");
+/**
+* Apply a room's model without changing the user's deployment default.
+*
+* `sessionController.selectModel` saves the selection as `agent-default-model` in the
+* background. That is right for a user choosing in the composer, but a room applying
+* its stored model (especially on startup) would otherwise overwrite the user's last
+* explicit choice. Capture the default first and restore it after the background save
+* has had a chance to land.
+*/
+const selectRoomModel = async (ctx, request) => {
+	const defaultModel = ctx.agentDefaultModel;
+	const before = defaultModel?.currentSelection();
+	const changesDefault = before !== void 0 && !sameModelSelection(before, {
+		provider: request.provider,
+		model: request.model,
+		...request.reasoningEffort === void 0 ? {} : { reasoningEffort: request.reasoningEffort }
+	});
+	await ctx.sessionController.selectModel(request);
+	if (!changesDefault || before === void 0 || defaultModel === void 0) return;
+	await new Promise((resolve) => setTimeout(resolve, 60));
+	try {
+		await defaultModel.saveSelection(before);
+	} catch {}
+};
+/** Whether a controller failure is the precise "this session is not stored" answer. */
+const isSessionNotFound = (error) => typeof error === "object" && error !== null && error.code === "session/not-found";
+/**
+* Read an optional host service without making it a required injection.
+*
+* The direct property is the usual path on a fully composed host. `ctx.get` is the fallback
+* for a host that exposes a lazily mounted service as a registry entry only; tests and
+* minimal hosts may provide neither, which must read as "service unavailable" rather than
+* as a crash while opening a room.
+*/
+const hostService = (ctx, key) => {
+	try {
+		const direct = ctx[key];
+		if (direct !== void 0) return direct;
+	} catch {}
+	const get = ctx.get;
+	if (typeof get !== "function") return void 0;
+	try {
+		return get.call(ctx, key);
+	} catch {
+		return;
+	}
+};
+/**
+* The model route a Session's own log records, or `''` when it has never selected one.
+*
+* A resolved room Session keeps the selection it was created with; a restarted host must
+* not silently leave it on a room whose configured model has since changed. Reading the
+* last `model/selection` event avoids a write on every open.
+*/
+const sessionModelKey = (session) => {
+	const events = session.snapshotEvents();
+	for (let index = events.length - 1; index >= 0; index -= 1) {
+		const event = events[index];
+		if (event?.type !== "model/selection") continue;
+		if (typeof event.data?.provider !== "string" || typeof event.data?.model !== "string") continue;
+		return [
+			event.data.provider,
+			event.data.model,
+			typeof event.data.reasoningEffort === "string" ? event.data.reasoningEffort : ""
+		].join("|");
+	}
+	return "";
+};
+/**
+* Resolves the DSH session backing one room.
+*
+* A room has exactly one Session, addressed by {@link roomSessionId}. Opening it must
+* therefore be a resolve-or-create, never a create alone:
+*
+* - `sessionController.create({ sessionId })` reuses the named Session only while it is
+*   **blank**. A room that has ever run a turn — every room does, because of the warm-up
+*   turn — is no longer blank, so the controller mints a fresh `session-<uuid>` in the
+*   same cwd instead of returning the room's Session.
+* - Checking only `ctx.sessions.get()` misses a persisted Session after a host restart,
+*   because the registry is process-local. The first open would then mint a replacement;
+*   the plugin's lookup by the deterministic id still returns nothing, the open fails, and
+*   the three-second discovery poll repeats the mint forever. That is how one room grew to
+*   16,004 Session directories.
+*
+* Resolving first also fixes the archived case: it loads the real Session and lets the
+* room unarchive it before running a turn, instead of creating an unrelated replacement.
+*/
 var RoomSessions = class {
 	ctx;
+	/** One in-flight open per room, so two discovery passes cannot race the same identity. */
+	pending = /* @__PURE__ */ new Map();
 	constructor(ctx) {
 		this.ctx = ctx;
 	}
@@ -8996,36 +9224,105 @@ var RoomSessions = class {
 		return this.ctx.sessions.get(roomSessionId(roomId));
 	}
 	/**
-	* Open a room's session, creating it through the controller on first use.
+	* Open a room's persisted Session, or create it on the one occasion it is absent.
 	*
-	* Creation goes through the controller rather than the session registry because only
-	* the controller persists the session and binds its agent. A registry-only session is
-	* an in-memory handle that cannot be resumed, so nothing would ever run in the room.
+	* @param roomId - the room the session belongs to.
+	* @param room - the room's configured scope and model.
+	* @returns the canonical room Session, with an agent bound to it.
 	*/
 	async ensure(roomId, room) {
 		const existing = this.existing(roomId);
 		if (existing !== void 0) return existing;
+		const pending = this.pending.get(roomId);
+		if (pending !== void 0) return pending;
+		const opening = this.open(roomId, room).finally(() => {
+			if (this.pending.get(roomId) === opening) this.pending.delete(roomId);
+		});
+		this.pending.set(roomId, opening);
+		return opening;
+	}
+	async open(roomId, room) {
 		const sessionId = roomSessionId(roomId);
 		const directory = resolveRoomDirectory(roomId, room.cwd);
 		await mkdir(directory, { recursive: true });
-		await this.ctx.sessionController.create({
+		const resumed = await this.resolvePersisted(sessionId, directory);
+		if (resumed !== void 0) {
+			await this.installRoomModel(resumed, room, false);
+			return resumed;
+		}
+		const created = await this.ctx.sessionController.create({
 			sessionId,
 			cwd: directory,
 			...room.agentPreset === void 0 ? {} : { agentPreset: room.agentPreset }
 		});
-		if (room.modelProvider !== void 0 && room.model !== void 0) await this.ctx.sessionController.selectModel({
-			sessionId,
-			provider: room.modelProvider,
+		if (created.sessionId !== sessionId) {
+			await this.archiveReplacement(created.sessionId);
+			throw new Error(`group-chat asked for room session ${sessionId} but the controller opened ${created.sessionId}`);
+		}
+		const session = this.existing(roomId);
+		if (session === void 0) throw new Error(`group-chat could not open a session for room ${roomId}`);
+		await this.installRoomModel(session, room, true);
+		return session;
+	}
+	/** Load a persisted room Session, or `undefined` only when the controller denies it exists. */
+	async resolvePersisted(sessionId, directory) {
+		let resolved;
+		try {
+			resolved = await this.ctx.sessionController.resolveAgent(sessionId);
+		} catch (error) {
+			if (isSessionNotFound(error)) return void 0;
+			throw error;
+		}
+		if ("agent" in resolved) {
+			const session = resolved.agent.session;
+			if (session.id !== sessionId) throw new Error(`group-chat resolved room session ${sessionId} as ${session.id}`);
+			if (session.header.cwd !== void 0 && session.header.cwd !== directory) this.ctx.logger?.warn?.("[group-chat] room session directory differs from the room configuration; keeping the existing history", sessionId, session.header.cwd, directory);
+			await this.unarchiveRoomSession(sessionId);
+			return session;
+		}
+		if (isSessionNotFound(resolved.error)) return void 0;
+		throw new Error(`group-chat could not resolve room session ${sessionId}: ${resolved.error instanceof Error ? resolved.error.message : String(resolved.error)}`);
+	}
+	/** Install the room's model when the Session's log does not already carry it. */
+	async installRoomModel(session, room, strict) {
+		if (room.modelProvider === void 0 || room.model === void 0) return;
+		const target = {
+			modelProvider: room.modelProvider,
 			model: room.model,
 			...room.reasoningEffort === void 0 ? {} : { reasoningEffort: room.reasoningEffort }
-		});
-		const created = this.existing(roomId);
-		if (created === void 0) throw new Error(`group-chat could not open a session for room ${roomId}`);
-		return created;
+		};
+		if (sessionModelKey(session) === modelKeyOf(target)) return;
+		try {
+			await selectRoomModel(this.ctx, {
+				sessionId: session.id,
+				provider: room.modelProvider,
+				model: room.model,
+				...room.reasoningEffort === void 0 ? {} : { reasoningEffort: room.reasoningEffort }
+			});
+		} catch (error) {
+			if (strict) throw error;
+			this.ctx.logger?.warn?.("[group-chat] keeping the room session on its existing model", session.id, error);
+		}
+	}
+	/** The workspace registry's archive surface, looked up lazily because it is optional. */
+	get archiveRegistry() {
+		return hostService(this.ctx, "workspaceRegistry");
+	}
+	/** Hide a replacement the controller minted instead of honoring the room id. */
+	async archiveReplacement(sessionId) {
+		try {
+			await this.archiveRegistry?.archiveSession(sessionId, { stopActivity: true });
+		} catch {}
+	}
+	/** Lift an archive marker from the room's canonical Session before its first turn. */
+	async unarchiveRoomSession(sessionId) {
+		try {
+			await this.archiveRegistry?.unarchiveSession?.(sessionId);
+		} catch {}
 	}
 };
 /** The height bounds the region enforces, exported so the client and host agree on them. */
-const SIDEBAR_HEIGHT_MIN = 120;
+const SIDEBAR_HEIGHT_MIN = 80;
 const SIDEBAR_HEIGHT_MAX = 1200;
 /** Reads the preferences file, treating every failure as "nothing saved yet". */
 const readPreferences = async (env = process.env) => {
@@ -9045,7 +9342,7 @@ const readPreferences = async (env = process.env) => {
 	}
 };
 /** Clamps a requested height into the range the region can actually draw. */
-const clampSidebarHeight = (value) => Math.min(SIDEBAR_HEIGHT_MAX, Math.max(120, Math.round(value)));
+const clampSidebarHeight = (value) => Math.min(SIDEBAR_HEIGHT_MAX, Math.max(80, Math.round(value)));
 /**
 * Writes the preferences file atomically.
 *
@@ -9336,7 +9633,7 @@ const activate = (ctx, target) => {
 		if (room.modelProvider === null || room.modelProvider === void 0) return;
 		if (room.model === null || room.model === void 0) return;
 		try {
-			await ctx.sessionController.selectModel({
+			await selectRoomModel(ctx, {
 				sessionId: session.id,
 				provider: room.modelProvider,
 				model: room.model,
@@ -9560,6 +9857,56 @@ const activate = (ctx, target) => {
 			const url = new URL(request.url ?? "/", "http://dsh.internal");
 			const route = url.pathname.slice(19).replace(/^\/+/u, "");
 			try {
+				if (request.method === "GET" && route === "attachment-materialize") {
+					const attachmentId = url.searchParams.get("attachmentId") ?? "";
+					const name = url.searchParams.get("name") ?? "attachment";
+					const bytes = Number(url.searchParams.get("bytes") ?? "0");
+					if (!attachmentId.startsWith("sha256:") || !Number.isSafeInteger(bytes) || bytes <= 0) throw new RouteRefusal("attachment-materialize requires a sha256 attachmentId and byte count", 400);
+					const attachments = hostService(ctx, "attachments");
+					if (attachments === void 0) throw new RouteRefusal("attachment store is unavailable", 501);
+					const chunks = [];
+					for await (const chunk of attachments.readFileStream({
+						attachmentId,
+						name,
+						bytes
+					})) chunks.push(chunk);
+					const safeName = basename(name).replace(/[^\p{L}\p{N}._-]+/gu, "_") || "attachment";
+					const directory = join(resolveWorkspaceRoot(), ".dsh-attachment-preview");
+					await mkdir(directory, { recursive: true });
+					const relativePath = ".dsh-attachment-preview/" + attachmentId.slice(7, 19) + "-" + safeName;
+					await writeFile(join(resolveWorkspaceRoot(), relativePath), Buffer.concat(chunks));
+					response.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+					response.end(JSON.stringify({
+						path: relativePath,
+						name: safeName
+					}));
+					return;
+				}
+				if (request.method === "GET" && route === "attachment-preview") {
+					const attachmentId = url.searchParams.get("attachmentId") ?? "";
+					const name = url.searchParams.get("name") ?? "attachment";
+					const bytes = Number(url.searchParams.get("bytes") ?? "0");
+					if (!attachmentId.startsWith("sha256:") || !Number.isSafeInteger(bytes) || bytes <= 0) throw new RouteRefusal("attachment-preview requires a sha256 attachmentId and byte count", 400);
+					const attachments = hostService(ctx, "attachments");
+					if (attachments === void 0) throw new RouteRefusal("attachment store is unavailable", 501);
+					const chunks = [];
+					for await (const chunk of attachments.readFileStream({
+						attachmentId,
+						name,
+						bytes
+					})) chunks.push(chunk);
+					const body = Buffer.concat(chunks);
+					const extension = name.toLowerCase().split(".").pop() ?? "";
+					const contentType = extension === "png" ? "image/png" : extension === "jpg" || extension === "jpeg" ? "image/jpeg" : extension === "gif" ? "image/gif" : extension === "webp" ? "image/webp" : extension === "pdf" ? "application/pdf" : extension === "md" ? "text/markdown; charset=utf-8" : extension === "json" ? "application/json; charset=utf-8" : extension === "txt" || extension === "log" ? "text/plain; charset=utf-8" : "application/octet-stream";
+					response.writeHead(200, {
+						"content-type": contentType,
+						"content-length": String(body.length),
+						"content-disposition": `inline; filename*=UTF-8''${encodeURIComponent(name)}`,
+						"cache-control": "private, no-store"
+					});
+					response.end(body);
+					return;
+				}
 				const payload = await readJsonBody(request);
 				const body = await handleRoomRequest(route, request.method ?? "GET", payload, url, backend, runtimes, closeRoom, ctx, pendingQuotes);
 				response.writeHead(200, { "content-type": "application/json; charset=utf-8" });
@@ -9626,6 +9973,44 @@ const activate = (ctx, target) => {
 const handleRoomRequest = async (route, httpMethod, payload, url, backend, runtimes, closeRoom, ctx, pendingQuotes) => {
 	const [resource, roomId, ...rest] = route.split("/").filter((part) => part.length > 0);
 	const action = rest.join("/");
+	/**
+	* Batch maintenance for the throwaway Sessions an older build minted under a room.
+	*
+	* Report is the default; archiving needs `dryRun: false`, and deleting additionally needs
+	* `purge: true` plus `confirm` equal to the room id. The canonical room Session is never a
+	* candidate, and neither is another room's Session or a subagent child.
+	*/
+	const cleanupMatch = /^rooms\/([^/]+)\/sessions\/cleanup$/u.exec(route);
+	if (cleanupMatch !== null && cleanupMatch[1] !== void 0) {
+		if (httpMethod !== "POST") throw new RouteRefusal("session cleanup accepts POST", 405);
+		const targetRoomId = decodeURIComponent(cleanupMatch[1]);
+		let room;
+		try {
+			room = (await backend.listRooms()).find((candidate) => candidate.id === targetRoomId);
+		} catch {}
+		const requestedDirectory = payload?.["directory"];
+		if (requestedDirectory !== void 0 && (typeof requestedDirectory !== "string" || !isAbsolute(requestedDirectory))) throw new RouteRefusal("directory must be an absolute path", 400);
+		const configuredDirectory = requestedDirectory ?? (room === void 0 ? void 0 : resolveRoomDirectory(targetRoomId, room.cwd));
+		if (configuredDirectory === void 0) throw new RouteRefusal("room is no longer listed; pass the room directory explicitly to clean its session records", 404);
+		const directory = await realpath(configuredDirectory).catch(() => configuredDirectory);
+		if (resolve(directory) === resolve(resolveWorkspaceRoot())) throw new RouteRefusal("refusing to clean sessions whose cwd is the workspace root", 400);
+		const persistence = hostService(ctx, "sessionPersistence");
+		if (persistence === void 0) throw new RouteRefusal("session persistence is unavailable on this host", 501);
+		const archive = hostService(ctx, "workspaceRegistry");
+		const dryRun = payload?.["dryRun"] !== false;
+		const purge = payload?.["purge"] === true;
+		if (purge && payload?.["confirm"] !== targetRoomId) throw new RouteRefusal("purging session directories requires confirm set to the room id", 400);
+		return cleanupRoomSessions({
+			roomId: targetRoomId,
+			directory,
+			primarySessionId: roomSessionId(targetRoomId),
+			persistence,
+			...archive === void 0 ? {} : { archive },
+			protectedSessionIds: [...runtimes.keys()].map((openRoomId) => roomSessionId(openRoomId)),
+			dryRun,
+			purge
+		});
+	}
 	if (resource === "rooms" && roomId === "messages" && action === "search") {
 		if (httpMethod !== "GET") throw new RouteRefusal("message search accepts GET", 405);
 		const query = url.searchParams.get("query") ?? "";
@@ -10194,4 +10579,4 @@ const readJsonBody = async (req) => {
 */
 const MAX_UPLOAD_BYTES = 16777216;
 //#endregion
-export { BackendError, Config, DEFAULT_CREDENTIAL_REF, GROUP_CHAT_ROUTE, GroupChatBackend, MANAGED_ENV, POLL_INTERVAL_MS, ROOM_SESSION_PREFIX, RoomEventTracker, SIDEBAR_HEIGHT_MAX, SIDEBAR_HEIGHT_MIN, activate, apply, clampSidebarHeight, inject, isAgentReply, isLocalUserMessage, isRuntimeInjectedData, isTransportFailure, isUserMessageData, lastRoomEvent, mentionedMemberIds, mentionsOf, messageId, name, publishableReply, readPreferences, resolveServerTarget, resolveWorkspaceRoot, roomIdOfSession, roomSessionId, senderId, shouldTriggerAgent, speakerPrefix, textOfContent, withSpeakerPrefix, writePreferences };
+export { BackendError, Config, DEFAULT_CREDENTIAL_REF, GROUP_CHAT_ROUTE, GroupChatBackend, MANAGED_ENV, POLL_INTERVAL_MS, ROOM_SESSION_PREFIX, RoomEventTracker, RoomSessions, SIDEBAR_HEIGHT_MAX, SIDEBAR_HEIGHT_MIN, activate, apply, clampSidebarHeight, handleRoomRequest, inject, isAgentReply, isLocalUserMessage, isRuntimeInjectedData, isTransportFailure, isUserMessageData, lastRoomEvent, mentionedMemberIds, mentionsOf, messageId, name, publishableReply, readPreferences, resolveServerTarget, resolveWorkspaceRoot, roomIdOfSession, roomSessionId, senderId, shouldTriggerAgent, speakerPrefix, textOfContent, withSpeakerPrefix, writePreferences };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sparkelf/dsh-group-chat",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Human-agent group chat for DataOps-managed DSH workspaces: rooms broadcast to every member, and only a member's own @mention wakes that member's agent.",
   "type": "module",
   "main": "./lib/index.js",
@@ -40,11 +40,6 @@
     "cordis.patch.yml",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsdown",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "vitest run --root ../.. packages/group-chat/tests"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/SparkElf/dsh-plugins-plus.git",
@@ -96,5 +91,10 @@
     "@deepseek-ai/schemastery": "^3.18.2",
     "ws": "^8.18.0",
     "socket.io-client": "^4.8.1"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run --root ../.. packages/group-chat/tests"
   }
-}
+}