@kodelyth/matrix 2026.5.39 → 2026.5.42

package/dist/subagent-hooks-api-Dr_xnMRG.js

@@ -0,0 +1,170 @@
+import { t as __exportAll } from "./rolldown-runtime-DUslC3ob.js";
+import { a as resolveMatrixTargetIdentity } from "./target-ids-Bsazo8si.js";
+import { a as listBindingsForAccount, c as resolveBindingKey, i as listAllBindings, n as getMatrixThreadBindingManager, o as removeBindingRecord } from "./thread-bindings-shared-fvfP7jVs.js";
+import { DEFAULT_ACCOUNT_ID } from "klaw/plugin-sdk/account-id";
+import { getSessionBindingService } from "klaw/plugin-sdk/conversation-binding-runtime";
+import { formatThreadBindingDisabledError, formatThreadBindingSpawnDisabledError, resolveThreadBindingSpawnPolicy } from "klaw/plugin-sdk/conversation-runtime";
+import { normalizeOptionalString } from "klaw/plugin-sdk/string-coerce-runtime";
+//#region extensions/matrix/src/matrix/subagent-hooks.ts
+var subagent_hooks_exports = /* @__PURE__ */ __exportAll({
+	handleMatrixSubagentDeliveryTarget: () => handleMatrixSubagentDeliveryTarget,
+	handleMatrixSubagentEnded: () => handleMatrixSubagentEnded,
+	handleMatrixSubagentSpawning: () => handleMatrixSubagentSpawning
+});
+function summarizeError(err) {
+	if (err instanceof Error) return err.message;
+	if (typeof err === "string") return err;
+	return "error";
+}
+function resolveMatrixBindingThreadId(binding) {
+	const { conversationId, parentConversationId } = binding.conversation;
+	return parentConversationId && parentConversationId !== conversationId ? conversationId : void 0;
+}
+function resolveMatrixBindingDeliveryOrigin(binding, fallbackAccountId) {
+	const boundRoomId = binding.conversation.parentConversationId ?? binding.conversation.conversationId;
+	const threadId = resolveMatrixBindingThreadId(binding);
+	return {
+		channel: "matrix",
+		accountId: binding.conversation.accountId ?? fallbackAccountId,
+		to: `room:${boundRoomId}`,
+		...threadId ? { threadId } : {}
+	};
+}
+async function handleMatrixSubagentSpawning(api, event) {
+	if (!event.threadRequested) return;
+	if (event.requester?.channel?.trim().toLowerCase() !== "matrix") return;
+	const accountId = normalizeOptionalString(event.requester?.accountId) || DEFAULT_ACCOUNT_ID;
+	const policy = resolveThreadBindingSpawnPolicy({
+		cfg: api.config,
+		channel: "matrix",
+		accountId,
+		kind: "subagent"
+	});
+	if (!policy.enabled) return {
+		status: "error",
+		error: formatThreadBindingDisabledError({
+			channel: policy.channel,
+			accountId: policy.accountId,
+			kind: "subagent"
+		})
+	};
+	if (!policy.spawnEnabled) return {
+		status: "error",
+		error: formatThreadBindingSpawnDisabledError({
+			channel: policy.channel,
+			accountId: policy.accountId,
+			kind: "subagent"
+		})
+	};
+	const rawTo = normalizeOptionalString(event.requester?.to) ?? "";
+	const matrixTarget = rawTo ? resolveMatrixTargetIdentity(rawTo) : null;
+	const roomId = matrixTarget?.kind === "room" ? matrixTarget.id : "";
+	if (!roomId) return {
+		status: "error",
+		error: "Cannot create Matrix thread binding: no room target in spawn request (requester.to must be a Matrix room ID)."
+	};
+	const bindingService = getSessionBindingService();
+	const capabilities = bindingService.getCapabilities({
+		channel: "matrix",
+		accountId
+	});
+	if (!capabilities.adapterAvailable || !capabilities.bindSupported) return {
+		status: "error",
+		error: `No Matrix session binding adapter available for account "${accountId}". Is the Matrix channel running?`
+	};
+	if (!capabilities.placements.includes("child")) return {
+		status: "error",
+		error: `Matrix session binding adapter for account "${accountId}" does not support child thread bindings.`
+	};
+	try {
+		return {
+			status: "ok",
+			threadBindingReady: true,
+			deliveryOrigin: resolveMatrixBindingDeliveryOrigin(await bindingService.bind({
+				targetSessionKey: event.childSessionKey,
+				targetKind: "subagent",
+				conversation: {
+					channel: "matrix",
+					accountId,
+					conversationId: roomId
+				},
+				placement: "child",
+				metadata: {
+					agentId: event.agentId?.trim() || void 0,
+					label: normalizeOptionalString(event.label) || void 0,
+					boundBy: "system"
+				}
+			}), accountId)
+		};
+	} catch (err) {
+		return {
+			status: "error",
+			error: `Matrix thread bind failed: ${summarizeError(err)}`
+		};
+	}
+}
+async function handleMatrixSubagentEnded(event) {
+	const accountId = normalizeOptionalString(event.accountId) || void 0;
+	const matching = (accountId ? listBindingsForAccount(accountId) : listAllBindings()).filter((entry) => entry.targetSessionKey === event.targetSessionKey && entry.targetKind === "subagent");
+	const removedBindingKeys = /* @__PURE__ */ new Set();
+	if (event.sendFarewell) {
+		const bindingService = getSessionBindingService();
+		const reason = normalizeOptionalString(event.reason) || "subagent-ended";
+		for (const binding of matching) {
+			const bindingId = resolveBindingKey(binding);
+			if ((await bindingService.unbind({
+				bindingId,
+				reason
+			})).some((entry) => entry.bindingId === bindingId)) removedBindingKeys.add(bindingId);
+		}
+	}
+	const affectedAccountIds = /* @__PURE__ */ new Set();
+	for (const binding of matching) {
+		if (removedBindingKeys.has(resolveBindingKey(binding))) continue;
+		if (removeBindingRecord(binding)) affectedAccountIds.add(binding.accountId);
+	}
+	for (const acctId of affectedAccountIds) await getMatrixThreadBindingManager(acctId)?.persist();
+}
+function handleMatrixSubagentDeliveryTarget(event) {
+	if (!event.expectsCompletionMessage) return;
+	if (event.requesterOrigin?.channel?.trim().toLowerCase() !== "matrix") return;
+	const requesterAccountId = normalizeOptionalString(event.requesterOrigin?.accountId);
+	const requesterThreadId = event.requesterOrigin?.threadId != null && event.requesterOrigin.threadId !== "" ? String(event.requesterOrigin.threadId).trim() : "";
+	const bindings = (requesterAccountId ? listBindingsForAccount(requesterAccountId) : listAllBindings()).filter((entry) => entry.targetSessionKey === event.childSessionKey && entry.targetKind === "subagent");
+	if (bindings.length === 0) return;
+	let binding;
+	if (requesterThreadId) binding = bindings.find((entry) => entry.conversationId === requesterThreadId && (!requesterAccountId || entry.accountId === requesterAccountId));
+	if (!binding && bindings.length === 1) binding = bindings[0];
+	if (!binding) return;
+	const roomId = binding.parentConversationId ?? binding.conversationId;
+	const threadId = binding.parentConversationId && binding.parentConversationId !== binding.conversationId ? binding.conversationId : void 0;
+	return { origin: {
+		channel: "matrix",
+		accountId: binding.accountId,
+		to: `room:${roomId}`,
+		...threadId ? { threadId } : {}
+	} };
+}
+//#endregion
+//#region extensions/matrix/subagent-hooks-api.ts
+let matrixSubagentHooksPromise = null;
+function loadMatrixSubagentHooksModule() {
+	matrixSubagentHooksPromise ??= Promise.resolve().then(() => subagent_hooks_exports);
+	return matrixSubagentHooksPromise;
+}
+function registerMatrixSubagentHooks(api) {
+	api.on("subagent_spawning", async (event) => {
+		const { handleMatrixSubagentSpawning } = await loadMatrixSubagentHooksModule();
+		return await handleMatrixSubagentSpawning(api, event);
+	});
+	api.on("subagent_ended", async (event) => {
+		const { handleMatrixSubagentEnded } = await loadMatrixSubagentHooksModule();
+		await handleMatrixSubagentEnded(event);
+	});
+	api.on("subagent_delivery_target", async (event) => {
+		const { handleMatrixSubagentDeliveryTarget } = await loadMatrixSubagentHooksModule();
+		return handleMatrixSubagentDeliveryTarget(event);
+	});
+}
+//#endregion
+export { subagent_hooks_exports as a, handleMatrixSubagentSpawning as i, handleMatrixSubagentDeliveryTarget as n, handleMatrixSubagentEnded as r, registerMatrixSubagentHooks as t };

package/dist/subagent-hooks-api.js

@@ -0,0 +1,2 @@
+import { i as handleMatrixSubagentSpawning, n as handleMatrixSubagentDeliveryTarget, r as handleMatrixSubagentEnded, t as registerMatrixSubagentHooks } from "./subagent-hooks-api-Dr_xnMRG.js";
+export { handleMatrixSubagentDeliveryTarget, handleMatrixSubagentEnded, handleMatrixSubagentSpawning, registerMatrixSubagentHooks };

package/dist/sync-state-Bx0gPaGA.js

@@ -0,0 +1,12 @@
+//#region extensions/matrix/src/matrix/sync-state.ts
+function isMatrixReadySyncState(state) {
+	return state === "PREPARED" || state === "SYNCING" || state === "CATCHUP";
+}
+function isMatrixDisconnectedSyncState(state) {
+	return state === "RECONNECTING" || state === "ERROR" || state === "STOPPED";
+}
+function isMatrixTerminalSyncState(state) {
+	return state === "STOPPED";
+}
+//#endregion
+export { isMatrixReadySyncState as n, isMatrixTerminalSyncState as r, isMatrixDisconnectedSyncState as t };

package/dist/target-ids-Bsazo8si.js

@@ -0,0 +1,77 @@
+import { normalizeLowercaseStringOrEmpty } from "klaw/plugin-sdk/string-coerce-runtime";
+//#region extensions/matrix/src/matrix/target-ids.ts
+const MATRIX_PREFIX = "matrix:";
+const ROOM_PREFIX = "room:";
+const CHANNEL_PREFIX = "channel:";
+const USER_PREFIX = "user:";
+function stripKnownPrefixes(raw, prefixes) {
+	let normalized = raw.trim();
+	while (normalized) {
+		const lowered = normalizeLowercaseStringOrEmpty(normalized);
+		const matched = prefixes.find((prefix) => lowered.startsWith(prefix));
+		if (!matched) return normalized;
+		normalized = normalized.slice(matched.length).trim();
+	}
+	return normalized;
+}
+function resolveMatrixTargetIdentity(raw) {
+	const normalized = stripKnownPrefixes(raw, [MATRIX_PREFIX]);
+	if (!normalized) return null;
+	const lowered = normalizeLowercaseStringOrEmpty(normalized);
+	if (lowered.startsWith(USER_PREFIX)) {
+		const id = normalized.slice(5).trim();
+		return id ? {
+			kind: "user",
+			id
+		} : null;
+	}
+	if (lowered.startsWith(ROOM_PREFIX)) {
+		const id = normalized.slice(5).trim();
+		return id ? {
+			kind: "room",
+			id
+		} : null;
+	}
+	if (lowered.startsWith(CHANNEL_PREFIX)) {
+		const id = normalized.slice(8).trim();
+		return id ? {
+			kind: "room",
+			id
+		} : null;
+	}
+	if (isMatrixQualifiedUserId(normalized)) return {
+		kind: "user",
+		id: normalized
+	};
+	return {
+		kind: "room",
+		id: normalized
+	};
+}
+function isMatrixQualifiedUserId(raw) {
+	const trimmed = raw.trim();
+	return trimmed.startsWith("@") && trimmed.includes(":");
+}
+function normalizeMatrixResolvableTarget(raw) {
+	return stripKnownPrefixes(raw, [
+		MATRIX_PREFIX,
+		ROOM_PREFIX,
+		CHANNEL_PREFIX
+	]);
+}
+function normalizeMatrixMessagingTarget(raw) {
+	return stripKnownPrefixes(raw, [
+		MATRIX_PREFIX,
+		ROOM_PREFIX,
+		CHANNEL_PREFIX,
+		USER_PREFIX
+	]) || void 0;
+}
+function resolveMatrixDirectUserId(params) {
+	if (params.chatType !== "direct") return;
+	if (!normalizeMatrixResolvableTarget(params.to ?? "").startsWith("!")) return;
+	const userId = stripKnownPrefixes(params.from ?? "", [MATRIX_PREFIX, USER_PREFIX]);
+	return isMatrixQualifiedUserId(userId) ? userId : void 0;
+}
+//#endregion
+export { resolveMatrixTargetIdentity as a, resolveMatrixDirectUserId as i, normalizeMatrixMessagingTarget as n, normalizeMatrixResolvableTarget as r, isMatrixQualifiedUserId as t };

package/dist/test-api.js

@@ -0,0 +1,4 @@
+import { r as setMatrixRuntime } from "./runtime-B-Fyrmxo.js";
+import { t as matrixPlugin } from "./channel-C0kCyTNB.js";
+import { t as MatrixClient } from "./sdk-Jhq7mLtD.js";
+export { MatrixClient, matrixPlugin, setMatrixRuntime };

package/dist/thread-binding-api-IGU0-L70.js

@@ -0,0 +1,17 @@
+import { a as resolveMatrixTargetIdentity } from "./target-ids-Bsazo8si.js";
+import { normalizeOptionalString } from "klaw/plugin-sdk/string-coerce-runtime";
+//#region extensions/matrix/src/thread-binding-api.ts
+const defaultTopLevelPlacement = "child";
+function resolveMatrixInboundConversation(params) {
+	const rawTarget = params.to?.trim() || params.conversationId?.trim() || "";
+	const target = rawTarget ? resolveMatrixTargetIdentity(rawTarget) : null;
+	const parentConversationId = target?.kind === "room" ? target.id : void 0;
+	const threadId = params.threadId != null ? normalizeOptionalString(String(params.threadId)) : void 0;
+	if (threadId) return {
+		conversationId: threadId,
+		...parentConversationId ? { parentConversationId } : {}
+	};
+	return parentConversationId ? { conversationId: parentConversationId } : null;
+}
+//#endregion
+export { resolveMatrixInboundConversation as n, defaultTopLevelPlacement as t };

package/dist/thread-binding-api.js

@@ -0,0 +1,2 @@
+import { n as resolveMatrixInboundConversation, t as defaultTopLevelPlacement } from "./thread-binding-api-IGU0-L70.js";
+export { defaultTopLevelPlacement, resolveMatrixInboundConversation as resolveInboundConversation };

package/dist/thread-bindings-FjAZmDUP.js

@@ -0,0 +1,352 @@
+import { a as listBindingsForAccount, c as resolveBindingKey, f as setMatrixThreadBindingManagerEntry, h as toSessionBindingRecord, l as resolveEffectiveBindingExpiry, m as toMatrixBindingTargetKind, o as removeBindingRecord, r as getMatrixThreadBindingManagerEntry, t as deleteMatrixThreadBindingManagerEntry, u as setBindingRecord } from "./thread-bindings-shared-fvfP7jVs.js";
+import { i as resolveMatrixStateFilePath, t as claimCurrentTokenStorageState } from "./storage-nyO0DOFE.js";
+import { a as sendMessageMatrix } from "./send-CJunc6QM.js";
+import { normalizeOptionalString } from "klaw/plugin-sdk/string-coerce-runtime";
+import { registerSessionBindingAdapter, resolveThreadBindingFarewellText, unregisterSessionBindingAdapter } from "klaw/plugin-sdk/thread-bindings-session-runtime";
+import path from "node:path";
+import { readJsonFileWithFallback, writeJsonFileAtomically } from "klaw/plugin-sdk/json-store";
+import { resolveAgentIdFromSessionKey } from "klaw/plugin-sdk/session-key-runtime";
+//#region extensions/matrix/src/matrix/thread-bindings.ts
+const STORE_VERSION = 1;
+const THREAD_BINDINGS_SWEEP_INTERVAL_MS = 6e4;
+const TOUCH_PERSIST_DELAY_MS = 3e4;
+function resolveBindingsPath(params) {
+	return resolveMatrixStateFilePath({
+		auth: params.auth,
+		accountId: params.accountId,
+		env: params.env,
+		stateDir: params.stateDir,
+		filename: "thread-bindings.json"
+	});
+}
+async function loadBindingsFromDisk(filePath, accountId) {
+	const { value } = await readJsonFileWithFallback(filePath, null);
+	if (value?.version !== STORE_VERSION || !Array.isArray(value.bindings)) return [];
+	const loaded = [];
+	for (const entry of value.bindings) {
+		const conversationId = normalizeOptionalString(entry?.conversationId);
+		const parentConversationId = normalizeOptionalString(entry?.parentConversationId);
+		const targetSessionKey = normalizeOptionalString(entry?.targetSessionKey) ?? "";
+		if (!conversationId || !targetSessionKey) continue;
+		const boundAt = typeof entry?.boundAt === "number" && Number.isFinite(entry.boundAt) ? Math.floor(entry.boundAt) : Date.now();
+		const lastActivityAt = typeof entry?.lastActivityAt === "number" && Number.isFinite(entry.lastActivityAt) ? Math.floor(entry.lastActivityAt) : boundAt;
+		loaded.push({
+			accountId,
+			conversationId,
+			...parentConversationId ? { parentConversationId } : {},
+			targetKind: entry?.targetKind === "subagent" ? "subagent" : "acp",
+			targetSessionKey,
+			agentId: normalizeOptionalString(entry?.agentId) || void 0,
+			label: normalizeOptionalString(entry?.label) || void 0,
+			boundBy: normalizeOptionalString(entry?.boundBy) || void 0,
+			boundAt,
+			lastActivityAt: Math.max(lastActivityAt, boundAt),
+			idleTimeoutMs: typeof entry?.idleTimeoutMs === "number" && Number.isFinite(entry.idleTimeoutMs) ? Math.max(0, Math.floor(entry.idleTimeoutMs)) : void 0,
+			maxAgeMs: typeof entry?.maxAgeMs === "number" && Number.isFinite(entry.maxAgeMs) ? Math.max(0, Math.floor(entry.maxAgeMs)) : void 0
+		});
+	}
+	return loaded;
+}
+function toStoredBindingsState(bindings) {
+	return {
+		version: STORE_VERSION,
+		bindings: [...bindings].toSorted((a, b) => a.boundAt - b.boundAt)
+	};
+}
+async function persistBindingsSnapshot(filePath, bindings) {
+	await writeJsonFileAtomically(filePath, toStoredBindingsState(bindings));
+	claimCurrentTokenStorageState({ rootDir: path.dirname(filePath) });
+}
+function buildMatrixBindingIntroText(params) {
+	const introText = normalizeOptionalString(params.metadata?.introText);
+	if (introText) return introText;
+	const label = normalizeOptionalString(params.metadata?.label);
+	const agentId = normalizeOptionalString(params.metadata?.agentId) || resolveAgentIdFromSessionKey(params.targetSessionKey);
+	return `⚙️ ${label || agentId || "session"} session active. Messages here go directly to this session.`;
+}
+async function sendBindingMessage(params) {
+	const trimmed = params.text.trim();
+	if (!trimmed) return null;
+	return (await sendMessageMatrix(`room:${params.roomId}`, trimmed, {
+		cfg: params.cfg,
+		client: params.client,
+		accountId: params.accountId,
+		...params.threadId ? { threadId: params.threadId } : {}
+	})).messageId || null;
+}
+async function sendFarewellMessage(params) {
+	const roomId = params.record.parentConversationId ?? params.record.conversationId;
+	const idleTimeoutMs = typeof params.record.idleTimeoutMs === "number" ? params.record.idleTimeoutMs : params.defaultIdleTimeoutMs;
+	const maxAgeMs = typeof params.record.maxAgeMs === "number" ? params.record.maxAgeMs : params.defaultMaxAgeMs;
+	const farewellText = resolveThreadBindingFarewellText({
+		reason: params.reason,
+		idleTimeoutMs,
+		maxAgeMs
+	});
+	await sendBindingMessage({
+		cfg: params.cfg,
+		client: params.client,
+		accountId: params.accountId,
+		roomId,
+		threadId: params.record.parentConversationId && params.record.parentConversationId !== params.record.conversationId ? params.record.conversationId : void 0,
+		text: farewellText
+	}).catch(() => {});
+}
+async function createMatrixThreadBindingManager(params) {
+	if (params.auth.accountId !== params.accountId) throw new Error(`Matrix thread binding account mismatch: requested ${params.accountId}, auth resolved ${params.auth.accountId}`);
+	const filePath = resolveBindingsPath({
+		auth: params.auth,
+		accountId: params.accountId,
+		env: params.env,
+		stateDir: params.stateDir
+	});
+	const existingEntry = getMatrixThreadBindingManagerEntry(params.accountId);
+	if (existingEntry) {
+		if (existingEntry.filePath === filePath) return existingEntry.manager;
+		existingEntry.manager.stop();
+	}
+	const loaded = await loadBindingsFromDisk(filePath, params.accountId);
+	for (const record of loaded) setBindingRecord(record);
+	let persistQueue = Promise.resolve();
+	const enqueuePersist = (bindings) => {
+		const snapshot = bindings ?? listBindingsForAccount(params.accountId);
+		const next = persistQueue.catch(() => {}).then(async () => {
+			await persistBindingsSnapshot(filePath, snapshot);
+		});
+		persistQueue = next;
+		return next;
+	};
+	const persist = async () => await enqueuePersist();
+	const persistSafely = (reason, bindings) => {
+		enqueuePersist(bindings).catch((err) => {
+			params.logVerboseMessage?.(`matrix: failed persisting thread bindings account=${params.accountId} action=${reason}: ${String(err)}`);
+		});
+	};
+	const defaults = {
+		idleTimeoutMs: params.idleTimeoutMs,
+		maxAgeMs: params.maxAgeMs
+	};
+	let persistTimer = null;
+	const schedulePersist = (delayMs) => {
+		if (persistTimer) return;
+		persistTimer = setTimeout(() => {
+			persistTimer = null;
+			persistSafely("delayed-touch");
+		}, delayMs);
+		persistTimer.unref?.();
+	};
+	const updateBindingsBySessionKey = (input) => {
+		const targetSessionKey = input.targetSessionKey.trim();
+		if (!targetSessionKey) return [];
+		const now = Date.now();
+		const nextBindings = listBindingsForAccount(params.accountId).filter((entry) => entry.targetSessionKey === targetSessionKey).map((entry) => input.update(entry, now));
+		if (nextBindings.length === 0) return [];
+		for (const entry of nextBindings) setBindingRecord(entry);
+		persistSafely(input.persistReason);
+		return nextBindings;
+	};
+	const manager = {
+		accountId: params.accountId,
+		getIdleTimeoutMs: () => defaults.idleTimeoutMs,
+		getMaxAgeMs: () => defaults.maxAgeMs,
+		persist,
+		getByConversation: ({ conversationId, parentConversationId }) => listBindingsForAccount(params.accountId).find((entry) => {
+			if (entry.conversationId !== conversationId.trim()) return false;
+			if (!parentConversationId) return true;
+			return (entry.parentConversationId ?? "") === parentConversationId.trim();
+		}),
+		listBySessionKey: (targetSessionKey) => listBindingsForAccount(params.accountId).filter((entry) => entry.targetSessionKey === targetSessionKey.trim()),
+		listBindings: () => listBindingsForAccount(params.accountId),
+		touchBinding: (bindingId, at) => {
+			const record = listBindingsForAccount(params.accountId).find((entry) => resolveBindingKey(entry) === bindingId.trim());
+			if (!record) return null;
+			const nextRecord = {
+				...record,
+				lastActivityAt: typeof at === "number" && Number.isFinite(at) ? Math.max(record.lastActivityAt, Math.floor(at)) : Date.now()
+			};
+			setBindingRecord(nextRecord);
+			schedulePersist(TOUCH_PERSIST_DELAY_MS);
+			return nextRecord;
+		},
+		setIdleTimeoutBySessionKey: ({ targetSessionKey, idleTimeoutMs }) => {
+			return updateBindingsBySessionKey({
+				targetSessionKey,
+				persistReason: "idle-timeout-update",
+				update: (entry, now) => ({
+					...entry,
+					idleTimeoutMs: Math.max(0, Math.floor(idleTimeoutMs)),
+					lastActivityAt: now
+				})
+			});
+		},
+		setMaxAgeBySessionKey: ({ targetSessionKey, maxAgeMs }) => {
+			return updateBindingsBySessionKey({
+				targetSessionKey,
+				persistReason: "max-age-update",
+				update: (entry, now) => ({
+					...entry,
+					maxAgeMs: Math.max(0, Math.floor(maxAgeMs)),
+					lastActivityAt: now
+				})
+			});
+		},
+		stop: () => {
+			if (sweepTimer) clearInterval(sweepTimer);
+			if (persistTimer) {
+				clearTimeout(persistTimer);
+				persistTimer = null;
+				persistSafely("shutdown-flush");
+			}
+			unregisterSessionBindingAdapter({
+				channel: "matrix",
+				accountId: params.accountId,
+				adapter: sessionBindingAdapter
+			});
+			if (getMatrixThreadBindingManagerEntry(params.accountId)?.manager === manager) deleteMatrixThreadBindingManagerEntry(params.accountId);
+			for (const record of listBindingsForAccount(params.accountId)) removeBindingRecord(record);
+		}
+	};
+	let sweepTimer = null;
+	const removeRecords = (records) => {
+		if (records.length === 0) return [];
+		return records.map((record) => removeBindingRecord(record)).filter((record) => Boolean(record));
+	};
+	const sendFarewellMessages = async (removed, reason) => {
+		await Promise.all(removed.map(async (record) => {
+			await sendFarewellMessage({
+				cfg: params.cfg,
+				client: params.client,
+				accountId: params.accountId,
+				record,
+				defaultIdleTimeoutMs: defaults.idleTimeoutMs,
+				defaultMaxAgeMs: defaults.maxAgeMs,
+				reason: typeof reason === "function" ? reason(record) : reason
+			});
+		}));
+	};
+	const unbindRecords = async (records, reason) => {
+		const removed = removeRecords(records);
+		if (removed.length === 0) return [];
+		await persist();
+		await sendFarewellMessages(removed, reason);
+		return removed.map((record) => toSessionBindingRecord(record, defaults));
+	};
+	const sessionBindingAdapter = {
+		channel: "matrix",
+		accountId: params.accountId,
+		capabilities: {
+			placements: ["current", "child"],
+			bindSupported: true,
+			unbindSupported: true
+		},
+		bind: async (input) => {
+			const conversationId = input.conversation.conversationId.trim();
+			const parentConversationId = normalizeOptionalString(input.conversation.parentConversationId);
+			const targetSessionKey = input.targetSessionKey.trim();
+			if (!conversationId || !targetSessionKey) return null;
+			let boundConversationId = conversationId;
+			let boundParentConversationId = parentConversationId;
+			const introText = buildMatrixBindingIntroText({
+				metadata: input.metadata,
+				targetSessionKey
+			});
+			if (input.placement === "child") {
+				const roomId = parentConversationId || conversationId;
+				const rootEventId = await sendBindingMessage({
+					cfg: params.cfg,
+					client: params.client,
+					accountId: params.accountId,
+					roomId,
+					text: introText
+				});
+				if (!rootEventId) return null;
+				boundConversationId = rootEventId;
+				boundParentConversationId = roomId;
+			}
+			const now = Date.now();
+			const record = {
+				accountId: params.accountId,
+				conversationId: boundConversationId,
+				...boundParentConversationId ? { parentConversationId: boundParentConversationId } : {},
+				targetKind: toMatrixBindingTargetKind(input.targetKind),
+				targetSessionKey,
+				agentId: normalizeOptionalString(input.metadata?.agentId) || resolveAgentIdFromSessionKey(targetSessionKey),
+				label: normalizeOptionalString(input.metadata?.label) || void 0,
+				boundBy: normalizeOptionalString(input.metadata?.boundBy) || "system",
+				boundAt: now,
+				lastActivityAt: now,
+				idleTimeoutMs: defaults.idleTimeoutMs,
+				maxAgeMs: defaults.maxAgeMs
+			};
+			setBindingRecord(record);
+			await persist();
+			if (input.placement === "current" && introText) {
+				const roomId = boundParentConversationId || boundConversationId;
+				const threadId = boundParentConversationId && boundParentConversationId !== boundConversationId ? boundConversationId : void 0;
+				await sendBindingMessage({
+					cfg: params.cfg,
+					client: params.client,
+					accountId: params.accountId,
+					roomId,
+					threadId,
+					text: introText
+				}).catch(() => {});
+			}
+			return toSessionBindingRecord(record, defaults);
+		},
+		listBySession: (targetSessionKey) => manager.listBySessionKey(targetSessionKey).map((record) => toSessionBindingRecord(record, defaults)),
+		resolveByConversation: (ref) => {
+			const record = manager.getByConversation({
+				conversationId: ref.conversationId,
+				parentConversationId: ref.parentConversationId
+			});
+			return record ? toSessionBindingRecord(record, defaults) : null;
+		},
+		touch: (bindingId, at) => {
+			manager.touchBinding(bindingId, at);
+		},
+		unbind: async (input) => {
+			return await unbindRecords(listBindingsForAccount(params.accountId).filter((record) => {
+				if (input.bindingId?.trim()) return resolveBindingKey(record) === input.bindingId.trim();
+				if (input.targetSessionKey?.trim()) return record.targetSessionKey === input.targetSessionKey.trim();
+				return false;
+			}), input.reason);
+		}
+	};
+	registerSessionBindingAdapter(sessionBindingAdapter);
+	if (params.enableSweeper !== false) {
+		sweepTimer = setInterval(() => {
+			const now = Date.now();
+			const expired = listBindingsForAccount(params.accountId).map((record) => ({
+				record,
+				lifecycle: resolveEffectiveBindingExpiry({
+					record,
+					defaultIdleTimeoutMs: defaults.idleTimeoutMs,
+					defaultMaxAgeMs: defaults.maxAgeMs
+				})
+			})).filter((entry) => typeof entry.lifecycle.expiresAt === "number" && entry.lifecycle.expiresAt <= now && Boolean(entry.lifecycle.reason));
+			if (expired.length === 0) return;
+			const reasonByBindingKey = new Map(expired.map(({ record, lifecycle }) => [resolveBindingKey(record), lifecycle.reason]));
+			(async () => {
+				const removed = removeRecords(expired.map(({ record }) => record));
+				if (removed.length === 0) return;
+				for (const record of removed) {
+					const reason = reasonByBindingKey.get(resolveBindingKey(record));
+					params.logVerboseMessage?.(`matrix: auto-unbinding ${record.conversationId} due to ${reason}`);
+				}
+				await persist();
+				await sendFarewellMessages(removed, (record) => reasonByBindingKey.get(resolveBindingKey(record)));
+			})().catch((err) => {
+				params.logVerboseMessage?.(`matrix: failed auto-unbinding expired bindings account=${params.accountId}: ${String(err)}`);
+			});
+		}, THREAD_BINDINGS_SWEEP_INTERVAL_MS);
+		sweepTimer.unref?.();
+	}
+	setMatrixThreadBindingManagerEntry(params.accountId, {
+		filePath,
+		manager
+	});
+	return manager;
+}
+//#endregion
+export { createMatrixThreadBindingManager as t };

package/dist/thread-bindings-runtime.js

@@ -0,0 +1,2 @@
+import { d as setMatrixThreadBindingIdleTimeoutBySessionKey, p as setMatrixThreadBindingMaxAgeBySessionKey } from "./thread-bindings-shared-fvfP7jVs.js";
+export { setMatrixThreadBindingIdleTimeoutBySessionKey, setMatrixThreadBindingMaxAgeBySessionKey };